Login gov.br no sistema do órgão: como funciona a integração

Por que integrar o login gov.br

A integração com o login gov.br tem duas frentes que andam juntas. Uma é administrativa: quem pede é o órgão, por meio de um agente público, no Serviço de Integração aos Produtos do Ecossistema da Identidade Digital GOV.BR. O órgão recebe primeiro uma credencial de homologação. A de produção só sai depois que a Secretaria de Governo Digital (SGD) homologa a integração, e o sistema precisa estar num domínio oficial de governo.

A outra frente é técnica. O protocolo é OpenID Connect, com fluxo de código de autorização e PKCE obrigatório. O nível da conta do cidadão (bronze, prata ou ouro) chega no id_token, e é com ele que o sistema decide o que liberar.

A fonte de tudo o que segue é o roteiro técnico do Login Único, mantido pelo gov.br.

Uma conta para vários serviços públicos

O cidadão já usa a conta gov.br em vários serviços públicos. Quando o sistema do órgão aceita essa conta, deixa de pedir mais um cadastro e mais uma senha. É nesse sentido que o Login Único funciona como SSO no setor público.

Para o órgão, há outro ganho. A integração com a conta gov.br é pré-requisito para usar a Assinatura Eletrônica Avançada, segundo a Portaria SGD/MGI nº 7.076/2024, art. 5º.

O que o sistema deixa de construir

Com o login gov.br, o sistema não guarda senha de cidadão. Também não precisa refazer a validação de identidade, porque o gov.br já informa como a conta foi validada. E quem ativou o segundo fator de autenticação na conta passa a usá-lo também ao entrar no seu sistema.

Isso reduz o que o órgão mantém, mas não encerra o assunto de segurança: sessão, permissões, guarda de tokens e tratamento dos dados continuam com o sistema integrado.

O que o órgão precisa providenciar antes do código

Há uma etapa que só o órgão pode cumprir, e vale começar por ela: sem a credencial de homologação, não há como testar o fluxo de verdade.

Quem pode pedir a integração

Podem usar o serviço órgãos da administração pública, autárquica e fundacional e empresas públicas da União, dos estados e dos municípios. O serviço é gratuito.

O pedido é formalizado por um agente público ou pelo gestor do serviço, com conta gov.br prata ou ouro. Não é o fornecedor que pede a credencial, mesmo quando é ele quem vai implementar.

A integração só é concedida para serviço público com benefício para a sociedade, e não é permitida em área com concorrência de mercado, como serviços bancários.

Estados e municípios têm um passo anterior: precisam ter aderido à Rede Nacional de Governo Digital, conforme o art. 8º da Portaria SGD/MGI nº 7.076/2024.

Do pedido de integração à credencial de produção

O nome oficial do pedido é solicitação de integração. O caminho tem quatro etapas:

1. O agente público preenche os dados do solicitante, do órgão e as informações técnicas do sistema.
2. A Diretoria de Identidade Digital analisa o pedido e envia a credencial de homologação.
3. O órgão desenvolve a integração, informa que está pronto para homologar e envia os dados técnicos do ambiente de produção.
4. Com a credencial de produção, o órgão disponibiliza o serviço e encerra a demanda.

A homologação é feita por vídeo anexado ao processo, com a barra de endereços sempre visível, mostrando o login pelo botão "Entrar com o GOV.BR" (que segue o Design System de Governo), o retorno ao serviço e o logout.

A credencial chega ao Responsável Técnico cifrada com a chave pública PGP que ele anexa ao formulário. Por isso, defina cedo quem ocupa esse papel.

Domínio oficial de governo e uma credencial por sistema

O sistema precisa estar hospedado em domínio oficial de governo, como gov.br, jus.br, leg.br, mp.br ou edu.br. O roteiro de solicitação de credencial também recomenda HTTPS.

A Portaria prevê uma credencial por sistema integrado. Se o órgão tem três sistemas, são três credenciais. O pedido ainda informa uma estimativa de volume e de sazonalidade de uso.

Depois de concluída, a integração não fica parada: troca de URL passa pelo serviço de Pós-Integração, e acompanhar as mudanças da API registradas no roteiro é responsabilidade do órgão.

Como a autenticação gov.br funciona por baixo

A autenticação gov.br usa OpenID Connect sobre OAuth 2.0, no fluxo de código de autorização. Quem já implementou login social reconhece a estrutura; o que pesa na homologação são os detalhes obrigatórios. É o tipo de trabalho da frente de integrações de API.

O fluxo de autenticação, passo a passo

