Protocolo OAuth2

O Login Cidadão Gov.br utiliza o protocolo OAuth 2, que é muito utilizado pelos fornecedores de mídias sociais, como Google, Facebook, Twiter, etc.

Esse protocolo possui descritos suas caraterísticas e especificações muito bem definidas em RFCs e, além disso, muitas outras informações e dicas de como utilizar esse tipo de autenticação podem ser encontrados na internet.

Deixamos aqui alguns links para conhecer melhor o Oauth2:

Uma introdução ao OAuth 2
OAuth 2 – Guia do Iniciante
Como funciona o protocolo OAuth 2.0
Uma introdução OAuth 2.0 para iniciantes

Especificação da RFC do protocolo OpenID

Informações adicionais

Subject Identifier

Subject Identifier é como são chamados os identificadores dos End Users no OpenID Connect. No Login Cidadão Gov.br trabalha-se com o tipo Pairwise. Isto quer dizer, cada serviço ou grupo de serviços, recebe um identificador diferente para um mesmo usuário.

Ou seja, o usuário “123” poderá ser conhecido por “ABC” nos serviços do DETRAN enquanto no Tudo Fácil ele é conhecido por “XYZ” e no Blog do Zezinho, por “XPTO”.

Isto é fundamental para a preservação da privacidade dos usuários, dificultando que serviços sejam capazes de cruzar informações sem a devida autorização do usuário mesmo em um cenário de vazamento pois os identificadores são não-correlacionáveis.

Tipos de requisição

De um modo geral o Login Cidadão Gov.br aceita diferentes tipos de resposta:

code, id_token, token id_token

com tipos de permissão:

authorization_code, refresh_token, implicit

Abaixo é exemplificado o passo a passo para uma requisição code/authorization_code.

Passo-a-passo para integrar

O Login Cidadão Gov.br deve ser utilizado com a URL de homologação para validação de aplicações em desenvolvimento e após liberado, deve utilizar somente a URL de produção. As URLs são:

Produção: https://logincidadao.rs.gov.br/
Homologação: https://meu.hml.rs.gov.br/

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

Passo 2

Utilize a url https://{URL}/.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://{URL}/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://{URL}/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.

Importante: Caso o usuário nessa etapa desmarque algum dos escopos pode ocorrer problema com o uso do serviço e o usuário entrar no Painel do rs.gov.br em "Meu Perfil", vá em "Todos os Serviço", clique no serviço em "Detalhes do Serviço" e em "Desativar Serviço" e depois acesse novamente o serviço para reautorizar.

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://{URL}/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://{URL}/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:/{URL}/api/v2/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.

Exemplo de implementação

Para uso interno PROCERGS temos alguns implementações de exemplo disponíveis:

Implementação Java *** ver link correto
Implementação .NET *** ver link correto

Passo 9 - Logout

Para encerrar a sessão com o usuário (logout) faça uma requisição GET para https://{URL}/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

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