README

Pacote PHP para integração com o sistema de autenticação GovBR, permitindo que aplicações web utilizem o login único do governo brasileiro para autenticar usuários.

Sumário

Autenticação GovBR

Configurar novo serviço no GovBR

Para cada novo sistema configurado para utilizar o Login Único do GovBR, é necessário solicitar as credenciais de acesso. Você deverá ter em mãos as seguintes informações antes de iniciar o processo de solicitação:

Acesso ao seu ambiente de testes configurado com HTTPS.
Dados do responsável negocial: nome completo, cargo, email, celular e CPF.
Dados do responsável técnico: nome completo, cargo, email, celular e CPF.
Chave GPG pública do responsável técnico do sistema, no formato .asc (ver seção Gerar Chave GPG Pessoal).
Dados do sistema: nome do sistema, objetivo do sistema, público-alvo, benefícios ofertados à sociedade, volumetria estimada de usuários.
URLs do sistema (Homologação e Produção): URL(s) do retorno Homologação, URL única para página inicial do sistema homologação e URL(s) de Logout.

Descrição das URLs da aplicação:

URL de Retorno: URL para onde o usuário será redirecionado após o login
URL Inicial: URL da página inicial de login do sistema, onde o usuário poderá iniciar o processo de autenticação via GovBR
URL de Logout: URL para onde o usuário será redirecionado após o logout

Por padrão, ao solicitar efetuar o logout do sistema, o usuário será redirecionado primeiro para fazer logout no sistema gov.br e depois para a URL de Logout do sistema integrado.

Solicitar Credencial do Login Único

As credenciais para acesso aos ambientes de homologação/teste e produção do Login Único devem ser solicitadas por meio do Serviço de Integração aos Produtos do Ecossistema da Identidade Digital GOV.BR.

Para a disponibilização das credenciais de produção, é imprescindível que o sistema a ser integrado esteja hospedado em um domínio oficial de governo (ex.: gov.br, mil.br, edu.br, jus.br, leg.br, def.br, mp.br, tc.br, etc), conforme preconiza o art. 3º da PORTARIA SGD/MGI Nº 7.076, DE 2 DE OUTUBRO DE 2024, preferenciamente utilizando o protocolo HTTPS.

Gerar Chave GPG Pessoal

Caso você ainda não possua, gerar uma Chave PGP pessoal, para, posteriormente, gerar o arquivo de chave no formato .asc para envio na solicitação de credenciais para os ambientes de homologação e produção.

# entrar na pasta
cd ~/.ssh

# gerar chave (A chave precisa ter data final de expiração definida)
gpg --full-generate-key

# Resposta para as perguntas:
# (1) RSA and RSA
# (2) 4096
# (3) 1y (1 ano)

# exportar o arquivo de chave pública de assinatura (Usar o mesmo e-mail usado na hora de gerar a chave)
gpg --armor --export everton.paiva@ufvjm.edu.br > chave_publica.asc

Instruções para acesso ao ambiente de Homologação

Orientações recebidas para ambiente de homologação:

Prezado(a),

Para a implementação da integração, siga os passos do Roteiro de Integração do Login Único (https://acesso.gov.br/roteiro-tecnico).

Para os testes, cada testador deverá criar sua conta no ambiente de homologação do Login Único (https://sso.staging.acesso.gov.br/).

Para criar a conta, utilize os seguintes dados padrão:

- Nome da mãe: MAMÃE
- Data de nascimento: 01/01/1980

Para a disponibilização das credenciais de produção, é imprescindível que o sistema a ser integrado esteja hospedado em um domínio oficial de governo (ex.: gov.br, mil.br, edu.br, jus.br, leg.br, def.br, mp.br, tc.br etc), conforme preconiza o art. 3º da Portaria SGD/MGI nº 7.076/2024.

Favor utilizar este canal de comunicação para esclarecimento de dúvidas. Outras informações relacionadas à integração aos produtos da Identidade Digital GOV.BR podem ser encontradas no site Identidade Digital para Gestores Públicos (www.gov.br/integracaogovbr).

Instruções para acesso ao ambiente de Produção

Descriptografar o arquivo de credenciais enviado via sistema:

gpg --output credenciais.txt --decrypt arquivo-credencais-recebido.txt.gpg

O arquivo credenciais.txt conterá as credenciais de acesso ao ambiente de produção do Login Único.

Documentação Oficial

Roteiro de Integração do Login Único

Instalação

Acesse a raíz do seu projeto PHP e execute o seguinte comando via Composer:

composer require ufvjm/govbr-auth

Utilização

No início dos arquivos que utilizarão a classe GovBrAuth:

require 'vendor/autoload.php';

use Ufvjm\GovBrAuth\GovBrAuth;

Variáveis de Configuração

Sua aplicação deverá ser capaz de preencher a seguintes variáveis de configuração do pacote:

redirectUri: URL de redirecionamento após o login
logoutUri: URL de redirecionamento após o logout
clientId: ID do cliente fornecido pelo GovBR
clientSecret: Segredo do cliente fornecido pelo GovBR
authUrl: URL do ambiente de autenticação (Homologação ou Produção)
apiUrl: URL do ambiente da API (Homologação ou Produção)

Ambientes do GovBR

URL's Homologação:

GOV_BR_ENV_URL=https://sso.staging.acesso.gov.br
GOV_BR_ENV_API_URL=https://api.staging.acesso.gov.br

URL's Produção:

GOV_BR_ENV_URL=https://sso.acesso.gov.br
GOV_BR_ENV_API_URL=https://api.acesso.gov.br

Botão de Login

/** @var GovBrAuth $govbr */
$govbr = new GovBrAuth($redirectUri, $logoutUri, $clientId, $clientSecret, $authUrl, $apiUrl);

$loginUrl = $govbr->generateGovLoginURL();

echo "<a href='$loginUrl'>Entrar com gov.br</a>";

Página de retorno

A página do sistema que foi informada como URL de redirecionamento após o login deve conter o seguinte código para terminar de processar a autenticação:

/** @var GovBrAuth $govbr */
$govbr = new GovBrAuth($redirect_uri, $post_logout_redirect_uri, $client_id, $client_secret, $env_url, $env_api_url);
$logoutURL = $govbr->generatePostLogoutURL();

if (!isset($_SESSION['code_verifier'])) {
    throw new Error('Code Verifier não encontrado na sessão.');
} else {
    $codeVerifier = $_SESSION['code_verifier'];
    try {
        $govbr->loadGovBrData($codeVerifier);

        $pessoa = $govbr->getDadosPessoais();

        // A pessoa foi autenticada com sucesso e a variável $pessoa contém os dados pessoais do usuário
        // Prosseguir com a lógica do sistema (ex.: criar sessão, redirecionar, etc.)
        
    } catch (Exception $e) {
        // Não foi possível autenticar a pessoa
        // ou aconteceu algum problema de comunicação com o GovBR
        // tratar o erro e oferecer um botão de atualizar para tentar a autenticação novamente
    }
}

Botão de Logout

/** @var GovBrAuth $govbr */
$govbr = new GovBrAuth($redirect_uri, $post_logout_redirect_uri, $client_id, $client_secret, $env_url, $env_api_url);
$logoutURL = $govbr->generatePostLogoutURL();

ufvjm / govbr-auth

Maintainers

Details