Configurar fornecedores de identidade

Controlo de acesso explica o que um fornecedor faz. Esta página é a ligação: os valores exatos que cada um pede e onde os encontrar.

O URI de redirecionamento vem primeiro

Todos os fornecedores, sem exceção, precisam de um valor registado do lado deles: o URL para onde devolvem o utilizador depois do início de sessão.

O painel mostra o valor exato em cada fornecedor que abrires, em Acesso → Início de sessão, com um botão de copiar. Usa-o — não o escrevas à mão.

Microsoft — contas profissionais ou escolares

Usa o fornecedor Entra ID. Cobre as contas alojadas num diretório Microsoft (tu@a-tua-empresa.com), não os endereços pessoais de Outlook ou Hotmail.

1. No portal do Azure, vai a Microsoft Entra ID → Registos de aplicações → Novo registo.
2. Em URI de redirecionamento, escolhe Web e cola o URL de callback do painel.
3. Copia o ID de aplicação (cliente) e o ID de diretório (inquilino) da página de descrição geral.
4. Em Certificados e segredos → Novo segredo de cliente, cria um segredo e copia o seu valor de imediato: o Azure nunca mais o mostra.
5. No ConnXL, adiciona o fornecedor Entra, cola o ID de cliente e o de inquilino, e aponta o segredo de cliente ao teu próprio cofre.

Quem pode iniciar sessão é uma escolha à parte nesse fornecedor:

• Apenas a minha organização Microsoft — o emissor fica fixado ao teu inquilino. Quem estiver de fora é recusado antes de qualquer outra regra ser verificada.
• Qualquer organização Microsoft — aceita diretórios de outras empresas, sujeito às tuas regras de audiência. Exige duas coisas no teu registo de aplicação que o ConnXL não consegue definir nem detetar: o registo tem de aceitar contas de qualquer diretório organizacional (multi-tenant) e pedir o claim opcional xms_edov no token de acesso (Configuração de token → Adicionar claim opcional). Sem o primeiro, a Microsoft recusa por si própria os inícios de sessão externos; sem o segundo, todos os inícios de sessão são recusados do nosso lado, porque esse claim é o único sinal de que um email pertence mesmo a quem o apresenta.

Microsoft — contas pessoais

Usa o fornecedor Conta pessoal Microsoft para endereços de outlook.com, hotmail.com e live.com. Não estão em nenhum diretório Entra, por isso o fornecedor Entra nunca as aceitará.

A configuração é igual à anterior com uma diferença: em Novo registo, escolhe como tipos de conta suportados Apenas contas pessoais Microsoft (ou «qualquer diretório organizacional e contas pessoais Microsoft» se quiseres ambas as populações). Não há emissor para introduzir: todas as contas pessoais Microsoft vivem num único diretório da Microsoft, e o ConnXL fixa esse emissor por ti.

Microsoft — qualquer conta

Usa o fornecedor Microsoft (qualquer conta) quando os teus utilizadores misturam diretórios de trabalho/escola e contas pessoais, e queres um único botão de início de sessão para todos. Não há tenant nem emissor a introduzir: o início de sessão passa pelo endpoint common da Microsoft, e o ConnXL verifica o emissor de cada token contra o tenant em que esse mesmo token foi emitido.

A configuração é o mesmo registo de aplicação de cima, com dois ajustes ambos obrigatórios (o ConnXL não consegue definir nem detetar nenhum deles, e errar num falha como um erro opaco da Microsoft):

1. Em Novo registo (ou depois em Autenticação → Tipos de conta suportados), escolhe Contas em qualquer diretório organizacional e contas pessoais Microsoft. Qualquer escolha mais estreita faz com que a própria Microsoft recuse uma das duas classes de conta.
2. Em Configuração de token → Adicionar afirmação opcional → ID, adiciona xms_edov. Os emails de contas de trabalho só são aceites quando a Microsoft atesta o proprietário do domínio; sem a afirmação, todo o início de sessão com conta de trabalho é recusado do nosso lado (as contas pessoais não são afetadas: o endereço é a identidade verificada da conta).

Google

Usa o fornecedor Google. Não há emissor para introduzir: a Google tem exatamente um, partilhado por todas as contas Google.

1. Na consola do Google Cloud, vai a APIs e serviços → Credenciais → Criar credenciais → ID de cliente OAuth.
2. Tipo de aplicação Aplicação Web; adiciona o URL de callback em URIs de redirecionamento autorizados.
3. Copia o ID de cliente e o segredo de cliente.

O equivalente à escolha «quem pode iniciar sessão» da Microsoft vive do lado da Google, em Ecrã de consentimento OAuth → Tipo de utilizador:

• Interno — apenas contas da tua organização do Google Workspace.
• Externo — qualquer conta Google da internet. Enquanto a app estiver em Teste tens um limite de 100 utilizadores de teste nomeados; publicá-la remove-o.

Qualquer outro fornecedor (OIDC genérico)

Usa o fornecedor OpenID Connect para tudo o resto. Não tem limite: liga o Okta e o Auth0 e o teu próprio Keycloak lado a lado, cada um com o seu botão de início de sessão.

