Como gerar um token de acesso para sistema (nova versão)

Esta página documenta a nova versão da autorização entre sistemas do Acesso Cidadão.

Para integrações legadas, mantenha a documentação antiga baseada em https://acessocidadao.es.gov.br/is/....

Visão geral

Na nova versão do Acesso Cidadão, os tokens de client credentials devem ser obtidos a partir do discovery document abaixo:

https://token.acessocidadao.es.gov.br/.well-known/openid-configuration

A partir dele, o endpoint de emissão de token é:

https://token.acessocidadao.es.gov.br/connect/token

Esse fluxo deve ser usado quando um sistema precisa chamar uma API protegida em nome do próprio sistema, sem contexto de usuário autenticado.

O que mudou na nova versão

• O endpoint de emissão de token passou a ser publicado no domínio token.acessocidadao.es.gov.br.
• O token continua sendo um JWT e deve ser tratado como credencial de acesso temporária.
• Não se deve mais confiar em prefixo de scope para identificar a API de destino.
• Na nova versão, a API protegida deve validar sempre o campo aud do token, pois scopes podem se repetir entre sistemas diferentes.

Discovery document

Antes de implementar a integração, consulte sempre o discovery document do provedor:

https://token.acessocidadao.es.gov.br/.well-known/openid-configuration

Esse documento publica, entre outras informações:

• issuer
• jwks_uri
• token_endpoint
• grant_types_supported

Requisição para obtenção do token

Para obter o token de acesso de sistema, faça uma requisição POST para:

https://token.acessocidadao.es.gov.br/connect/token

Header

Content-Type: application/x-www-form-urlencoded
Authorization: Basic BASE64(CLIENT_ID:CLIENT_SECRET)

Recomenda-se usar autenticação do cliente via header Authorization: Basic, conforme padrão OAuth 2.0.

Body

Parâmetro	Obrigatório	Descrição
grant_type	Sim	Deve ser client_credentials.
scope	Sim	Um ou mais scopes autorizados para a aplicação cliente.

Exemplo HTTP

POST /connect/token HTTP/1.1
Host: token.acessocidadao.es.gov.br
Authorization: Basic BASE64(CLIENT_ID:CLIENT_SECRET)
Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials&scope=api.read api.write

Exemplo cURL

curl --request POST 'https://token.acessocidadao.es.gov.br/connect/token' \
  --header 'Authorization: Basic BASE64(CLIENT_ID:CLIENT_SECRET)' \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --data-urlencode 'grant_type=client_credentials' \
  --data-urlencode 'scope=api.read api.write'

Resposta esperada

Em caso de sucesso, o serviço retorna um JSON semelhante ao abaixo:

{
  "access_token": "<jwt>",
  "token_type": "Bearer",
  "expires_in": 3600
}

Uso do token

De posse do access_token, a aplicação cliente pode chamar a API protegida usando o header abaixo:

Authorization: Bearer <access_token>

Validação na API protegida

Na nova versão, a API protegida deve validar:

• assinatura do token;
• expiração;
• issuer;
• aud;
• scopes exigidos pela operação.

Importante

O campo scope não substitui a validação de aud.

No modelo antigo, alguns cenários dependiam de prefixos fixos nos scopes para separar tokens de sistemas diferentes. Esse comportamento não deve mais ser usado como barreira principal de segurança.

Na nova versão:

• scopes podem ter nomes iguais em APIs diferentes;
• a identificação correta da API destinatária está no campo aud;
• cada API deve validar se o token foi emitido para ela.

Boas práticas

• Nunca grave client_secret no código-fonte.
• Use HTTPS em toda a comunicação.
• Gere novo token quando ele expirar; não reutilize tokens antigos.
• Solicite apenas os scopes realmente necessários.
• Em caso de falha, verifique primeiro se a aplicação está cadastrada com os scopes corretos e se a API está validando o aud esperado.