Gerador de OpenID Discovery

/.well-known/openid-configuration: o documento de descoberta que conecta o OIDC

OpenID Connect (OIDC) é a camada de autenticação que se senta em cima do OAuth 2.0 (RFC 6749). OAuth resolve "este app pode chamar esta API em nome de um usuário"; OIDC adiciona "e aqui vai informação verificada sobre quem é esse usuário" via um ID Token assinado. O documento de descoberta publicado no caminho well-known /.well-known/openid-configuration é o arquivo JSON de metadados que todo cliente OIDC busca uma vez no startup para aprender onde ficam os endpoints do provedor — issuer, authorization, token, userinfo, JWKS, end-session, o mapa inteiro. Definido pela spec OpenID Connect Discovery 1.0, é o que transforma o OIDC em protocolo plug-and-play: cole uma URL de issuer no Auth0, Keycloak, MSAL ou oidc-client-ts e a biblioteca busca todo o resto automaticamente.

O documento útil mínimo declara o issuer mais um punhado de URLs de endpoint e preferências criptográficas. Uma resposta funcional fica assim:

{
  "issuer": "https://idp.example.com",
  "authorization_endpoint": "https://idp.example.com/oauth2/authorize",
  "token_endpoint": "https://idp.example.com/oauth2/token",
  "userinfo_endpoint": "https://idp.example.com/oauth2/userinfo",
  "jwks_uri": "https://idp.example.com/.well-known/jwks.json",
  "response_types_supported": ["code", "id_token", "code id_token"],
  "subject_types_supported": ["public"],
  "id_token_signing_alg_values_supported": ["RS256", "ES256"]
}

Campos obrigatórios vs opcionais

Os campos acima são obrigatórios pela spec de discovery. Opcionais mas onipresentes: scopes_supported (anuncia openid, profile, email, offline_access), claims_supported (dica de quais campos de userinfo o IdP devolve), end_session_endpoint (para logout iniciado pelo Relying Party), revocation_endpoint e introspection_endpoint (RFC 7009 e RFC 7662 — adotados do OAuth para o ecossistema OIDC), code_challenge_methods_supported (S256 para PKCE — obrigatório para qualquer SPA ou cliente mobile moderno), token_endpoint_auth_methods_supported e grant_types_supported.

Provedores de identidade e opções de self-hosting

Principais IdPs comerciais que publicam discovery OIDC: Google (accounts.google.com/.well-known/openid-configuration), Microsoft Entra ID (antigo Azure AD), Sign in with Apple, Auth0, Okta, AWS Cognito, Firebase Auth, Stytch e Clerk. Opções self-hosted testadas em produção: Keycloak (Red Hat, Java), Authentik (Python, escolha moderna para quem hospeda em casa), ZITADEL (Go, multi-tenant), Ory Kratos + Hydra (Go, split cloud-native), Dex (Go, gateway na frente de LDAP/SAML), Casdoor e FusionAuth. Todos entregam o discovery endpoint pronto; o gerador desta página serve para montar um manualmente quando se implementa um IdP custom ou um mock em testes.

Fluxos, JWKS e PKCE

O Authorization Code Flow com PKCE (Proof Key for Code Exchange) é o fluxo recomendado hoje tanto para SPAs quanto para apps mobile e apps web com backend — o legado Implicit Flow foi descontinuado. O jwks_uri publica as chaves públicas (em formato JWK) que os clientes usam para verificar a assinatura do ID Token, que é um JWT assinado contendo claims como sub, email, name, picture e aud. O endpoint well-known geralmente fica com CORS aberto (Access-Control-Allow-Origin: *) e cache de uma hora — clientes refetcham periodicamente para acompanhar rotação de chaves. A RFC 8414 define um mecanismo paralelo, /.well-known/oauth-authorization-server, para servidores OAuth puros que não falam OIDC.

Perguntas frequentes

Preciso disso para OAuth 2.0 puro? Não — o documento é específico do OIDC. Servidores OAuth 2.0 puros podem publicar /.well-known/oauth-authorization-server (RFC 8414), e muitos publicam os dois.

Dá para self-hostar um provedor OIDC? Sim — Keycloak, Authentik, ZITADEL e Ory Hydra são open source de grau de produção. Cada um gera o documento de discovery para você e expõe o endpoint JWKS.

Quem lê este arquivo de fato? Bibliotecas cliente OIDC: oidc-client-ts e oauth4webapi no browser, MSAL para stacks Microsoft, AppAuth em mobile, panva/node-openid-client no Node, Authlib em Python e Spring Security em Java. Todas fazem bootstrap só com a URL do issuer.

Por que o caminho é well-known? A RFC 8615 reserva /.well-known/ como registro global de sufixos URI padronizados para protocolos diferentes não colidirem. É o mesmo lugar que hospeda security.txt, desafios ACME, MTA-STS e descoberta de federação Matrix.