Precisa de três coisas: o URL do emissor, um ID de cliente e um segredo de cliente. O ConnXL lê o documento /.well-known/openid-configuration do emissor para descobrir os endpoints de autorização, token e JWKS, por isso nunca os introduzes.

O emissor tem de ser um URL https:// com host: um domínio simples é recusado. O seletor Configurar para, ao lado do campo, muda o exemplo para a forma do teu fornecedor:

Qualquer outro fornecedor conforme ao standard funciona da mesma maneira: se publicar um documento de descoberta, o ConnXL consegue usá-lo.

Âmbitos

Deixa a lista de âmbitos vazia a não ser que o teu fornecedor precise de mais do que os predefinidos. O ConnXL pede sempre o necessário para identificar o utilizador; âmbitos extra só servem quando o teu IdP exige um explícito para entregar o claim do email.

Segurança ao nível da linha (troca de token)

Tudo o que vem acima serve para pôr alguém com sessão iniciada. Esta secção é sobre o que acontece a seguir: levar essa identidade até à tua própria base de dados, para que uma consulta devolva as linhas dessa pessoa e de mais ninguém.

O modo de autenticação Troca de token de início de sessão de uma ligação HTTP torna isso possível. Em vez de reencaminhar o token da Microsoft tal como está, o agente emite um JWT de curta duração a partir da identidade que acabou de validar, assina-o com um segredo que tu forneces, e envia-o como bearer token em cada pedido que a função faz.

O token emitido leva sub, email e name do utilizador do Excel com sessão iniciada, mais role, aud, iss, iat e exp. O PostgREST — a API REST que o Supabase gera sobre a tua base de dados — e o Hasura aceitam exatamente esta forma, por isso as tuas políticas de Row-Level Security aplicam-se por utilizador: cada pedido vindo de uma célula chega como a pessoa que escreveu a fórmula, e não como uma única conta de serviço partilhada.

Qual dos dois modos de utilizador escolher

• user_token — reencaminhamento direto. Escolhe-o quando a tua API valida os tokens da Microsoft por si própria: já tem o emissor, a audiência e as chaves de assinatura configurados, e lê a identidade de quem chama diretamente do token que o agente reencaminha.
• user_token_exchange — troca de token. Escolhe-o quando a tua API valida os seus próprios JWT e não sabe nada da Microsoft: PostgREST, Supabase, Hasura, ou qualquer serviço que verifique um segredo HS256 partilhado. O agente é a ponte entre os dois mundos.
• Ambos os modos enviam a credencial como Authorization: Bearer <token>. Se a tua API a lê de outro cabeçalho, indica esse nome no campo userTokenHeader da ligação: o token passa então a ser enviado sem prefixo nesse cabeçalho. Deixa-o vazio para o comportamento predefinido.

Receita: linhas por utilizador a partir do Supabase

1. Encontra o segredo de assinatura. No teu painel do Supabase, vai a Project Settings → API → JWT Secret. É esse o segredo com que o PostgREST verifica cada token que recebe.
2. Guarda-o como referência. Põe o valor no teu próprio cofre de segredos e aponta-lhe o campo exchangeSecret da ligação — secret://env/SUPABASE_JWT_SECRET, ou qualquer um dos outros backends listados em Ligações. O valor em si nunca chega ao ConnXL.
3. Cria a ligação. Tipo HTTP API, URL base https://<project-ref>.supabase.co/rest/v1, autenticação Troca de token de início de sessão, audiência authenticated.
4. Adiciona o cabeçalho apikey. O PostgREST quer a anon key do teu projeto em cada pedido, além do bearer token. Adiciona-a como cabeçalho extra na ligação — nome apikey, valor a anon key, de novo como referência secret://. Sem ela, o Supabase recusa a chamada antes sequer de olhar para o JWT.
5. Escreve a política. Ativa o RLS na tabela e assenta-a num claim do token emitido:

create policy "own rows" on documents for select using (auth.jwt()->>'sub' = user_id);

Usa antes auth.jwt()->>'email' quando as tuas linhas forem identificadas pelo endereço de email e não pelo subject id do fornecedor.

Os campos da troca

Quando o início de sessão não funciona

• «redirect_uri mismatch» — o URL registado não corresponde ao que o painel mostra, carácter a carácter. Copia-o de novo.
• «redirect_uri mismatch» a queixar-se de http:// versus https:// (o Entra mostra-o como AADSTS500112) — o TLS termina num balanceador de carga ou proxy inverso à frente do agente, e o agente não confia nos cabeçalhos reencaminhados por predefinição. Define CONNXL_TRUSTED_PROXY=1 no host do agente para que o callback seja construído como https://.
• O início de sessão resulta mas o suplemento recusa-te à mesma — a autenticação funcionou, a autorização não. Revê os domínios permitidos/negados e a audiência em Controlo de acesso.
• Todos os inícios de sessão Entra falham no modo «qualquer organização» — falta o claim opcional xms_edov no registo de aplicação.
• Não acontece nada ao carregar no botão de início de sessão — o agente tem de servir HTTPS de confiança; o Excel recusa-se a carregar um suplemento, ou a sua janela de início de sessão, a partir de um host não fiável.