Protocolo OAuth2

O OAuth 2.0 é o padrão de autorização utilizado pelo Login Cidadão Gov.br e grandes provedores de identidade. Ele permite a delegação de acesso a recursos sem a exposição de credenciais do usuário.

A implementação deve seguir as especificações oficiais (RFCs) para garantir segurança e interoperabilidade.

Especificações Oficiais

RFC 6749 (The OAuth 2.0 Authorization Framework): Define os fluxos principais (Grant Types) e a estrutura do protocolo.
RFC 6750 (Bearer Token Usage): Padroniza como enviar o token de acesso no cabeçalho HTTP (Authorization: Bearer ).
RFC 7636 (PKCE): Extensão obrigatória para segurança em aplicações Mobile e SPAs.
OpenID Connect Core 1.0: Camada de identidade sobre o OAuth 2.0 usada para fornecer dados do cidadão.

Workflow Técnico

Autorização: O app redireciona o usuário para o Provedor (Login Cidadão Gov.br).
Consentimento: O usuário autoriza os Scopes (permissões) solicitados.
Troca de Código: O app recebe um code e o troca por um access_token e um id_token (JWT).
Consumo: O app usa o access_token para acessar APIs de recursos em nome do usuário.
Encerramento: O app usa o id_token para encerrar a sessão do usuário.

Passo-a-passo para integrar

Passo 1

Solicitar a inclusão do serviço e obter o Client Id e Client Secret.

Dica: se a solicitação já foi concluída, o responsável pelo serviço deve obter o Client Id e Client Secret pelo Painel do Desenvolvedor.

Login GOV.BR - Incluir Serviço para Clientes - RS.GOV.BR - Portal de Serviços Digitais

Passo 2

Utilize a url https://meu.hml.rs.gov.br/.well-known/openid-configuration para obter as configurações do OpenId.

O serviço retornará em formato JSON conforme exemplo:

{
   "issuer":"(Url do login cidadão)",
   "authorization_endpoint":"(Endpoint de autorização)",
   "token_endpoint":"(Endpoint do token)",
   "token_endpoint_auth_methods_supported": "(métodos de autenticação)",
   "token_endpoint_auth_signing_alg_values_supported": "(algoritmos de autenticação)",
   "id_token_signing_alg_values_supported": "(algoritmos de autenticação)",
   "userinfo_endpoint":"(Endpoint de informações do usuário)",
   "check_session_iframe":"(Endpoint de check da sessão)",
   "end_session_endpoint":"(Endpoint de fim da sessão)",
   "jwks_uri":"(Endpoint para validação das chaves JWT)",
   "registration_endpoint":"(Endpoint de registro)",
   "scopes_supported": "(Escopos suportados)",
   "response_types_supported": "(Tipos de response_type)",
   "subject_types_supported": "(Tipos de subject)"
}

Passo 3

Implementar uma requisição GET de autorização https://meu.hml.rs.gov.br /openid/connect/authorize passando as seguintes informações:

Campo	Descrição
response_type	Especifica para o provedor o tipo de autorização. Neste caso será code
client_id	Chave de acesso que identifica o serviço consumidor
scope	Especifica os recursos que o serviço consumidor quer obter. Insira vários escopo utilizando espaço, por exemplo: openid email name
redirect_uri	URI de retorno cadastrada para a aplicação cliente (em URL callbacks) no formato URL Encode. Este parâmetro não pode conter caracteres especiais
nonce	Sequência de caracteres usado para associar uma sessão do serviço consumidor a um Token de ID e para atenuar os ataques de repetição. Pode ser um valor aleatório, mas que não seja de fácil dedução. Item obrigatório.
state	Valor usado para manter o estado entre a solicitação e o retorno de chamada. Item obrigatório.

Neste passo ocorre a etapa de autenticação do usuário, será feito um redirecionamento para a tela de login do GovBr.

Observação: Tanto o ambiente de homologação quanto o de produção do Login Cidadão Gov.Br utilizam usuário e senha produção do GovBr. Em homologação, o responsável pelo serviço pode confirgurá-lo para usar o ambiente de testes do Gov.br(stanging). ***

Passo 4

Após a autorização, a requisição é retornada para a URL especificada no redirect_uri, por exemplo, https://{SEUDOMINIO}/openid/callback retornando os seguintes parâmetros:

Campo	Descrição
code	Código de autenticação gerado pelo provedor. Será utilizado para obtenção do Token de Resposta. Possui tempo de expiração e só pode ser utilizado uma única vez
state	State passado anteriormente no https://meu.hml.rs.gov.br /openid/connect/authorize que pode ser utilizado para controle da aplicação cliente. O cliente consegue saber se o code veio de um state gerado por ele.

Esta URL de callback pode implementar, por exemplo, o Passo 6.

Importante: Esta URL deve ter sido cadastrada como url de redirecionamento no serviço.

