Pular para o conteúdo principal

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:

  1. 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
  2. O sistema redireciona o cidadão ao gov.br para autenticação.
  3. Autenticado, o gov.br retorna o cidadão ao portal do município (municipio.gov.br), para o qual a credencial foi emitida.
  4. O portal do município redireciona o cidadão de volta ao sistema Betha, já autenticado e com o acesso liberado.
ATENÇÃO

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ávelAtribuições
Representante do municípioConduz 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 / RevendaFornece 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).
PRAZOS

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:

EtapaNomeResponsávelPrazo estimado
1Permissão para Login ÚnicoMunicípio~3 dias (até 72h de aprovação)
2Credencial de testeMunicípio + Betha~5 dias
3Aprovação da integraçãoMunicípio + Betha~4 dias
4Configuração dos redirecionamentosBetha / RevendaVariável
5Credencial de produçãoMunicí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.

ATENÇÃO

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

  1. Acesse o portal de integração gov.br e clique em Iniciar.

novidade

  1. Entre com a Conta gov.br do responsável institucional.
  2. Preencha as informações do cadastro.

novidade

Dica de preenchimento

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."

  1. Preencha os dados do serviço e clique em Adicionar Dados na Tabela.

novidade

Dica de preenchimento

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.

  1. Clique em Submeter e aguarde a aprovação por e-mail (até 72 horas úteis).

novidade

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

  1. Verifique a aprovação da solicitação de permissão para Login Único no e-mail informado no pedido.

novidade

  1. Acesse o sistema de acompanhamento em solicitacao.servicos.gov.br/processos, localize o protocolo e clique em Responder.

novidade

  1. Preencha os Dados Funcionais do Requisitante.

novidade

Dica de preenchimento
  • 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.
  1. Selecione o produto Autenticação Login Único e preencha os dados técnicos. Clique em Adicionar Dados na Tabela.

novidade

Dica de preenchimento:
  1. Clique em Submeter.

novidade

  1. Clique no botão destacado para baixar o documento com intuito de assiná-lo. Para assinatura do documento, utilize o assinador.iti.br.

novidade

  1. 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.

novidade

  1. 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.
NÃO PULE ESTE PASSO

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].

  1. 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.
ATENÇÃO

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.

Como criptografar as credenciais
  • 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

  1. 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:

  1. 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/).
  2. 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.
  3. Clique em Entrar com gov.br.
  4. Faça o login no gov.br com a conta de teste. Se o gov.br pedir, autorize o compartilhamento dos dados.
  5. Confirme o retorno ao sistema e o acesso à Suíte.
  6. Anexe o vídeo no chamado.
Dicas para a gravação
  • 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.
SE ALGO DER ERRADO NA GRAVAÇÃO
SintomaCausa provávelO que fazer
A Suíte fica em Carregando... depois do loginO 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.brConecte-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 momentoFalha no ambiente de testes da BethaAbra um chamado para a equipe de Aplicações informando o município e a entidade
O botão Entrar com gov.br não apareceA credencial de teste do município ainda não foi registradaConfira se o chamado de credenciamento já foi atendido
  1. Baixe o vídeo anexado ao chamado.
  2. Acesse o sistema de acompanhamento em solicitacao.servicos.gov.br/processos, localize o protocolo aprovado e clique em Responder.

novidade

  1. Faça o upload do vídeo e clique em Desenvolvimento Concluído.

novidade

  1. 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.

  1. Consulte a documentação técnica do Gateway gov.br da Betha em github.com/betha-plataforma/govbr-gateway-exemplos.
  2. Configure os redirecionamentos no servidor do município.
  3. 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

  1. Verifique a aprovação da integração (Etapa 3) no e-mail cadastrado.

novidade

  1. Acesse o sistema de acompanhamento em solicitacao.servicos.gov.br, localize o protocolo aprovado, clique em Responder.

novidade

  1. Clique no botão com símbolo de caneta para iniciar o preenchimento das informações.

novidade

  1. Preencha as informações obrigatórias para a credencial de produção. Clique no botão Atualizar.

novidade

Dica de preenchimento:

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
  • "URL de logout de produção": https://{dominio_da_prefeitura}.gov.br/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:

DOCUMENTAÇÃO COMPLETA GATEWAY

  1. Clique em Enviar. A credencial de produção chegará em até 72h ao e-mail do responsável técnico.

novidade

  1. 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.
NÃO PULE ESTE PASSO

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].

  1. 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.
ATENÇÃO

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:

EtapaResponsávelItem
Etapa 1MunicípioSolicitação de permissão enviada ao gov.br
Etapa 1gov.brAprovação recebida por e-mail
Etapa 2Município + BethaProtocolo respondido com os dados técnicos
Etapa 2MunicípioDocumento assinado digitalmente e enviado
Etapa 2gov.brCredenciais de teste recebidas por e-mail
Etapa 2MunicípioContato com a Betha para preparar o ambiente de testes
Etapa 3BethaVídeo do fluxo completo gravado e anexado ao chamado
Etapa 3MunicípioVídeo enviado ao gov.br com o status Desenvolvimento Concluído
Etapa 3gov.brAprovação da integração confirmada
Etapa 4BethaRedirecionamentos configurados no servidor
Etapa 5Município + BethaCredencial de produção solicitada e recebida
Etapa 5MunicípioContato com a Betha para configurar o ambiente de produção