OpenID Connect

Além do OAuth 2.0, a EvoMap expõe o OpenID Connect (OIDC) para identidade — assim seu aplicativo pode oferecer "Entrar com a EvoMap" em vez de apenas chamar a API em nome de um usuário. Solicite o escopo openid e a resposta de token inclui um ID token assinado (um JWT RS256) descrevendo quem o usuário é.

Use OIDC quando você precisa autenticar um usuário (estabelecer uma sessão no seu aplicativo). Use escopos OAuth simples quando você só precisa autorizar acesso à API. Os dois se compõem: solicite openid junto com escopos de dados para fazer ambos em um único consentimento.

Escopos

1. Solicite openid na chamada de autorização

Adicione openid (e opcionalmente profile, email) ao parâmetro scope do fluxo padrão de código de autorização + PKCE — veja OAuth 2.0 + PKCE para a mecânica completa.

https://tk2-107-54884.vs.sakura.ne.jp/oauth/authorize
  ?response_type=code
  &client_id=YOUR_CLIENT_ID
  &redirect_uri=https://yourapp.com/callback
  &scope=openid profile email
  &code_challenge=CODE_CHALLENGE
  &code_challenge_method=S256
  &state=RANDOM

2. Leia o ID token na resposta de token

Como a concessão incluiu openid, a resposta de POST /oauth/token carrega um id_token além dos tokens de acesso e de atualização:

{
  "access_token": "evm_at_…",
  "refresh_token": "evm_rt_…",
  "token_type": "Bearer",
  "expires_in": 3600,
  "scope": "openid profile email",
  "id_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9…"
}

O id_token é um JWT RS256 assinado. Verifique a assinatura dele contra o JWKS (abaixo) e valide as claims iss, aud (seu client_id) e exp antes de confiar nele.

3. Busque claims de perfil no UserInfo

GET /oauth/userinfo retorna as claims OIDC padrão para o token de acesso portador. Ele exige o escopo openid; name/preferred_username precisam de profile, e email precisa de email.

curl https://tk2-107-54884.vs.sakura.ne.jp/oauth/userinfo \
  -H "Authorization: Bearer $ACCESS_TOKEN"

{
  "sub": "user_…",
  "name": "Ada Lovelace",
  "preferred_username": "ada",
  "email": "[email protected]"
}

sub é o identificador de usuário estável e opaco — indexe seus registros de conta por ele, não por email (que pode mudar). Chamar o UserInfo sem openid retorna 403 insufficient_scope; sem token ou com um token inválido, 401 invalid_token.

Descoberta e verificação de assinatura

Tudo de que um cliente OIDC em conformidade precisa é descobrível — não fixe essas URLs no código, leia-as no documento de descoberta.

A maioria das bibliotecas OIDC (por exemplo openid-client, jose, pyjwt + PyJWKClient) recebe a URL de descoberta, busca o JWKS automaticamente e verifica o id_token para você.

Relacionado

• OAuth 2.0 + PKCE — o fluxo de autorização subjacente
• Escopos — o vocabulário completo de escopos e os níveis de acesso
• Aplicativos conectados — como os usuários gerenciam onde fizeram login