Passo 5

Após autenticado, no fluxo de autenticação o provedor redireciona o usuário para a página de autorização. O usuário dará permissão aos escopos solicitados neste serviço conforme imagem abaixo.

Uma vez autorizado o próximo passo é requisitar um token de acesso.

Passo 6

Implementar a requisição do token através de um POST para https://meu.hml.rs.gov.br /openid/connect/token passando as seguintes informações:

Parâmetros do Header

Campo	Descrição
Content-Type	Tipo do conteúdo da requisição que está sendo enviada. Nesse caso application/x-www-form-urlencoded

Parâmetros do Body

Campo	Descrição
grant_type	Especifica para o provedor o tipo de autorização. Neste caso será authorization_code
code	Código retornado pela requisição anterior
redirect_uri	URI de retorno cadastrada para a aplicação cliente no formato URL Encode. Este parâmetro não pode conter caracteres especiais
client_id	Chave de acesso que identifica o serviço consumidor
client_secret	Chave segredo que equivale a senha do serviço consumidor

O serviço retornará, em caso de sucesso, no formato JSON, as informações conforme exemplo:

{
"access_token": "(Token de acesso cujo padrão é do tipo Bearer)",
"expires_in": "(Tempo de vida do token em segundos.)",
"token_type": "(O tipo do token gerado. Padrão: Bearer)",
"scope": "(Escopos)",
"id_token": "(Token de autenticação com informações básicas do usuário.)",
"session_state": "(Estado para controle da sessão)",
}

Passo 7

De posse das informações do json anterior, a aplicação consumidora está habilitada para consultar dados de recursos protegidos, que são as informações e método de acesso do usuário.

No entanto antes de utilizar os tokens do JSON anterior é necessário validar se as informações foram geradas pelos serviços do Login Cidadão Gov.Br.
Esta validação ocorrerá por meio da consulta da chave pública disponível no serviço https://meu.hml.rs.gov.br/openid/connect/jwks com algum método para verificar as chaves e a assinatura JWT.

Outra forma de validação pode ser através do id_token. Ao extrair o JSON codificado do ID_TOKEN ele conterá as seguintes informações para validação:

{
 iss: "(URL do provedor de autenticação que emitiu o token)",
 sub: "(Subject Identifier)",
 aud: "(Client ID da aplicação onde o usuário se autenticou)",
 iat: "(Data/hora em que o token foi emitido)",
 exp: "(Data/hora de expiração do token)",
 auth_time: "(Data/hora da autenticação)",
 nonce: "(Sequência de caracteres usado para associar uma sessão)",
 kid: "pub"
}

Passo 8

Para solicitação de informações do cadastro do cidadão, faça uma requisição GET para https:/meu.hml.rs.gov.br /api/v5/person e acrescente o atributo Authorization ao header do HTTP da requisição:

Parâmetros do Header

Campo	Descrição	Exemplo
Authorization	palavra Bearer e o ACCESS_TOKEN	Bearer oSeuAccesst0ken

O retorno será em formato JSON com todas as informações do usuário.

Passo 9 - Logout

Para encerrar a sessão com o usuário (logout) faça uma requisição GET para https://meu.hml.rs.gov.br/openid/connect/session/end passando o seguinte parâmetro:

Parâmetro Query

Campo	Descrição	Exemplo
post_logout_redirect_uri	URL da aplicação para ser redirecionada após logout	https://minhaapp/logout
id_token_hint	Token de autenticação com informações básicas do usuário.	eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzd...

Importante: Esta URL deve ter sido cadastrada como url de post_logout_redirect_uri no serviço para que o redirecionamento ocorra adequadamente.

Primeiro Acesso

Para o usuário autenticar basta utilizar o login e senha do GovBr.

Na primeira vez que o usuário acessa será apresentada a tela de consentimento, solicitando a permissão de uso dos seus dados no serviço do Login Cidadão Gov.br:

Basta o usuário confirmar e o acesso.

Lembrando: depois que o Login Cidadão Gov.br começou a utilizar os escopos do Gov.Br (dentre os escopos especiais), essa tela poderá ser reapresentada aos usuários para solicitação de consentimento quando houver qualquer alteração nos escopos.

Primeiro acesso feito pelo serviço

Agora, quando o usuário faz um primeiro acesso a um serviço nosso (isto é, serviço está vinculado ao Login Cidadão Gov.br), uma tela solicitando a autorização de uso dos dados é exibida:

Conforme a autorização anterior, o usuário autoriza e o sistema tem acesso as informações dos escopos do Gov.Br.

Atenção: Caso tenha a coincidência de ser o primeiro acesso nos dois casos, ocorre a primeira e depois ocorre a segunda autorização, em sequencia.

RS.GOV.BR - Portal de Serviços Digitais

Guia de Serviços

Como usar