Qualquer client OIDC

Todo realm é um provedor OpenID Connect padrão, então qualquer biblioteca OIDC ou OAuth 2.0 certificada funciona sem SDK do Authio. Passe à biblioteca o emissor do realm, um client ID e, num client confidencial, o segredo; o resto ela lê do discovery. Esta página mostra as requisições como elas trafegam, para você saber o que a biblioteca faz e conseguir conferir com curl.

Discovery

O emissor é https://authio.api.hyperio.tech/realms/{realm}. O documento de discovery dele lista os endpoints, os escopos e grants que os clients do realm usam e os algoritmos suportados. Ele é servido no endereço do OpenID Connect e nas duas formas do RFC 8414, com CORS aberto a qualquer origem.

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

Configure a biblioteca com o emissor, e não com endpoints avulsos. A lista completa, com todos os parâmetros, está em Endpoints OIDC.

Registre o client

Código de autorização com PKCE

1. 1

   Crie um verifier e o challenge dele

   O verifier é uma string aleatória que a aplicação guarda; o challenge é o hash SHA-256 dela em base64url. Crie também um state e um nonce aleatórios para este login.

   TerminalBash

   CODE_VERIFIER=$(openssl rand -hex 32)
   CODE_CHALLENGE=$(printf '%s' "$CODE_VERIFIER" | openssl dgst -sha256 -binary | openssl base64 -A | tr '+/' '-_' | tr -d '=')

2. 2

   Mande o navegador para o endpoint de autorização

   Pedido de autorizaçãoTexto simples

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

   Parâmetros opcionais: prompt (none, login, select_account, consent), max_age, login_hint, ui_locales, id_token_hint, organization e resource — o identificador de um servidor de recurso, para receber um access token para aquela API. display=popup com response_mode=web_message faz o login num popup.

3. 3

   Receba o código

   Depois do login hospedado, o navegador volta com code, state e iss (RFC 9207). Confira se state é o que você mandou e se iss é o emissor do realm. O código é de uso único e expira em 30 segundos, então troque-o na hora. Uma recusa volta com error no lugar, também com state e iss.

   RetornoTexto simples

   https://app.example.com/callback?code=AUTHORIZATION_CODE&state=STATE&iss=https%3A%2F%2Fauthio.api.hyperio.tech%2Frealms%2Facme

4. 4

   Troque o código por tokens

   Client confidencialClient público

   Client confidencialBash

   curl -X POST https://authio.api.hyperio.tech/realms/acme/protocol/openid-connect/token \
     -u 'acme-web:YOUR_CLIENT_SECRET' \
     -d grant_type=authorization_code \
     -d code=AUTHORIZATION_CODE \
     --data-urlencode redirect_uri=https://app.example.com/callback \
     -d code_verifier=$CODE_VERIFIER

   RespostaJSON

   {
     "access_token": "eyJhbGciOiJSUzI1NiIs...",
     "token_type": "Bearer",
     "expires_in": 1800,
     "refresh_token": "eyJhbGciOiJSUzI1NiIs...",
     "refresh_expires_in": 3600,
     "id_token": "eyJhbGciOiJSUzI1NiIs...",
     "scope": "openid profile email offline_access"
   }

   Valide o ID token como pede o OpenID Connect Core: assinatura, iss, aud igual ao seu client ID, exp e nonce igual ao que você mandou. Apresentar o mesmo código duas vezes revoga a sessão em que ele foi emitido.

SPAs, apps móveis e nativos

Aplicações que rodam no aparelho do usuário não conseguem guardar segredo, então usam um client público com PKCE e S256. Use uma biblioteca que faça o fluxo acima por você — uma certificada pelo OpenID para a sua plataforma.

• SPAs voltam para uma página https da própria aplicação. O documento de discovery, o JWKS e o endpoint de token respondem a qualquer origem, então o código pode ser trocado no navegador. Para tirar os tokens do navegador de vez, coloque um Backend-for-Frontend na frente do SPA.
• Apps de desktop e CLIs escutam na interface de loopback. Registre http://127.0.0.1/callback e ligue Loopback on any port: o Authio passa a aceitar qualquer porta em 127.0.0.1, [::1] e localhost (RFC 8252).
• Apps móveis voltam por um link https que o app reivindica (universal links ou app links). Redirect URIs precisam ser http ou https, então esquemas de URI próprios não são aceitos.
• Aparelhos sem navegador, como TVs, usam o fluxo de dispositivo.

Valide access tokens

Uma API confere cada access token localmente, com as chaves do realm; um token válido não exige chamada ao Authio. Use a biblioteca JWT da sua plataforma com estas regras:

Um JWT continua válido até expirar, mesmo depois que a sessão termina. Para perceber revogações e logouts antes, ou para aceitar tokens opacos ou criptografados, consulte o endpoint de introspecção (RFC 7662) como um client confidencial autorizado a introspectar os tokens da API. Ele sempre responde 200, com active: false e mais nada para qualquer token que não seja válido.

curl -X POST https://authio.api.hyperio.tech/realms/acme/protocol/openid-connect/introspect \
  -u 'orders-api:YOUR_CLIENT_SECRET' \
  -d token=ACCESS_TOKEN \
  -d token_type_hint=access_token

Refresh tokens

Um refresh token só é emitido quando offline_access é concedido. Apresente-o com a mesma autenticação de client da troca do código:

curl -X POST https://authio.api.hyperio.tech/realms/acme/protocol/openid-connect/token \
  -u 'acme-web:YOUR_CLIENT_SECRET' \
  -d grant_type=refresh_token \
  -d refresh_token=REFRESH_TOKEN

• Refresh tokens são rotacionados por padrão: guarde o novo refresh_token de cada resposta.
• Dentro da janela de reuso (10 segundos por padrão), um pedido repetido recebe o mesmo refresh token novo. Um token gasto apresentado depois disso encerra a sessão inteira e é registrado como possível roubo.
• A renovação mantém auth_time, amr e o resource original. Ela só devolve id_token se o client ligar ID Token on Refresh.
• Uma recusa é invalid_grant: faça o login da pessoa de novo.

UserInfo

O endpoint UserInfo devolve as claims atuais da pessoa, lidas de novo a cada chamada, até onde os escopos do token permitem. Ele exige um token com o escopo openid concedido. Responde JSON, a menos que o client tenha pedido um JWT assinado ou criptografado: veja UserInfo assinado e criptografado.

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

Logout

Para encerrar a sessão da pessoa, mande o navegador para o endpoint de logout com o ID token que você recebeu. Só um id_token_hint válido encerra a sessão — um expirado é aceito. Sem ele, o Authio mostra uma tela de confirmação no lugar.

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

post_logout_redirect_uri só é seguido se estiver registrado no client, comparado como um redirect URI; state volta inalterado. Para descartar tokens sem tirar a pessoa das outras aplicações do realm, revogue o refresh token (RFC 7009): isso encerra a sessão do client e mantém o login único.

curl -X POST https://authio.api.hyperio.tech/realms/acme/protocol/openid-connect/revoke \
  -u 'acme-web:YOUR_CLIENT_SECRET' \
  -d token=REFRESH_TOKEN \
  -d token_type_hint=refresh_token

Aplicações que precisam saber quando uma sessão termina em outro lugar — por um administrador, uma suspensão, outra aba — podem registrar um endereço de logout por back-channel ou front-channel. Veja Sessões e SSO.

Próximos passos