Realizando cadastramento da entidade ao gov.br
Guia para o município integrar o Login Único gov.br aos sistemas Betha e disponibilizar autenticação segura aos cidadãos.
Apresentação
O credenciamento ao gov.br habilita o município a oferecer o Login Único como forma de acesso às soluções da Betha. Com isso, o cidadão entra nos serviços da prefeitura usando a mesma conta gov.br que já utiliza nos serviços federais.
O processo é conduzido pelo representante do município, do início ao fim: preenchimento de formulários, assinatura de documentos, contato com a Betha e solicitação das credenciais. A Betha/Revenda entra como apoio técnico, fornecendo os dados de integração e preparando os ambientes de teste e produção quando acionada.
Como funciona a credencial gov.br
Um ponto importante para entender antes de começar: a credencial gov.br é emitida para o domínio do município, não para a Betha. O gov.br autoriza a página da prefeitura, e é ela quem conversa com o Login Único.
O fluxo de autenticação acontece assim:
- O cidadão inicia o acesso em um sistema Betha (Cidadão Web, Protocolo, Tributos), que oferece a opção de login via gov.br
- O sistema redireciona o cidadão ao gov.br para autenticação.
- Autenticado, o gov.br retorna o cidadão ao portal do município (municipio.gov.br), para o qual a credencial foi emitida.
- O portal do município redireciona o cidadão de volta ao sistema Betha, já autenticado e com o acesso liberado.
O gov.br nunca se comunica diretamente com a Betha. A credencial pertence ao domínio oficial do município. Por isso, todas as URLs de redirecionamento de produção precisam usar o domínio gov.br da prefeitura (ver Etapa 5).
Pré-requisitos e responsabilidades
Pré-requisitos
- Sistemas Betha com licença ativa e serviços disponibilizados ao cidadão (ex.: Cidadão Web, Protocolo, Tributos).
- Conta gov.br do responsável institucional do município.
- Domínio gov.br oficial da prefeitura (ex.: saopaulo.sp.gov.br), necessário na etapa de produção.
Responsabilidades
| Responsável | Atribuições |
|---|---|
| Representante do município | Conduz o processo do início ao fim: preenche os formulários, assina os documentos digitalmente, aciona a Betha para preparar os ambientes, envia ao gov.br o vídeo de comprovação gravado pela Betha e solicita a credencial de produção. |
| Betha / Revenda | Fornece os dados técnicos (URLs, IPs, Chave PGP), prepara o ambiente de testes (após a credencial de teste), grava o vídeo de comprovação do fluxo de autenticação e configura o ambiente de produção (após a credencial de produção). |
O processo completo leva em média 20 dias a partir da solicitação. Cada aprovação pelo gov.br pode levar até 72 horas, e ainda há o tempo de assinatura digital dos documentos e de contato com a Betha. Inicie o processo com no mínimo 30 dias de antecedência em relação à data desejada para a implantação
Visão geral das etapas
O credenciamento tem cinco etapas:
| Etapa | Nome | Responsável | Prazo estimado |
|---|---|---|---|
| 1 | Permissão para Login Único | Município | ~3 dias (até 72h de aprovação) |
| 2 | Credencial de teste | Município + Betha | ~5 dias |
| 3 | Aprovação da integração | Município + Betha | ~4 dias |
| 4 | Configuração dos redirecionamentos | Betha / Revenda | Variável |
| 5 | Credencial de produção | Município + Betha | ~4 dias |
Conceitos
Login Único gov.br: serviço federal de autenticação que permite ao cidadão acessar serviços públicos com uma única conta gov.br. No contexto Betha, é usado como opção de login nos sistemas do município.
Credencial de teste (homologação): conjunto de chaves que habilita o fluxo de autenticação no ambiente de homologação, usado para testar a integração antes de colocá-la no ar. É a credencial obtida na Etapa 2.
Credencial de produção: conjunto de chaves que habilita a autenticação no ambiente real, acessível aos cidadãos. É a credencial obtida na Etapa 5, após a integração ser aprovada.
Responsável negocial: pessoa da prefeitura que atua como ponto de contato institucional do processo. Não precisa ser da área técnica.
Responsável técnico: técnico da Betha ou da Revenda responsável pela implantação. É o e-mail deste responsável que recebe as credenciais emitidas pelo gov.br.
Níveis de categoria (Prata e Ouro): níveis de confiabilidade da conta gov.br do cidadão. Definem o grau de segurança exigido no login. Nos formulários de integração, informe Prata e Ouro.
Escopos: dados da conta gov.br que o sistema pede ao gov.br no login. Os sistemas Betha pedem os escopos openid, email, profile, govbr_confiabilidades e govbr_empresa. Todos precisam estar liberados na credencial do município, de teste e de produção.
Gateway de redirecionamento: aplicação disponibilizada pela Betha que é publicada no servidor web da prefeitura para gerenciar os redirecionamentos do Login Único em produção. Configurada na Etapa 4.
Chave PGP: arquivo de criptografia exigido pelo gov.br nos formulários de teste e de produção. Garante a segurança na troca de informações.
A Chave PGP deve ser baixada em chave-publica-pgp.plataforma.betha.cloud e anexada ao campo indicado do formulário. Ela é exigida duas vezes: uma na credencial de teste (Etapa 2) e outra na credencial de produção (Etapa 5)
Etapas do credenciamento
Etapa 1: Permissão para Login Único
Responsável: Município · Prazo: até 72h de aprovação
- Acesse o portal de integração gov.br e clique em Iniciar.
|
|---|
- Entre com a Conta gov.br do responsável institucional.
- Preencha as informações do cadastro.
|
|---|
No campo "Produtos ID em que possui interesse, nome dos sistemas envolvidos e objetivos da integração", coloque: Autenticação Login Único (gov.br). Cite como objetivo "efetuar a autenticação com o gov.br para dar a opção aos munícipes de acessar os serviços prestados de maneira mais rápida e segura."
- Preencha os dados do serviço e clique em Adicionar Dados na Tabela.
|
|---|
No campo "Quais serviços públicos o cidadão acessa", coloque os sistemas que o município tem licença e serviços disponibilizados à população, como Cidadão Web, Protocolo, Tributos.
- Clique em Submeter e aguarde a aprovação por e-mail (até 72 horas úteis).
|
|---|
Resultado: a aprovação da permissão chega ao e-mail cadastrado. Com ela, avance para a Etapa 2.
Etapa 2: Credencial de teste para Login Único
Responsável: Município (preenche e assina) + Betha (fornece dados técnicos e prepara o ambiente) · Prazo: até 72h de aprovação
- Verifique a aprovação da solicitação de permissão para Login Único no e-mail informado no pedido.
|
|---|
- Acesse o sistema de acompanhamento em solicitacao.servicos.gov.br/processos, localize o protocolo e clique em Responder.
|
|---|
- Preencha os Dados Funcionais do Requisitante.
|
|---|
- Responsável Negocial: pessoa da prefeitura que será o ponto de contato institucional.
- Responsável Técnico: técnico da Betha ou Revenda responsável pela implantação.
- Selecione o produto Autenticação Login Único e preencha os dados técnicos. Clique em Adicionar Dados na Tabela.
|
|---|
- No campo "Nome do Sistema", coloque "Cidadão Web".
- No campo "Descrição do Sistema", coloque "xxxxx".
- "Serviços públicos que o cidadão acessa nos sistemas": "Emissão de certidão negativa de imóveis, Emissão de certidão negativa do contribuinte, Emissão de certidão negativa de econômico, Emissão de certidão de baixa de atividade, Emissão de guia de IPTU, Emissão de guia de ISS, Emissão de guia de alvará."
- "Lista de IPs do serviço": "54.232.148.178".
- "Quais níveis de categoria": "Prata e Ouro".
- "URL de retorno Homologação": https://login.test.betha.cloud/servicelogin/govbr, https://login-feature-govbr.betha.cloud/servicelogin/govbr, http://localhost, http://localhost:8080, https://beth.test.betha.cloud.
- "URL de logout de homologação": https://login.test.betha.cloud/servicelogin/logout, https://login-feature-govbr.betha.cloud/servicelogin/logout, http://localhost/servicelogin/logout, http://localhost:8080/servicelogin/logout.
- Chave PGP: Faça o download aqui e depois coloque o arquivo no campo.
- Nos campos "Data prevista para início do desenvolvimento", "Data prevista para homologação" e "Data prevista para disponibilização para a sociedade", coloque 1 semana após a data atual.
- "URL para página inicial do Sistema": https://suite.test.plataforma.betha.cloud/.
- Clique em Submeter.
|
|---|
- Clique no botão destacado para baixar o documento com intuito de assiná-lo. Para assinatura do documento, utilize o assinador.iti.br.
|
|---|
- Faça o upload do documento assinado e clique em Enviar. A credencial de teste chegará ao e-mail do responsável técnico em até 72h.
|
|---|
- No mesmo protocolo, abra a aba Enviar dados/dúvidas e peça os escopos que os sistemas Betha usam no login. Envie o texto abaixo:
Solicito que a credencial deste protocolo seja emitida com os escopos openid, email, profile, govbr_confiabilidades e govbr_empresa no ambiente de homologação do Login Único gov.br.
O formulário do gov.br não tem campo para escolher escopos. Sem o pedido acima, a credencial pode vir sem o escopo govbr_empresa, e o gov.br recusa o login com a mensagem Invalid scope: [govbr_empresa].
- Entre em contato com a Betha para preparar o ambiente de testes. Acesse servicos.betha.com.br/atendimento, informe que deseja liberar o gov.br para a entidade e anexe as credenciais de teste recebidas. A Betha preparará o ambiente para que o fluxo de autenticação possa ser testado.
Anexe as credenciais criptografadas. Manter a criptografia é responsabilidade do município: credenciais anexadas descriptografadas expõem dados sensíveis e não poderão ser atendidas pela Betha, será necessário reenviá-las corretamente.
- Por motivos de segurança, as credenciais do gov.br não devem tramitar de forma pública nos chamados, esses dados precisam estar criptografados.
- O processo recomendado é o uso de criptografia assimétrica com PGP. Para isso, a Betha disponibiliza sua chave pública e recomenda que ela seja utilizada já no processo de homologação do gov.br (ver as Etapas 2 e 5 deste guia).
- Alguns clientes utilizam chaves próprias ou repassam as credenciais sem criptografia. Nesses casos, é necessário criptografá-las novamente com a chave pública da Betha antes de anexá-las ao chamado.
- Recriptografando com a chave pública da Betha
- Faça o download da chave pública da Betha.
- Tenha um programa para criptografar com PGP. Recomendamos o GPG (https://www.gnupg.org/).
- O passo a passo varia conforme o programa. No caso do GPG, crie um arquivo de texto (.txt), salve as credenciais nele e execute no terminal o comando abaixo, ajustando o caminho da chave pública baixada e o do arquivo .txt criado:
gpg --encrypt \
--recipient-file ~/Downloads/chave-publica.asc \
--trust-model always \
--output arquivo.txt.gpg \
arquivo.txt
- O resultado será um arquivo de texto criptografado (arquivo.txt.gpg) com a chave pública da Betha. Esse é o arquivo que pode ser anexado ao chamado.
Resultado: com a credencial de teste emitida e o ambiente preparado pela Betha, a Betha grava o vídeo do fluxo de autenticação e o devolve no chamado. Avance para a Etapa 3.
Etapa 3: Aprovação da integração para Login Único
Responsável: Betha / Revenda (grava o vídeo) + Município (envia o vídeo ao gov.br) · Prazo: até 72h de aprovação
- Aguarde o retorno da Betha no chamado aberto na Etapa 2. Depois de registrar a credencial de teste, a Betha / Revenda grava o vídeo do fluxo completo de autenticação funcionando no ambiente de testes e o anexa ao chamado, comprovando que as credenciais estão configuradas e funcionando.
Como gravar o vídeo (técnicos da Betha e da Revenda)
Antes de gravar, confira:
- A credencial de teste do município já foi registrada no ambiente de testes da Betha. Sem ela, o botão gov.br não aparece.
- Você tem uma conta gov.br de teste no ambiente de homologação do gov.br. Nunca use a conta gov.br de uma pessoa real.
- O gravador de tela captura somente a janela do navegador.
- Você está conectado à VPN da Betha. Fora dela, a Suíte do ambiente de testes pode não carregar.
Passo a passo:
- Acesse a landing page do cliente no ambiente de testes: nomemunicipio.siglaestado.test.plataforma.betha.cloud (exemplo: https://resende.rj.test.plataforma.betha.cloud/). Em produção, o endereço é nomemunicipio.siglaestado.betha.cloud (exemplo: https://resende.rj.betha.cloud/).
- Selecione uma entidade do município e clique em Continuar. As entidades do ambiente de testes têm códigos e nomes diferentes das de produção; qualquer entidade do município serve, pois a credencial vale para o município inteiro.
- Clique em Entrar com gov.br.
- Faça o login no gov.br com a conta de teste. Se o gov.br pedir, autorize o compartilhamento dos dados.
- Confirme o retorno ao sistema e o acesso à Suíte.
- Anexe o vídeo no chamado.
- Faça uma passagem completa sem gravar antes, para resolver verificações e autorizações do gov.br. Grave depois uma passagem limpa, do início ao fim.
- Não mostre senha (somente a máscara do campo), códigos de verificação nem a barra de endereço durante o login.
- Salve o vídeo em MP4 com menos de 10 MB, o limite de anexo do chamado.
- Veja o exemplo de vídeo em https://www.loom.com/share/5196c94569214a04829addcfd6ecedc0.
| Sintoma | Causa provável | O que fazer |
|---|---|---|
| A Suíte fica em Carregando... depois do login | O computador não alcança os arquivos da Suíte de testes. No console do navegador (F12), aparece ERR_CONNECTION_TIMED_OUT em test.betha.com.br | Conecte-se à VPN da Betha e repita o acesso |
| A landing page mostra Não foi possível iniciar o login federado deste município no momento | Falha no ambiente de testes da Betha | Abra um chamado para a equipe de Aplicações informando o município e a entidade |
| O botão Entrar com gov.br não aparece | A credencial de teste do município ainda não foi registrada | Confira se o chamado de credenciamento já foi atendido |
- Baixe o vídeo anexado ao chamado.
- Acesse o sistema de acompanhamento em solicitacao.servicos.gov.br/processos, localize o protocolo aprovado e clique em Responder.
|
|---|
- Faça o upload do vídeo e clique em Desenvolvimento Concluído.
|
|---|
- Aguarde a aprovação por e-mail (até 72 horas úteis).
Resultado: a integração é aprovada por e-mail. Antes de solicitar a produção, configure os redirecionamentos (Etapa 4).
Etapa 4: Configuração dos redirecionamentos
Responsável: Betha / Revenda · Prazo: variável
A Betha disponibiliza uma aplicação (Gateway) que deve ser publicada no servidor web da prefeitura para gerenciar os redirecionamentos do Login Único.
- Consulte a documentação técnica do Gateway gov.br da Betha em github.com/betha-plataforma/govbr-gateway-exemplos.
- Configure os redirecionamentos no servidor do município.
- Esta configuração precisa estar pronta antes de solicitar a credencial de produção (Etapa 5). Caso tenha sido utilizado subdomínio ou subpasta na configuração do servidor web, consulte a documentação do Gateway para saber como proceder.
Etapa 5: Credencial de produção para Login Único
Responsável: Município (preenche e solicita) + Betha (ativa a integração) · Prazo: até 72h de aprovação
- Verifique a aprovação da integração (Etapa 3) no e-mail cadastrado.
|
|---|
- Acesse o sistema de acompanhamento em solicitacao.servicos.gov.br, localize o protocolo aprovado, clique em Responder.
|
|---|
- Clique no botão com símbolo de caneta para iniciar o preenchimento das informações.
|
|---|
- Preencha as informações obrigatórias para a credencial de produção. Clique no botão Atualizar.
|
|---|
Dicas de preenchimento
- "Data prevista para disponibilização à sociedade": Coloque uma semana a partir da data do preenchimento.
- "Quantidade atual de contas (Produção)": xxx.
- "Número de acessos por dia": xxxx.
- "Lista de IPs do serviço": 18.228.71.37, 54.207.92.132, 52.67.237.89.
- "URL de retorno Produção": https://{dominio_da_prefeitura}.gov.br/login, https://{dominio_da_prefeitura}.gov.br/beth
- "URL para página inicial do Sistema": https://{dominio_da_prefeitura}.gov.br/suite
- Redirecionar para: https://betha.cloud
- "URL de logout de produção": https://{dominio_da_prefeitura}.gov.br/logout
- Redirecionar para: https://login.betha.cloud/servicelogin/logout
- Chave PGP: Faça o download aqui e depois coloque o arquivo no campo.
Observação
Substitua {dominio_da_prefeitura} pelo domínio específico da prefeitura no formato Gov.br. Para garantir a integração com o Gov.br, é necessário configurar todas as URLs de redirecionamento para os serviços da Betha utilizando o domínio oficial Gov.br da prefeitura correspondente. Isso assegura a compatibilidade com o processo de autenticação do Gov.br e promove operações seguras de login.
Caso tenha sido utilizado um subdomínio ou subpasta na configuração do servidor web utilizando a aplicação de Gateway se referir a documentação da aplicação para como realizar essa configuração:
- Clique em Enviar. A credencial de produção chegará em até 72h ao e-mail do responsável técnico.
|
|---|
- No mesmo protocolo, abra a aba Enviar dados/dúvidas e peça os escopos novamente, agora para produção. Envie o texto abaixo:
Solicito que a credencial de produção deste protocolo seja emitida com os escopos openid, email, profile, govbr_confiabilidades e govbr_empresa no ambiente de produção do Login Único gov.br.
A credencial de produção é emitida separadamente da de teste. Mesmo que a de teste tenha vindo com o escopo govbr_empresa, a de produção pode vir sem ele, e o login dos cidadãos falha com Invalid scope: [govbr_empresa].
- Entre em contato com a Betha novamente para configurar o ambiente de produção. Ao receber as credenciais, acesse servicos.betha.com.br/atendimento, informe a Betha e anexe as credenciais recebidas. A Betha configurará o ambiente de produção para liberar o Login Único aos cidadãos.
Anexe as credenciais criptografadas. Manter a criptografia é responsabilidade do município: credenciais anexadas descriptografadas expõem dados sensíveis e não poderão ser atendidas pela Betha, será necessário reenviá-las corretamente.
Resultado: com o ambiente de produção configurado pela Betha, o Login Único gov.br fica disponível aos cidadãos nos sistemas do município.
Checklist de acompanhamento
Use esta tabela para acompanhar o progresso do credenciamento:
| Etapa | Responsável | Item |
|---|---|---|
| Etapa 1 | Município | Solicitação de permissão enviada ao gov.br |
| Etapa 1 | gov.br | Aprovação recebida por e-mail |
| Etapa 2 | Município + Betha | Protocolo respondido com os dados técnicos |
| Etapa 2 | Município | Documento assinado digitalmente e enviado |
| Etapa 2 | gov.br | Credenciais de teste recebidas por e-mail |
| Etapa 2 | Município | Contato com a Betha para preparar o ambiente de testes |
| Etapa 3 | Betha | Vídeo do fluxo completo gravado e anexado ao chamado |
| Etapa 3 | Município | Vídeo enviado ao gov.br com o status Desenvolvimento Concluído |
| Etapa 3 | gov.br | Aprovação da integração confirmada |
| Etapa 4 | Betha | Redirecionamentos configurados no servidor |
| Etapa 5 | Município + Betha | Credencial de produção solicitada e recebida |
| Etapa 5 | Município | Contato com a Betha para configurar o ambiente de produção |














