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

Para que sua aplicação continue operando corretamente, preparamos este roteiro técnico de migração.

1. Atualização dos Endpoints (v5)

O primeiro passo é atualizar as chamadas de API para a versão 5. Você pode consultar o detalhamento técnico no Swagger de Homologação.

Certifique-se de que sua aplicação aponte para os seguintes caminhos:

Dados do perfil: /api/v5/person
Foto do perfil: /api/v5/person/picture
Dados de empresa (Gov.br): /api/v5/person/login/govbr/dadosempresa

2. Limpeza de Escopos na Autorização

Na versão atual do Login, o escopo profile já inclui de forma implícita os escopos sub, name, first_name, given_name, picture, updated_at, phone_number_verified e email_verified, tornando a referência individual a eles desnecessária na requisição de autorização.

Este comportamento se mantém na nova versão, porém, estes itens agora são tratados exclusivamente como claims do escopo profile. Por esse motivo, você deve remover estes termos da sua chamada de autorização, pois eles não são mais suportados como escopos individuais.

Ao solicitar apenas o escopo profile, todas essas informações continuarão sendo entregues automaticamente na resposta.

3. Padronização de Escopos Obrigatórios

Certifique-se de que sua requisição de autorização utilize os escopos padronizados para garantir o acesso às informações:

Escopo openid: Obrigatório para requisições que desejam receber o id_token no Token Bearer.
Escopo profile: Obrigatório para garantir o acesso aos dados de perfil do usuário.

4. Configuração do Endpoint de Descoberta

A boa prática dita que todo cliente deve consumir o endpoint de descoberta para identificar os serviços disponíveis de forma dinâmica:

/.well-known/openid-configuration

Nota de Transição: Durante o período de migração, é necessário forçar (fixar) o userinfo_endpoint para a URL /api/v5/person, garantindo a compatibilidade com a nova estrutura de dados.

5. Migração para Nova URL

A migração para a nova URL de homologação deve seguir uma ordem específica para garantir a estabilidade do serviço:

Realize todas as alterações técnicas descritas nos itens anteriores na versão atual do login.
Valide que sua aplicação continua operante tanto em Homologação (https://meu.hml.rs.gov.br) quanto em Produção (https://logincidadao.rs.gov.br).
Somente após confirmar o funcionamento com o código ajustado, realize a migração do ambiente de homologação para a nova URL: https://meu-api-hml.pub.hsm.rs.gov.br.

Esta mudança deve ser transparente. Caso ocorra qualquer erro após a virada da URL, o problema deve ser verificado imediatamente com a equipe técnica.

Resumo do Checklist de Migração

[ ] Consultar definições no Swagger atual.
[ ] Alterar endpoints para a versão /api/v5/.
[ ] Limpar a lista de escopos na URL de autorização (remover as claims individuais).
[ ] Garantir a presença dos escopos openid e profile.
[ ] Fixar o userinfo_endpoint para /api/v5/person.
[ ] Validar o código ajustado nas URLs atuais de homologação e produção.
[ ] Após validação, atualizar a URL de homologação para o novo endereço.