1. O sistema redireciona o cidadão ao endpoint authorize, com response_type=code, os escopos pedidos e os parâmetros de segurança.
2. Depois do login, o gov.br devolve um code na URL de retorno cadastrada. Esse código expira e só vale uma vez.
3. O backend troca o code no endpoint token, com grant_type=authorization_code, autenticando o cliente com CLIENT_ID:CLIENT_SECRET em Base64 no cabeçalho Authorization: Basic.
4. A resposta traz access_token, id_token, expires_in e scope.
5. O sistema valida a assinatura do id_token com a chave pública do endpoint jwk e só então lê os dados.

A tela que recebe o code deve redirecionar para outra página. Os tokens ficam de preferência no backend; se forem ao frontend, vão criptografados.

O id_token vale 60 segundos e pode conter dado sensível, por isso não deve ser enviado a outras APIs. Para chamar uma API protegida, vai só o access_token no cabeçalho.

PKCE, state e nonce

Três parâmetros são obrigatórios:

• state, gerado pelo sistema e conferido no retorno, para confirmar que a resposta pertence à requisição que ele fez;
• nonce, que amarra o id_token àquela autenticação;
• PKCE, com code_challenge e code_challenge_method=S256, e um code_verifier de 43 a 128 caracteres apresentado na troca do código.

Sessão própria e logout

O token do gov.br não deve ser usado como sessão. O sistema autentica pelo gov.br e mantém a própria sessão.

O logout também é obrigatório. O front-end chama o endpoint logout com o post_logout_redirect_uri, e essa URL de retorno precisa estar cadastrada na credencial.

Aplicativo móvel sem WebView

Em aplicativo, o login abre no navegador nativo do aparelho, nunca em WebView. O roteiro aponta a WebView como causa de falha no retorno ao app. Se o login gov.br faz parte de um app de serviço ao cidadão, esse requisito entra no projeto de criação de aplicativos desde o início.

Níveis de conta e o que eles liberam no sistema

A conta gov.br tem três níveis: bronze, prata e ouro. Quanto mais segura a forma de validação, maior o nível.

• Bronze: cadastro validado na Receita Federal ou no INSS, ou presencialmente no INSS e no Balcão gov.br.
• Prata: reconhecimento facial com base na CNH, internet banking de banco credenciado ou SIGEPE, para servidor federal.
• Ouro: reconhecimento facial com base no TSE, QR Code da Carteira de Identidade Nacional ou certificado digital ICP-Brasil de pessoa física.

Qual nível cada funcionalidade exige é decisão do órgão, e essa regra precisa estar escrita antes do código, no levantamento de requisitos.

Como o sistema descobre o nível da conta

O nível chega no próprio id_token, em reliability_info.level, com os valores gold, silver ou bronze. Os selos de confiabilidade vêm em reliability_info.reliabilities, como uma lista de identificadores.

A consulta antiga por API existe só por compatibilidade; integração nova não deve usá-la.

Selos de confiabilidade e o catálogo para exigir prata ou ouro

Cada selo corresponde a uma forma de validação e a um nível: o certificado digital, por exemplo, é o selo 801 e equivale a ouro. A lista completa está no roteiro.

Quando o cidadão entra com nível abaixo do exigido, o sistema pode encaminhá-lo ao Catálogo de Confiabilidades com o parâmetro niveis (por exemplo, niveis=2,3 para prata ou ouro). Lá ele pode subir o nível da conta, e o catálogo o devolve pela redirect_uri.

O que muda no cadastro do sistema

Parte do cadastro deixa de ser digitada pelo cidadão e chega pronta. Isso muda o modelo de dados.

O CPF como identificador

Os campos sub e preferred_username trazem o CPF. Ele vira a chave que liga a conta gov.br ao usuário do sistema.

Se já existe base própria, planeje como cada registro será associado ao CPF no primeiro acesso.

Dados que o sistema recebe e a LGPD

O id_token traz name, social_name (quando existe), email e phone_number. E-mail e telefone só vêm quando verificados, sinalizados por email_verified e phone_number_verified, e não são obrigatórios na conta. A foto, em picture, fica protegida pelo access_token.

O campo amr informa como o cidadão entrou: senha, certificado, banco, QR code do aplicativo ou segundo fator. Novos métodos podem surgir, e a integração deve prever isso. Com o escopo govbr_empresa, o sistema consulta os CNPJs vinculados ao CPF e o papel da pessoa em cada um.

Ao integrar, o órgão passa a responder pelo tratamento desses dados conforme a LGPD. O roteiro pede um Aviso de Privacidade e canais para os pedidos de privacidade dos titulares. Peça só os escopos de que o sistema precisa, e decida desde o desenho quem acessa cada dado, como mostramos em LGPD no desenvolvimento de software.

A divisão do trabalho fica assim: a solicitação de integração e a homologação são do órgão; a implementação, os testes para a homologação, a sessão e o logout são do sistema. A Evo Tech cuida dessa parte técnica em integrações de API, e um sistema novo pode nascer com o login gov.br desde o primeiro desenho, em sistemas sob medida.