Conectar um provedor OpenID Connect

Use este guia quando o seu provedor 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 os mesmos passos; só muda o lugar onde o seu provedor exibe os valores.

Pré-requisitos

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

Etapas

1. Abra Configuraçõ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 provedor tiver emitido um. O Control Center descobre os endpoints a partir do documento de descoberta padrão do emissor — sem configuração por provedor.
3. No provedor, registre o redirecionamento https://<your-server>/oidc/callback nesse cliente.
4. Se os seus grupos estiverem sob uma declaração diferente de groups, defina o nome do Claim de grupos; mapeie grupos para papéis se quiser (o SSO nunca consegue conceder o papel 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 pressione Salvar conexão.
6. Pressione Testar ligação — o servidor busca o documento de descoberta do emissor e confirma os endpoints dele, então um toast verde significa que tudo, exceto a ida e volta pelo navegador, funciona. Para verificar também o registro do cliente, use o verificador abaixo.
7. Faça um login: a tela de conexão web mostra Entrar com OpenID Connect, ou abra https://<your-server>/oidc/login diretamente.

As declarações (e-mail, nome, grupos) são lidas do endpoint de token do emissor por TLS, pelo seu servidor — o navegador nunca as fornece, então não há verificação local de assinatura JWT envolvida. O cliente deve poder solicitar o escopo openid profile email, que é exatamente o que o Control Center pede.

Como esse canal TLS é a única coisa que autentica as declarações, a URL do emissor precisa ser https — um emissor em texto simples permitiria que qualquer atacante no caminho forjasse identidades em massa. http é aceito apenas para emissores de loopback (localhost, 127.0.0.1, ::1), para desenvolvimento local.

Cliente público ou cliente confidencial?

O formato padrão — e recomendado — é um cliente público usando o fluxo de código de autorização com PKCE (RFC 7636): o verificador de código de uso único que o servidor guarda substitui o segredo, e a troca de token fica vinculada à solicitação de autorização que a iniciou. Não há segredo a vazar, e um código de autorização roubado é inútil sem o verificador. Alguns provedores chamam esse tipo de cliente de “SPA” ou “native” na hora de criá-lo.

Se o seu provedor tiver emitido um cliente confidencial, marque o cliente como público no provedor (o PKCE continua ativo de qualquer forma) ou cole o segredo do cliente no campo Segredo do cliente (opcional) da conexão. O segredo é guardado no arquivo de segredos 0600 do servidor (nunca no banco de dados), enviado ao endpoint de token como client_secret_post e nunca devolvido por RPC; deixar o campo em branco ao salvar mantém o segredo guardado. Quando um login falha na troca de token, o log do servidor informa o erro do próprio provedor (invalid_client quase sempre significa que o segredo está ausente ou incorreto).

Alcançabilidade

O login em si é mediado pelo navegador: o emissor apenas redireciona o navegador do usuário de volta para /oidc/callback, e o seu servidor faz uma chamada HTTPS de saída ao endpoint de token — nenhuma conexão de entrada vinda do emissor é necessária, então um servidor atrás de NAT funciona desde que os navegadores dos usuários consigam alcançá-lo (LAN, VPN, Tailscale ou um túnel). O provisionamento por SCIM é a exceção: o IdP chama o seu servidor diretamente, o que exige um túnel ou uma URL pública — veja provisionar usuários com SCIM.

Verifique sua configuração nesta página

O verificador abaixo é executado no seu navegador. Ele busca o documento de descoberta do seu emissor diretamente, de modo 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 exigido pelo tipo de cliente. Com um ID de cliente e o endereço do servidor, ele pode abrir um login de teste que mostra se o cliente e a sua URI de redirecionamento estão registrados. Ele 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