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

Content-Type: application/x-www-form-urlencoded,/code>

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

6. Token JWT

O access_token agora é um JWT.

Exemplo de payload:

Boas Práticas:

• Validar assinatura via JWKs
• Validar exp
• Validar iss e aud

7. Checklist de Implementação

• Endpoints atualizados para /api/v5
• Integração com .well-known
• Authorization Code Flow
• Escopos openid profile
• Remoção de escopos antigos
• Validação de JWT
• Testes ponta a ponta

8. Considerações Técnicas

• Prefira discovery ao invés de URLs fixas
• Evite parsing manual de token
• Garanta tratamento de erros OAuth
• Utilize bibliotecas OIDC

Referência: Swagger e documentação oficial do Login Cidadão.