Ligar um fornecedor OpenID Connect

Utilize este guia quando o seu fornecedor de identidade fala OpenID Connect em vez de SAML. Qualquer emissor certificado para OIDC funciona — Pocket ID, Keycloak, Auth0, Zitadel, Google Workspace e afins seguem todos os mesmos passos; só difere o local onde o seu fornecedor mostra os valores.

Pré-requisitos

• um fornecedor OIDC onde possa criar um cliente — anote o ID de cliente e a URL do emissor (a base sob a qual vive o documento .well-known/openid-configuration), mais o segredo do cliente quando o cliente é do tipo confidencial (os clientes públicos com PKCE não têm nenhum),
• um servidor do Control Center que administre (o proprietário do servidor).

Passos

1. Abra Definições → Servidor → Início de sessão único e mude para OpenID Connect.
2. Preencha a URL do emissor, o ID de cliente e o Segredo do cliente (opcional) quando o fornecedor tiver emitido um. O Control Center descobre os endpoints a partir do documento de descoberta padrão do emissor — sem configuração por fornecedor.
3. No fornecedor, registe o redirecionamento https://<your-server>/oidc/callback nesse cliente.
4. Se os seus grupos estiverem sob um claim diferente de groups, defina o nome do Claim de grupos; mapeie grupos para funções se quiser (o SSO nunca pode conceder a função de proprietário).
5. Escolha a política de associação (adicionar automaticamente a todos os espaços de trabalho, ou exigir convites por espaço de trabalho), ative Usar OpenID Connect para entrar e prima Guardar ligação.
6. Prima Testar ligação — o servidor vai buscar o documento de descoberta do emissor e confirma os seus endpoints, por isso uma notificação verde significa que tudo funciona exceto a ida e volta pelo navegador. Para verificar também o registo do cliente, use o verificador abaixo.
7. Inicie sessão: o ecrã de ligação web mostra Entrar com OpenID Connect, ou abra https://<your-server>/oidc/login diretamente.

Os claims (email, name, groups) são lidos pelo seu servidor a partir do endpoint de token do emissor através de TLS — o navegador nunca os fornece, pelo que não há qualquer verificação local da assinatura do JWT. Deve permitir-se que o cliente peça o scope openid profile email, que é exatamente o que o Control Center pede.

Como esse canal TLS é a única coisa que autentica os claims, a URL do emissor tem de ser https — um emissor em texto simples permitiria a qualquer atacante no caminho forjar identidades em massa. http só é aceite para emissores de loopback (localhost, 127.0.0.1, ::1), para desenvolvimento local.

Cliente público ou cliente confidencial?

A forma predefinida — e recomendada — é um cliente público com o fluxo de código de autorização e PKCE (RFC 7636): o verificador de código de uso único que o servidor guarda substitui o segredo e a troca de token fica associada ao pedido de autorização que a iniciou. Não há segredo para divulgar e um código de autorização roubado é inútil sem o verificador. Alguns fornecedores chamam a este tipo de cliente “SPA” ou “native” quando o cria.

Se, em vez disso, o seu fornecedor emitiu um cliente confidencial, ou marque o cliente como público no fornecedor (o PKCE mantém-se ativo de qualquer forma), ou cole o segredo do cliente no campo Segredo do cliente (opcional) da ligação. O segredo é guardado no ficheiro de segredos 0600 do servidor (nunca na base de dados), enviado para o endpoint de token como client_secret_post e nunca devolvido por RPC; deixar o campo em branco ao guardar mantém o segredo armazenado. Quando um início de sessão falha na troca de token, o registo do servidor indica o próprio erro do fornecedor (invalid_client significa quase sempre que o segredo está em falta ou errado).

Alcançabilidade

O início de sessão em si é mediado pelo navegador: o emissor apenas redireciona o navegador do utilizador de volta para /oidc/callback e o seu servidor faz uma chamada HTTPS de saída para o endpoint de token — não é necessária nenhuma ligação de entrada vinda do emissor, pelo que um servidor atrás de NAT funciona desde que os navegadores dos utilizadores o consigam alcançar (LAN, VPN, Tailscale ou um túnel). O provisionamento SCIM é a exceção: o IdP chama o seu servidor diretamente, o que exige um túnel ou um URL público — consulte provisionar utilizadores com SCIM.

Verifique a sua configuração nesta página

O verificador abaixo é executado no seu navegador. Vai buscar diretamente o documento de descoberta do seu emissor, pelo que este site nunca o vê, e aplica as regras do servidor: um emissor https que corresponde ao documento, endpoints na própria origem do emissor, PKCE S256 e o método de autenticação de token de que o seu tipo de cliente precisa. Com um ID de cliente e o endereço do servidor, pode abrir um início de sessão de teste que mostra se o cliente e o seu URI de redirecionamento estão registados. Nunca pede o segredo do cliente.

Runs in your browserYour browser fetches the discovery document straight from your issuer. Add a server address and it also asks that server which sign-in methods it offers. This site never receives what you type.

Issuer URL

Client ID (optional)

Needed for the test sign-in.

Groups claim (optional)

Client type

Public, PKCE only Confidential, has a client secret

Never paste the secret here. The check only needs to know whether one exists.

Server address (optional)

The address your users open. Adds a reachability check and a test sign-in.

Paste the discovery document instead

Discovery document JSON

For providers that block other sites from reading it.

Check issuer