Endpoints OpenID Connect

Cada realm é um OpenID Provider independente. O emissor dele é {base}/realms/{realm} e todos os endpoints ficam abaixo dele, então um client configurado com o emissor encontra o resto pelo discovery. Os exemplos desta página usam o realm acme na plataforma compartilhada:

https://authio.api.hyperio.tech/realms/acme

Num ambiente dedicado, troque o host pelo endereço da API do seu ambiente. Um token emitido por um realm nunca é aceito por outro.

Os endpoints num relance

Os limites contam cada chamador por realm. Uma requisição recusada recebe 429 com o cabeçalho Retry-After. As respostas que levam credenciais — token, introspecção, revogação, UserInfo, autorização de dispositivo — saem com Cache-Control: no-store.

Discovery

Os metadados do provedor são servidos em três endereços, para que o client os encontre seja qual for a convenção que ele segue: o OpenID Connect Discovery acrescenta o sufixo ao emissor, e o RFC 8414 o insere depois do host, a forma que os clients MCP tentam primeiro.

curl https://authio.api.hyperio.tech/realms/acme/.well-known/openid-configuration
curl https://authio.api.hyperio.tech/.well-known/oauth-authorization-server/realms/acme
curl https://authio.api.hyperio.tech/.well-known/openid-configuration/realms/acme

O documento descreve o realm como ele está configurado, e não um catálogo genérico:

Não há endpoint de registro dinâmico de clients, e request objects assinados (request, request_uri) não são aceitos. O discovery responde 404 para um realm que não existe.

JWKS

As chaves públicas que validam os tokens do realm, como um JWK Set (RFC 7517). Todo token informa no cabeçalho kid a chave que o assinou. As chaves são rotacionadas periodicamente, então guarde o conjunto em cache e busque de novo quando um token trouxer um kid que você não tem.

curl https://authio.api.hyperio.tech/realms/acme/protocol/openid-connect/certs

Endpoint de autorização

Inicia um login com o fluxo authorization code. O navegador é enviado para cá, o login hospedado executa os passos de login do client e o navegador volta ao seu redirect_uri com um código.

https://authio.api.hyperio.tech/realms/acme/protocol/openid-connect/auth
  ?client_id=acme-web
  &response_type=code
  &redirect_uri=https%3A%2F%2Fapp.acme.com%2Fcallback
  &scope=openid%20profile%20email%20offline_access
  &state=af0ifjsldkj
  &nonce=n-0S6_WzA2Mj
  &code_challenge=E9Melhoa2OwvFrEMTJguCHaoeK1t8URWbuGJSstw-cM
  &code_challenge_method=S256

A resposta traz code, state e iss (RFC 9207). O código vale 30 segundos e uma única vez: apresentá-lo de novo revoga a sessão em que ele foi emitido. Enquanto o redirect_uri não está comprovado, os erros aparecem numa tela de erro em vez de serem redirecionados; depois disso, voltam ao redirect_uri com error, error_description, state e iss.

Endpoint de token

Troca um grant por tokens. O corpo é application/x-www-form-urlencoded. Um client confidencial se autentica por HTTP Basic (client_secret_basic, o padrão) ou com client_id e client_secret no corpo (client_secret_post) — só o método registrado no client é aceito, e o Basic vale quando os dois são enviados. Um client público envia só o client_id e conta com o PKCE. Autenticação de client por JWT com chave privada não é aceita.

Grants aceitos

Cada grant precisa estar habilitado no client. Um grant desconhecido recebe unsupported_grant_type; um conhecido que o client não habilitou recebe unauthorized_client.

curl https://authio.api.hyperio.tech/realms/acme/protocol/openid-connect/token \
  -u "acme-web:$CLIENT_SECRET" \
  -d grant_type=authorization_code \
  -d code="$CODE" \
  --data-urlencode redirect_uri=https://app.acme.com/callback \
  -d code_verifier="$CODE_VERIFIER"

Autorização de dispositivo

Inicia o fluxo de dispositivo (RFC 8628) para aparelhos com entrada limitada. O client se autentica como no endpoint de token e precisa ter o grant device code habilitado.

curl https://authio.api.hyperio.tech/realms/acme/protocol/openid-connect/device/auth \
  -d client_id=acme-cli \
  --data-urlencode "scope=openid profile offline_access"

Enquanto a pessoa decide, a consulta responde authorization_pending; consultar rápido demais responde slow_down; depois de 10 minutos, expired_token; um pedido negado, access_denied. Veja Fluxo de dispositivo.

UserInfo

Devolve as claims atuais da pessoa por trás de um access token: sempre sub, mais as claims que os escopos profile, email e phone do token liberam, lidas na hora a cada chamada. Um token sem openid recebe 403 com insufficient_scope; um inválido, 401 com invalid_token, os dois com o cabeçalho WWW-Authenticate.

curl https://authio.api.hyperio.tech/realms/acme/protocol/openid-connect/userinfo \
  -H "Authorization: Bearer $ACCESS_TOKEN"

Introspecção

Diz a uma API se um token ainda está ativo (RFC 7662), inclusive revogação, sessão encerrada e usuário suspenso, que a conferência da assinatura sozinha não enxerga. Quem chama se autentica como client. A resposta é sempre 200: {"active": false} para qualquer token que não seja válido, sem dizer o motivo.

curl https://authio.api.hyperio.tech/realms/acme/protocol/openid-connect/introspect \
  -u "acme-web:$CLIENT_SECRET" \
  -d token="$ACCESS_TOKEN" \
  -d token_type_hint=access_token

Um token ativo devolve active, scope, client_id, username, token_type, exp, iat, nbf, sub, aud, iss e jti, mais claims de autorização como os papéis, acr, amr, sid e a organização. Com token_type_hint=api_key o client pergunta por uma das chaves de API dos seus consumers: uma chave ativa devolve sub (o consumer), client_id, scope, consumer_name, credential_id, credential_type e consumer_resource_access.

Revogação

Invalida um token de que você não precisa mais (RFC 7009), normalmente no logout. Quem chama se autentica como client, e toda requisição bem formada recebe 200, mesmo com um token desconhecido ou expirado. Revogar encerra a sessão por trás do token, o que também invalida os refresh tokens dela; a pessoa continua conectada às outras aplicações do realm.

curl https://authio.api.hyperio.tech/realms/acme/protocol/openid-connect/revoke \
  -u "acme-web:$CLIENT_SECRET" \
  -d token="$REFRESH_TOKEN" \
  -d token_type_hint=refresh_token

Logout

Desconecta a pessoa do realm (RP-Initiated Logout). Envie o navegador para cá com:

https://authio.api.hyperio.tech/realms/acme/protocol/openid-connect/logout
  ?id_token_hint=ID_TOKEN
  &post_logout_redirect_uri=https%3A%2F%2Fapp.acme.com%2F
  &state=af0ifjsldkj

Os clients que registraram um URI de logout back-channel ou front-channel são avisados sempre que uma sessão deles termina — no logout, mas também quando um administrador a revoga ou o usuário é suspenso. Veja Sessões e SSO.

Outros endereços sob um realm

Erros

Os endpoints de protocolo respondem erros com os campos do RFC 6749 §5.2, mais o error_code do próprio Authio, para cruzar um relato com os logs:

{
  "error": "invalid_client",
  "error_description": "Invalid client credentials. The provided client_secret is not valid.",
  "error_code": "InvalidClientCredentials"
}

Todos os valores de error e os códigos por trás deles estão em Códigos de erro.

Próximos passos