Guia de Migração: Novo Login Cidadão Gov.br em produção

Este documento descreve de forma técnica e orientada a desenvolvedores o processo de migração para o ambiente de novo do Login Cidadão Gov.br.

Objetivo

Padronizar a integração com o Login Cidadão Gov.br utilizando OpenID Connect e JWT, garantindo compatibilidade com o novo modelo de autenticação.

1. Atualização de Endpoints

Atualize todas as integrações de backend para utilizar os endpoints na versão /api/v5/.

Endpoints principais

GET /api/v5/person
GET /api/v5/person/picture
GET /api/v5/person/login/govbr/dadosempresa

2. Descoberta de Configuração (OpenID Connect)

A partir da v5, a configuração do provedor deve ser obtida via endpoint de descoberta:

 GET /.well-known/openid-configuration

Exemplo de uso

curl https://logincidadao.rs.gov.br/.well-known/openid-configuration

Ação obrigatória

Utilize os endpoints retornados dinamicamente (authorization, token, userinfo, jwks);
Evite hardcode de URLs no cliente.

3. Separação Frontend (SPA) e Backend

Frontend (Login do desenvolvedor na aplicação do Login Cidadão Gov.br)

https://login.rs.gov.br

Backend (integração existente)

https://logincidadao.rs.gov.br

Nenhuma mudança é necessária nas chamadas HTTP existentes para backend, a URL se manterá a mesma.

4. Fluxo de Autenticação (OIDC)

Fluxo recomendado: Authorization Code Flow

1. Redirecionamento para login

GET /authorize?response_type=code 
 &client_id=CLIENT_ID 
 &redirect_uri=REDIRECT_URI 
 &scope=openid profile 
 &state=STATE

2. Recebimento do authorization code

REDIRECT_URI?code=AUTH_CODE&state=STATE

3. Troca do código por token

POST /token 
 Content-Type: application/x-www-form-urlencoded 

 grant_type=authorization_code 
 &code=AUTH_CODE 
 &redirect_uri=REDIRECT_URI 
 &client_id=CLIENT_ID 
 &client_secret=CLIENT_SECRET

4. Uso do access token

GET / api /v5/ person

Authorization : Bearer ACCESS_TOKEN

5. Escopos

Escopos obrigatórios:

openid e profile

Mudança importante

Os atributos abaixo não devem mais ser solicitados como escopo :

[

" phone ", " birthdate ", " email_verified ", " family_name ", " middle_name ", " given_name ", " name ",

" picture ", " preferred_username ", "sub", " updated_at ", " public_profile ", " username ", " first_name ",

" last_name ", " full_name ", " city ", "country", " state ", " addresses ", "mobile", " aviseme ", " govbrcnpj "

]

Esses dados agora são retornados automaticamente como claims no escopo profile.

Mapeamento de escopos e claims

Scope	Nome	Claim	Descrição	Somente Leitura
profile	Perfil	sub	Identificador do usuário	Sim
profile	Perfil	updated_at		Sim
profile	Perfil	given_name	Nome	Não
profile	Perfil	family_name	Nome da família	Não
profile	Perfil	name	Nome completo	Não
profile	Perfil	full_name	Nome completo	Não
profile	Perfil	preferred_username	Apelido preferido	Não
profile	Perfil	picture	Foto	Não
profile	Perfil	birthdate	Data de nascimento	Não
profile	Perfil	username	Nome de usuário	Sim
profile	Perfil	surname	Sobrenome	Não
profile	Perfil	first_name	Primeiro nome	Não
profile	Perfil	last_name	Último nome	Não
profile	Perfil	nationality	Nacionalidade	Não
profile	Perfil	city	Cidade	Não
profile	Perfil	state	Estado	Não
profile	Perfil	country	País	Não
email	E-mail	email	Endereço de e-mail	Sim
email	E-mail	email_verified	Verificação do endereço de e-mail	Sim
email	E-mail	email_verified_at	Data de verificação do endereço de e-mail	Sim
address	Endereço	person_addresses	Endereço	Sim
phone_number	Número de telefone	phone_number	Número de telefone	Sim
phone_number	Número de telefone	phone_number_verified	Verificação do número de telefone	Sim
phone_number	Número de telefone	phone_number_verified_at	Data de verificação do número de telefone	Sim
cpf	CPF	cpf	Número do CPF	Sim
id_cards	Documentos de identidade	id_cards	Documentos de identidade	Sim
voter_registration	Título de eleitor	voter_registration	Número do título de eleitor	Sim
voter_registration	Título de eleitor	voter_registration_verified	Verificação do título de eleitor	Sim
voter_registration	Título de eleitor	voter_registration_verified_at	Data de verificação	Sim
govbrcategorias	Categorias	govbrcategorias	Categorias da conta gov.br	Sim
govbrconfiabilidade	Confiabilidade	govbrconfiabilidade	Confiabilidade da conta gov.br	Sim
govbrniveis	Níveis	govbrniveis	Níveis da conta gov.br	Sim
govbrselos	Selos	govbrselos	Selos da conta gov.br	Sim
govbrrecuperacertificadox509	Certificado x509	govbrrecuperacertificadox509	Dados do certificado x509	Sim
govbrempresa	Empresas	govbrempresa	Empresas da conta gov.br	Sim
govbrempresa	Empresas	govbrcnpj		Sim
govbrempresa	Empresas	govbrcategorias		Sim
govbrtipoacesso	Método de autenticação	govbrtipoacesso	Método de autenticação	Sim

6. Token JWT

O access_token agora é um JWT.

Exemplo de payload:

{     
    " iss ": "https://logincidadao.rs.gov.br",     
    " jti ": "b5c1c5ff1bde8fdc001046d2c66a26e0b1c995979c56420d6b1733d13972ffaf7da3a37bf622f2dd",     
    " iat ": 1782310207.625573,     
    " nbf ": 1782310207.625575,     
    "exp": 1782396607.592077,     
    "sub": "be5c7fa3dd0ccb4ab9490152eae385bc8f64c29ec05c8b67921ccee0e745fc68",     
    "scopes": [     
      " openid ",     
      "profile",     
      "email",     
      " cpf ",     
      "logout",     
    ],     
    " aud ": "https://logincidadao.rs.gov.br/ api "  }