Pular para o conteúdo principal

Como autenticar um usuário (nova versão)

Esta página documenta a nova versão da autenticação de usuários 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, o fluxo de login deve usar o discovery document abaixo:

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

A autenticação de usuários é feita por Authorization Code com PKCE.

Esse é o fluxo recomendado para novas integrações e substitui o modelo legado documentado no domínio antigo.

Endpoints publicados no discovery​

A partir do discovery document, os principais endpoints são:

authorization_endpoint: https://login.acessocidadao.es.gov.br/connect/authorize
token_endpoint:         https://login.acessocidadao.es.gov.br/connect/token
userinfo_endpoint:      https://userinfo.acessocidadao.es.gov.br/

O que mudou na nova versão​

  • O login passou a ser documentado a partir do domínio login.acessocidadao.es.gov.br.
  • Novas integrações devem usar Authorization Code com PKCE.
  • Não se deve mais iniciar novas integrações usando o endpoint legado /is/connect/authorize.
  • O redirect_uri continua precisando ser exatamente igual ao cadastrado para a aplicação.

Resumo do fluxo​

  1. A aplicação detecta que o usuário não está autenticado.
  2. A aplicação gera state, nonce, code_verifier e code_challenge.
  3. A aplicação redireciona o usuário para o authorization_endpoint.
  4. Após autenticação e autorização, o Acesso Cidadão retorna um code para a aplicação.
  5. A aplicação troca esse code por tokens no token_endpoint, enviando também o code_verifier.
  6. Com o access_token, a aplicação pode chamar APIs protegidas e o endpoint userinfo, conforme os scopes autorizados.

1. Gerando os parâmetros de segurança​

Antes de redirecionar o usuário para o login, gere:

  • state: protege contra CSRF;
  • nonce: associa a resposta de autenticação à sessão iniciada pela aplicação;
  • code_verifier: segredo temporário do PKCE;
  • code_challenge: derivado do code_verifier, preferencialmente com S256.

Recomendação​

Use sempre:

code_challenge_method=S256

2. Requisição de autorização​

A autenticação é iniciada com um GET para:

https://login.acessocidadao.es.gov.br/connect/authorize

Parâmetros mais comuns​

ParâmetroObrigatórioDescrição
response_typeSimDeve ser code.
client_idSimIdentificador da aplicação cadastrada.
redirect_uriSimURL de retorno cadastrada para a aplicação.
scopeSimEscopos solicitados. O mínimo usual é openid profile.
stateSimValor aleatório para correlação da sessão e proteção contra CSRF.
nonceRecomendadoValor aleatório para correlação da autenticação.
code_challengeSimValor derivado do code_verifier.
code_challenge_methodSimRecomenda-se S256.
response_modeNãoOpcional. Quando necessário, pode ser query ou form_post.

Exemplo de URL​

https://login.acessocidadao.es.gov.br/connect/authorize?response_type=code&client_id=[CLIENT_ID_DA_APLICACAO]&redirect_uri=https%3A%2F%2Fappcliente.com.br%2Floginacessocidadao&scope=openid%20profile&state=[STATE_GERADO]&nonce=[NONCE_GERADO]&code_challenge=[CODE_CHALLENGE_GERADO]&code_challenge_method=S256

3. Retorno para a aplicação​

Após o login e a autorização do usuário, o Acesso Cidadão redireciona o navegador para o redirect_uri da aplicação, enviando pelo menos:

ParâmetroDescrição
codeCódigo de autorização temporário, de uso único.
stateMesmo valor enviado pela aplicação na requisição inicial.

A aplicação deve validar se o state retornado corresponde ao valor originalmente gerado.

4. Troca do código por token​

Para obter o token, a aplicação deve fazer POST para:

https://login.acessocidadao.es.gov.br/connect/token
Content-Type: application/x-www-form-urlencoded

Para clientes confidenciais, envie também a autenticação do cliente conforme cadastro da aplicação.

Body​

ParâmetroObrigatórioDescrição
grant_typeSimDeve ser authorization_code.
codeSimCódigo recebido no retorno do login.
redirect_uriSimDeve ser exatamente o mesmo usado na requisição inicial.
code_verifierSimValor original usado para gerar o code_challenge.

Exemplo cURL​

curl --request POST 'https://login.acessocidadao.es.gov.br/connect/token' \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --data-urlencode 'grant_type=authorization_code' \
  --data-urlencode 'code=[CODE_RECEBIDO]' \
  --data-urlencode 'redirect_uri=https://appcliente.com.br/loginacessocidadao' \
  --data-urlencode 'code_verifier=[CODE_VERIFIER_GERADO]'

5. Resposta esperada​

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

{
  "access_token": "<token-de-acesso>",
  "id_token": "<token-de-identidade>",
  "token_type": "Bearer",
  "expires_in": 3600
}

Observação importante​

Na maioria dos cenários de consumo de APIs, o token usado para autorização é o access_token.

O id_token existe para representar o resultado da autenticação do usuário na aplicação cliente e não deve ser enviado para APIs como substituto do access token.

6. UserInfo​

Um dos endpoints que podem ser acessados com o access_token do usuário é o userinfo:

https://userinfo.acessocidadao.es.gov.br/

As claims retornadas dependem dos scopes concedidos no login.

Boas práticas​

  • Use sempre PKCE em novas integrações.
  • Prefira S256 como método do code_challenge.
  • Valide state no retorno.
  • Trate o redirect_uri como case sensitive e exatamente igual ao cadastrado.
  • Solicite apenas os scopes realmente necessários.
  • Não use o fluxo legado /is/... para novas integrações.
Última atualização em