Como integrar Portal do Cidadão com o gov.br

Data: 19/01/09/2221

Autores:

1. Rafael Passos dos Santos (Assessor)
2. Lucas de Souza e Souza (Assessor)
   

1. Objetivo

Ter informações mais claras de como integrar Portal do Cidadão com a autenticação do gov.br, assim como saber se é possível buscarmos os dados do cidadão, e se buscar, quais são os dados, conforme a User Story: “Eu como vingadores, preciso realizar um estudo de caso de como integrar com o gov.br" presente na Sprint número 81 do time Vingadores.

2. Introdução

Todo usuário do sistema precisa de um Login e Senha que venha ser acessado de forma segura, onde o cidadão cadastrado seja ele mesmo, com seu devido CPF, e seu cadastro seja validado, para que nem uma pessoa venha se passar por outra, diante disso vem a necessidade da integração com GOVBR que irar fazer o papel de trazer essa segurança para o cidadão,  em vista que ele tem uma base dados com 250 milhões de registros (considerando brasileiros, estrangeiros e falecidos), levando em conta que o Cadastro Base do Cidadão - CBC utiliza a base cadastral de pessoas físicas da Receita Federal - CPF.

Diante do Decreto n° 8.936, de 19 de dezembro de 2016, o mecanismo de acesso digital único foi concebido. o conceito da Plataforma de Autenticação Digital do Cidadão, o projeto Login Único, tendo, como destaque o mecanismo de acesso digital único.

Dentro deste contexto, podemos destacar as diversas dificuldades com múltiplas contas de acesso sob responsabilidade do cidadão e variados bancos de dados cadastrais, tais como a duplicidade e inconsistência de informações, falta de integração, dados dispersos e diversas formas de autenticação. Problemas enfrentados por cidadãos ao tentar consumir um serviço público digital oferecido pelo governo federal. Analisando essas dificuldades, o Ministério da Economia (ME), em parceria com o Serviço Federal de Processamento de Dados (Serpro), disponibilizou a plataforma central de autenticação digital do cidadão, o Login Único.

Essa é a nova proposta do Governo federal, para facilitar a identificação e autenticação do cidadão, privilegiando a governança e a convergência autoritativa, e finalmente o controle de acesso unificado. A Plataforma de Cidadania Digital chega para ampliar e simplificar o acesso dos cidadãos brasileiros aos serviços públicos digitais, inclusive por meio de dispositivos móveis.

Este documento é o elemento para orientar a integração da Plataforma de Autenticação Digital do Cidadão – Login Único a qualquer ambiente. A partir de agora, será feita uma revisão sobre a arquitetura de serviço e alguns conceitos utilizados pela Plataforma, além de uma explicação sobre procedimentos administrativos essenciais para autorizar o acesso à Plataforma.

Este documento contém as formas de chamadas a operações, parâmetros e métodos de integração, e, por último, os procedimentos para permitir a conectividade entre os ambientes de implantação.

3. Desenvolvimento

Conceitos

• Escopos e Atributos

São conjuntos de informações fornecidos a quem possui autorização.

Os escopos com atributos estão disponíveis no Login Único?

1. openid, email, phone, profile(CPF, Nome, e-mail, telefone, foto);
2. govbr_empresa(CNPJ, Nome Fantasia, CPF do Responsável, Nome do Responsável, Atuação no CNPJ)
3. govbr_confiabilidades(selos de confiabilidade).

As funcionalidades necessárias para atender à integração

• Solicitação e Alteração de Configuração

Solicitação de Configuração

Para utilização do sistema Login Único, há necessidade de liberar os ambientes para aplicação cliente possa utilizar. Essa liberação ocorre pelos passos:

1. Preenchimento do Plano de Integração. Leia atentamente as instruções de preenchimento que constam no próprio documento/
2. Geração da Chave PGP - A chave PGP é solicitada para transmissão das credenciais de forma segura. Informações sobre como administrar as chaves PGP para credenciais do Login Único.

Para encaminhamento das informações aos integrantes da Secretaria de Governança Digital (SGD) do Ministério da Economia (ME), deverá seguir as orientações:

1. A assinatura do documento deverá ser pelo Representante Legal do órgão ou entidade dona do serviço a ser integrado, e Representante Técnico. Ambos devem constar na tabela do item 3. O documento deve ter o formato “.doc”, “.pdf” ou “.odt”;
2. A chave púbica PGP deverá ser gerada pelo Representante Legal do órgão ou entidade dona do serviço a ser integrado, e Representante Técnico. Ambos devem constar na tabela do item 3;
3. Com recebimento do documento e da chave pública PGP, todos com correta completude das informações, a credencial de teste ou produção será gerada e encaminhada aos e-mails dos representantes descritos na tabela do item 3 deste documento;
4. O Assunto do e-mail de liberação de chaves terá o padrão: CHAVE DO AMBIENTE [nome do ambiente] – [Nome do Órgão/Entidade] – UF;
5. A chave de produção somente será emitida após comprovação da integração com sucesso ao ambiente de TESTE. Para fins de comprovação, deve ser encaminhado para o e-mail com vídeo da integração em funcionamento, junto com o Plano de Integração preenchido com as URLs do ambiente de produção do órgão/entidade e chave pública PGP do Órgão/Entidade. ATENÇÃO: SÃO PERMITIDAS APENAS URLS com HTTPS NO AMBIENTE DE PRODUÇÃO.
6. O Órgão/Entidade DEVEavisar, por meio de email, que a integração está disponível para sociedade;
7.  

O endereço de envio encontra-se no Plano de Integração.

Alteração de Configuração

Para alterar as configurações da credencial, deverá seguir as orientações:

1. Enviar e-mail informando o CLIENT_ID no qual as alterações deverão ser aplicadas;
2. O Assunto do e-mail de alteração de chaves deve seguir o padrão: ALTERAÇÃO EM CHAVE DO AMBIENTE [nome do ambiente] – [client_id];
3. No corpo do e-mail de alteração, o responsável deve informar

O endereço de envio encontra-se no Plano de Integração.

• Administração das chaves PGP para credenciais do Login Único

Como criar um par de chaves PGP

O PGP (abreviação de Pretty Good Privacy, ou Muito Boa Privacidade) é um programa de criptografia de chave pública e privada altamente seguro e utilizado para proteção de conteúdo enviado por correio eletrônico.

Orientaremos como criar par de chaves PGP por meio do programa Gpg4win (versão windows), porém existem outras aplicativos permitem geração.

Sigam os passos para criação:

1. 1. Realize download do aplicativo Gpg4win ;
   2. Siga os passos até finalizar instalação;
   3. Execute o programa Kleopatra.
   
   4. Selecione item do Menu Arquivo / Novo Par de chaves;
   
   5. Selecione opção Criar um par de chaves OpenPGP pessoal;
   
   6. Informe o Nome e o Email, marque a opção Proteger a chave com senha e clique no botão Criar. O nome e email deverão ser algum dos presentes no Item Responsáveis pela Integração no Plano de Integração
   
   7. Concluída a criação clique no botão Terminar;
   
   8. Selecione a chave criada, clique item do Menu Arquivo / Exportar para salvar chave pública;
   
   9. Enviar chave pública junto com Plano de Integração.

Como ler arquivo da credencial com chave PGP

Orientaremos como ler arquivo por meio do programa Gpg4win (versão windows), porém existem outros aplicativos que podem ser empregados para esta finalidade.

Sigam os passos para criação:

1. Realize download do aplicativo Gpg4win ;
2. Siga os passos até finalizar instalação;
3. Execute o programa Kleopatra.

4. Selecione item do Menu Arquivo / Descriptografar/Verificar;

5. Selecione o arquivo com a credencial criptografada, digite a senha da geração do par de chaves, clique no botão OK;

6. Selecione a pasta deseja salvar o aquivo descriptografado e clique no botão Save all;

Passo-a-Passo para Integrar

• Autenticação

Para que a autenticação aconteça, todo o canal de comunicação deve ser realizado com o protocolo HTTPS. Será feito um redirecionamento para uma URL de autorização do Login Único e, após a autenticação ser concluída, retornará um código de autenticação para a aplicação cliente com intuito de adquirir um ticket de acesso para os serviços protegidos.

A utilização da autenticação do Login Único depende dos seguintes passos:

https://sso.staging.acesso.gov.br/authorize?response_type=code&client_id=ec4318d6-f797-4d65-b4f7-39a33bf4d544&scope=openid+email+phone+profile&redirect_uri=http%3A%2F%2Fappcliente.com.br%2Fphpcliente%2Floginecidadao.Php&nonce=3ed8657fd74c&state=358578ce6728b

4. Após a autorização, a requisição é retornada para a URL especificada no redirect_uri do serviço https://sso.staging.acesso.gov.br/authorize, enviando os parâmetros:

5. Após autenticado, o provedor redireciona para a página de autorização. O usuário habilitará o consumidor no sistema para os escopos solicitados. Caso o usuário da solicitação autorize o acesso, é gerado um “ticket de acesso”, conforme demonstra na especificação OpenID Connect ;
6. Para obter o ticket de acesso, o consumidor deve fazer uma requisição POST para o endereço https://sso.staging.acesso.gov.br/token passando as seguintes informações:

Parâmetros do Header para requisição Post https://sso.staging.acesso.gov.br/token

Variavél	Descrição
Content-Type	Tipo do conteúdo da requisição que está sendo enviada. Nesse caso estamos enviando como um formulário
Authorization	Informação codificada em Base64, no seguinte formato: CLIENT_ID:CLIENT_SECRET (senha de acesso do serviço consumidor)(utilizar codificador para Base64  para gerar codificação). A palavra Basic deve está antes da informação.

Exemplo de header:

Content-Type:application/x-www-form-urlencoded
Authorization: Basic
ZWM0MzE4ZDYtZjc5Ny00ZDY1LWI0ZjctMzlhMzNiZjRkNTQ0OkFJSDRoaXBfTUJYcVJkWEVQSVJkWkdBX2dRdjdWRWZqYlRFT2NWMHlFQll4aE1iYUJzS0xwSzRzdUVkSU5FcS1kNzlyYWpaZ3I0SGJuVUM2WlRXV1lJOA==

Parâmetros do Body para requisição Post https://sso.staging.acesso.gov.br/token

Exemplo de query

curl -X POST -d 'grant_type=authorization_code&code=Z85qv1&redirect_uri=http%3A%2F%2Fappcliente.com.br%2Fphpcliente%2Floginecidadao.Php' https://sso.staging.acesso.gov.br/token

O serviço retornará, em caso de sucesso, no formato JSON, as informações conforme exemplo:

{
        "access_token": "(Token de acesso a recursos protegidos do autenticador, bem como serviços do Login Único.)",
        "id_token": "(Token de autenticação com informações básicas do usuário.)",
        "token_type": "(O tipo do token gerado. Padrão: Bearer)",
        "expires_in": "(Tempo de vida do token em segundos.)"
}

7. De posse das informações do json anterior, a aplicação consumidora está habilitada para consultar dados de recursos protegidos, que são as informações e método de acesso do usuário ou serviços externos do Login Único.
8. Antes de utilizar as informações do JSON anterior, de forma especifica os ACCESS_TOKEN e ID_TOKEN, para buscar informações referente ao método de acesso e cadastro básico do usuário, há necessidade da aplicação consumidora validar se as informações foram geradas pelos serviços do Login Único. Esta validação ocorrerá por meio da consulta da chave pública disponível no serviço https://sso.staging.acesso.gov.br/jwk. Para isso, verificar o método processToClaims dos Exemplos de Integração.
9. A utilização das informações do ACCESS_TOKEN e ID_TOKEN ocorrerá ao extrair do JSON codificado os seguintes parâmetros:

JSON do ACCESS_TOKEN

{
        "sub": "(CPF do usuário autenticado)",
        "aud": "Client ID da aplicação onde o usuário se autenticou",
        "scope": ["(Escopos autorizados pelo provedor de autenticação.)"],
        "amr": ["(Listagem dos fatores de autenticação do usuário. Pode ser “passwd” se o mesmo logou fornecendo a senha, “x509” se o mesmo utilizou certificado digital ou certificado em nuvem, ou “bank” para indicar utilização de conta bancária para autenticar. Esse último seguirá com número de identificação do banco, conforme código de compensação do Bacen presente ao final da explicação.)"],
        "iss": "(URL do provedor de autenticação que emitiu o token.)",
        "exp": "(Data/hora de expiração do token)",
        "iat": "(Data/hora em que o token foi emitido.)",
        "jti": "(Identificador único do token, reconhecido internamente pelo provedor de autenticação.)",
        "cnpj": "CNPJ vinculado ao usuário autenticado. Atributo será preenchido quando autenticação ocorrer por certificado digital de pessoal jurídica."
}

Observações para ACCESS_TOKEN:

• Caso conta do cidadão esteja com segundo fator de autenticação ativado, quando o atributo AMR vier com passwd, aparecerão os conteúdos mfa (indica presença de segundo fator) e otp (forma de segundo fator com código encaminhado pelo aplicativo gov.br).
• Documento para verificação do Código de Compensação dos possíveis bancos integrados ao Login Único:Documento verificar Código de Compensação dos Bancos.

JSON do ID_TOKEN

{
        "sub": "(CPF do usuário autenticado.)",
        "amr": ["(Listagem dos fatores de autenticação do usuário. Pode ser “passwd” se o mesmo logou fornecendo a senha, “x509” se o mesmo utilizou certificado digital ou certificado em nuvem, ou “bank” para indicar utilização de conta bancária para autenticar. Esse último seguirá com número de identificação do banco, conforme código de compensação do Bacen presente ao final da explicação.)"],
        "picture": "(URL de acesso à foto do usuário cadastrada no Gov.br. A mesma é protegida e pode ser acessada passando o access token recebido.)",
        "name": "(Nome cadastrado no Gov.br do usuário autenticado.)",
        "phone_number_verified": "(Confirma se o telefone foi validado no cadastro do Gov.br. Poderá ter o valor "true" ou "false")",
        "phone_number": "(Número de telefone cadastrado no Gov.br do usuário autenticado. Caso o atributo phone_number_verified do ID_TOKEN tiver o valor false, o atributo phone_number não virá no ID_TOKEN)",
        "email_verified": "(Confirma se o email foi validado no cadastro do Gov.br. Poderá ter o valor "true" ou "false")",
        "email": "(Endereço de e-mail cadastrado no Gov.br do usuário autenticado. Caso o atributo email_verified do ID_TOKEN tiver o valor false, o atributo email não virá no ID_TOKEN)",
        "cnpj": "(CNPJ vinculado ao usuário autenticado. Atributo será preenchido quando autenticação ocorrer por certificado digital de pessoal jurídica.)"
}

Observações para ID_TOKEN:

• Os paramêtros email,phone_number,picture não são obrigatórios. Ambos podem estar preenchidos ou não.
• Caso conta do cidadão esteja com segundo fator de autenticação ativado, quando o atributo AMR vier com passwd, aparecerão os conteúdos mfa (indica presença de segundo fator) e otp (forma de segundo fator com código encaminhado pelo aplicativo gov.br).
• Documento para verificação do Código de Compensação dos possíveis bancos integrados ao Login Único:Documento verificar Código de Compensação dos Bancos.

10. Para solicitação do conteúdo da foto salva no cadastro do cidadão, deverá acessar, pelo método GET, o serviço https://sso.staging.acesso.gov.br/userinfo/picture e acrescentar o atributo Authorization ao header do HTTP da requisição:

O serviço retornará, em caso de sucesso a informação em formato Base64

11. Para verificar quais níveis da conta do cidadão está localizada, deverá acessar, pelo método GET, o serviço https://api.staging.acesso.gov.br/confiabilidades/v3/contas/cpf/niveis?response-type=ids

Parâmetros para requisição GET https://api.staging.acesso.gov.br/confiabilidades/v3/contas/cpf/niveis?response-type=ids

VariavélDescriçãoAuthorizationpalavra Bearer e o ACCESS_TOKEN da requisição POST do https://sso.staging.acesso.gov.br/tokencpfCPF do cidadão (sem ponto, barra etc).

A resposta em caso de sucesso retorna sempre um array de objetos JSON no seguinte formato:

[
        {
        "id": "(Identificação para reconhecer o nível)",
        "dataAtualizacao": "(Mostra a data e hora que ocorreu atualização do nível na conta do usuário. A mascará será YYYY-MM-DD HH:MM:SS)"
        }
]

Verificar quais níveis estão disponíveis, acesse Resultado Esperado do Acesso ao Serviço de Confiabilidade Cadastral (Níveis)

12. Para verificar quais catagorias da conta do cidadão está localizado, deverá acessar, pelo método GET, o serviço https://api.staging.acesso.gov.br/confiabilidades/v3/contas/cpf/categorias?response-type=ids

Parâmetros para requisição GET https://api.staging.acesso.gov.br/confiabilidades/v3/contas/cpf/categorias?response-type=ids

A resposta em caso de sucesso retorna sempre um array de objetos JSON no seguinte formato:

[
        {
        "id": "(Identificação para reconhecer a categoria)",
        "dataAtualizacao": "(Mostra a data e hora que ocorreu atualização da categoria na conta do usuário. A mascará será YYYY-MM-DD HH:MM:SS)"
        }
]

Verificar quais categorias estão disponíveis, acesse Resultado Esperado do Acesso ao Serviço de Confiabilidade Cadastral (Categorias)

13. Para verificar quais selos de confiabilidade a conta do cidadão possui, deverá acessar, pelo método GET, o serviço https://api.staging.acesso.gov.br/confiabilidades/v3/contas/cpf/confiabilidades?response-type=ids

Parâmetros para requisição GET https://api.staging.acesso.gov.br/confiabilidades/v3/contas/cpf/confiabilidades?response-type=ids

A resposta em caso de sucesso retorna sempre um array de objetos JSON no seguinte formato:

[
        {
        "id": "(Identificação para reconhecer a confiabilidade)",
        "dataAtualizacao": "(Mostra a data e hora que ocorreu atualização da confiabilidade na conta do usuário. A mascará será YYYY-MM-DD HH:MM:SS)"
        }
]

Verificar quais selos de confiabilidade estão disponíveis, acesse Resultado Esperado do Acesso ao Serviço de Confiabilidade Cadastral (Selos)

• Resultado Esperado do Acesso ao Serviço de Confiabilidade Cadastral (Níveis)

As categorias existentes no Login Único são:

[
        {
                "id": "1 (conta_basica)",
                "dataAtualizacao": "(Mostra a data e hora que ocorreu atualização da categoria na conta do usuário. A mascará será YYYY-MM-DD HH:MM:SS)"
        },

        {
                "id": "2 (verificada)",
                "dataAtualizacao": "(Mostra a data e hora que ocorreu atualização da categoria na conta do usuário. A mascará será YYYY-MM-DD HH:MM:SS)"
        },

        {
                "id": "3 (comprovada)",
                "dataAtualizacao": "(Mostra a data e hora que ocorreu atualização da categoria na conta do usuário. A mascará será YYYY-MM-DD HH:MM:SS)"
        }
]

• Resultado Esperado do Acesso ao Serviço de Confiabilidade Cadastral (Categorias)

As categorias existentes no Login Único são:

[
        {
                "id": "101 (carrosel_perguntas_previdencia)",
                "dataAtualizacao": "(Mostra a data e hora que ocorreu atualização da categoria na conta do usuário. A mascará será YYYY-MM-DD HH:MM:SS)"
        },

        {
                "id": "102 (carrosel_perguntas)",
                "dataAtualizacao": "(Mostra a data e hora que ocorreu atualização da categoria na conta do usuário. A mascará será YYYY-MM-DD HH:MM:SS)"
        },

        {
                "id": "201 (servidor_publico)",
                "dataAtualizacao": "(Mostra a data e hora que ocorreu atualização da categoria na conta do usuário. A mascará será YYYY-MM-DD HH:MM:SS)"
        },
        {
                "id": "202 (biometria_facial)",
                "dataAtualizacao": "(Mostra a data e hora que ocorreu atualização da categoria na conta do usuário. A mascará será YYYY-MM-DD HH:MM:SS)"
        },

        {
                "id": "203 (balcao_presencial)",
                "dataAtualizacao": "(Mostra a data e hora que ocorreu atualização da categoria na conta do usuário. A mascará será YYYY-MM-DD HH:MM:SS)"
        },

        {
                "id": "204 (internet_banking)",
                "dataAtualizacao": "(Mostra a data e hora que ocorreu atualização da categoria na conta do usuário. A mascará será YYYY-MM-DD HH:MM:SS)"
        },
        {
                "id": "301 (biometria_individualizada)",
                "dataAtualizacao": "(Mostra a data e hora que ocorreu atualização da categoria na conta do usuário. A mascará será YYYY-MM-DD HH:MM:SS)"
        },

        {
                "id": " 302 (certificado_digital)",
                "dataAtualizacao": "(Mostra a data e hora que ocorreu atualização da categoria na conta do usuário. A mascará será YYYY-MM-DD HH:MM:SS)"
        }

]

• Resultado Esperado do Acesso ao Serviço de Confiabilidade Cadastral (Selos)

Os selos existentes no Login Único são:

[
        {
                "id": "101 (kba_previdencia)",
                "dataAtualizacao": "(Mostra a data e hora que ocorreu atualização da confiabilidade na conta do usuário. A mascará será YYYY-MM-DD HH:MM:SS)"
        },

        {
                "id": "201 (cadastro_basico)",
                "dataAtualizacao": "(Mostra a data e hora que ocorreu atualização da confiabilidade na conta do usuário. A mascará será YYYY-MM-DD HH:MM:SS)"
        },

        {
                "id": "301 (servidor_publico)",
                "dataAtualizacao": "(Mostra a data e hora que ocorreu atualização da confiabilidade na conta do usuário. A mascará será YYYY-MM-DD HH:MM:SS)"
        },
        {
                "id": "401 (biovalid_facial)",
                "dataAtualizacao": "(Mostra a data e hora que ocorreu atualização da confiabilidade na conta do usuário. A mascará será YYYY-MM-DD HH:MM:SS)"
        },

        {
                "id": "501 (balcao_sat_previdencia)",
                "dataAtualizacao": "(Mostra a data e hora que ocorreu atualização da confiabilidade na conta do usuário. A mascará será YYYY-MM-DD HH:MM:SS)"
        },

        {
                "id": "502 (balcao_denatran)",
                "dataAtualizacao": "(Mostra a data e hora que ocorreu atualização da confiabilidade na conta do usuário. A mascará será YYYY-MM-DD HH:MM:SS)"
        },

        {
                "id": "503 (balcao_correios)",
                "dataAtualizacao": "(Mostra a data e hora que ocorreu atualização da confiabilidade na conta do usuário. A mascará será YYYY-MM-DD HH:MM:SS)"
        },

        {
                "id": "504 (balcao_cadastro_presencial_govbr)",
                "dataAtualizacao": "(Mostra a data e hora que ocorreu atualização da confiabilidade na conta do usuário. A mascará será YYYY-MM-DD HH:MM:SS)"
        },

        {
                "id": "601 (balcao_nai_previdencia)",
                "dataAtualizacao": "(Mostra a data e hora que ocorreu atualização da confiabilidade na conta do usuário. A mascará será YYYY-MM-DD HH:MM:SS)"
        },

        {
                "id": "602 (bb_internet_banking)",
                "dataAtualizacao": "(Mostra a data e hora que ocorreu atualização da confiabilidade na conta do usuário. A mascará será YYYY-MM-DD HH:MM:SS)"
        },

        {
                "id": "603 (banrisul_internet_banking)",
                "dataAtualizacao": "(Mostra a data e hora que ocorreu atualização da confiabilidade na conta do usuário. A mascará será YYYY-MM-DD HH:MM:SS)"
        },

        {
                "id": "604 (bradesco_internet_banking)",
                "dataAtualizacao": "(Mostra a data e hora que ocorreu atualização da confiabilidade na conta do usuário. A mascará será YYYY-MM-DD HH:MM:SS)"
        },

        {
                "id": "605 (caixa_internet_banking)",
                "dataAtualizacao": "(Mostra a data e hora que ocorreu atualização da confiabilidade na conta do usuário. A mascará será YYYY-MM-DD HH:MM:SS)"
        },

        {
                "id": "606 (brb_internet_banking)",
                "dataAtualizacao": "(Mostra a data e hora que ocorreu atualização da confiabilidade na conta do usuário. A mascará será YYYY-MM-DD HH:MM:SS)"
        },

        {
                "id": "607 (sicoob_internet_banking)",
                "dataAtualizacao": "(Mostra a data e hora que ocorreu atualização da confiabilidade na conta do usuário. A mascará será YYYY-MM-DD HH:MM:SS)"
        },

        {
                "id": "608 (santander_internet_banking)",
                "dataAtualizacao": "(Mostra a data e hora que ocorreu atualização da confiabilidade na conta do usuário. A mascará será YYYY-MM-DD HH:MM:SS)"
        },

        {
                "id": "701 (tse_facial)",
                "dataAtualizacao": "(Mostra a data e hora que ocorreu atualização da confiabilidade na conta do usuário. A mascará será YYYY-MM-DD HH:MM:SS)"
        },

        {
                "id": "801 (certificado_digital)",
                "dataAtualizacao": "(Mostra a data e hora que ocorreu atualização da confiabilidade na conta do usuário. A mascará será YYYY-MM-DD HH:MM:SS)"
        }
]

• Acesso ao serviço de Catálogo de Confiabilidades (Selos)

1. Com usuário autenticado, deverá acessar, por meio do método GET ou POST, a URL https://confiabilidades.staging.acesso.gov.br/

Parâmetros da Query para requisição GET https://confiabilidades.staging.acesso.gov.br/

Observações sobre as variáveis do serviço de catálogo

• Acesso ao Serviço de Log Out

Parâmetros da Query para requisição GET https://sso.staging.acesso.gov.br/logout

Exemplo 1 de execução no front end em javascript

var form = document.createElement("form");
    form.setAttribute("method", "post");
form.setAttribute("action", "https://sso.staging.acesso.gov.br/logout?post_logout_redirect_uri=https://www.minha-aplicacao.gov.br/retorno.html");
document.body.appendChild(form);
    form.submit();

Exemplo 2 de execução no front end em javascript

window.location.href='https://sso.staging.acesso.gov.br/logout?post_logout_redirect_uri=https://www.minha-aplicacao.gov.br/retorno.html';

• Acesso ao Serviço de Cadastro de Pessoas Jurídicas

O Login Único disponibiliza dois serviços para acesso a informações de Pessoa Jurídica. O primeiro apresenta todos os CNPJs cadastrados para um determinado usuário. O segundo, utiliza desse CNPJ para extrair informações cadastradas no Login Único para aquela pessoa e empresa.

Para acessar o serviço que disponibiliza os CNPJs vinculados a um determinado usuário, é necessário o seguinte:

1. Na requisição de autenticação, adicionar o escopo “govbr_empresa“, conforme exemplo:

Exemplo de requisição

https://sso.staging.acesso.gov.br/authorize?response_type=code&client_id=minha-aplicacao&scope=openid+email+phone+profile+govbr_empresa&redirect_uri=http%3A%2F%2Fappcliente.com.br%2Fphpcliente%2Floginecidadao.Php&nonce=3ed8657fd74c&state=358578ce6728b

Parâmetros para requisição GET https://api.staging.acesso.gov.br/empresas/v2/empresas?filtrar-por-participante=cpf

3. O resultado em formato JSON é a lista de CNPJs do CPF autenticado, conforme o exemplo abaixo:

Exemplo de requisição

[
        {
        "cnpj": "(Número de CNPJ da empresa vinculada)",
        "razaoSocial": "(Razão Social (Nome da empresa) cadastrada na Receita Federal)",
        "dataCriacao": "(Mostra a data e hora da vinculação do CNPJ a conta do usuário. A mascará será YYYY-MM-DD HH:MM:SS)"
        }
]

4. Com o usuário autenticado, a aplicação cliente deverá acessar, por meio do método GET, a URL https://api.staging.acesso.gov.br/empresas/v2/empresas/cnpj/participantes/cpf enviando as seguintes informações:

Parâmetros para requisição GET https://api.staging.acesso.gov.br/empresas/v2/empresas/cnpj/participantes/cpf

5. O resultado em formato JSON é o detalhamento do CNPJ do CPF autenticado, conforme o exemplo abaixo:

Exemplo de requisição

{
"cpf": "(Número do CPF que pode atuar com empresa)",
"atuacao": "(Papel do CPF na empresa na Receita Federal. O conteúdo será SOCIO, CONTADOR, REPRESENTANTE_LEGAL ou NAO_ATUANTE. O NAO_ATUANTE representa CPF possui certificado digital de pessoa jurídica, porém não possui um papel na empresa na base da Receita Federal. Se CPF for colaborador, atributo atuacao não aparecerá)",
"cadastrador": "(Identifica se o CPF pode realizar cadastro de colaboradores para CNPJ. O conteúdo false determinar que o CPF é um colaborador da empresa. O conteúdo true determina CPF é representante da empresa com certificado digital de pessoal jurídica)",
"cpfCadastrador": "(CPF responsável por realizar cadastro do Colaborador. Se CPF apresentar atributo cadastrador com conteúdo true, o atributo cpfCadastrador não aparecerá)",
"dataCriacao": "(Mostra a data e hora da vinculação do CPF ao CNPJ. A mascará será YYYY-MM-DD HH:MM:SS)",
"dataExpiracao": "(Mostra a data e hora que o CPF poderá atuar com CNPJ. A mascará será YYYY-MM-DD HH:MM:SS)"
}

• Acesso ao Serviço de Revalidação de Senha

Para que a revalidação aconteça, todo o canal de comunicação deve ser realizado com o protocolo HTTPS. Será feito um redirecionamento para URL de autorização especifica do Login Único e, após a revalidação ser concluída, retornará um código de autenticação para a aplicação cliente com intuito de adquirir um ticket de acesso para revalidação da senha e continuação do fluxo do sistema.

Esta estrutura precisará autorização específica a ser solicitada para Ministério da Economia.

Passos para processo:

1. Requisição GET para endereço https://oauth.staging.acesso.gov.br/v1/authorize passando as seguintes informações:

Exemplo de requisição:

Exemplo de requisição:

https://oauth.staging.acesso.gov.br/v1/authorize?response_type=code&client_id=ec4318d6-f797-4d65-b4f7-39a33bf4d544&redirect_uri=http%3A%2F%2Fappcliente.com.br%2Fphpcliente%2Floginecidadao.Php&scope=password-validationstate=exASJANS12sa

2. Após a autorização, a requisição é retornada para a URL especificada no redirect_uri do serviço https://oauth.staging.acesso.gov.br/v1/authorize, enviando os parâmetros:

3. Para obter o novo ticket de acesso, o consumidor deve fazer uma requisição POST para o endereço https://oauth.staging.acesso.gov.br/v1/token passando as seguintes informações:

Parâmetros do Header para requisição Post https://oauth.staging.acesso.gov.br/v1/token

Variavél	Descrição
Content-Type	Tipo do conteúdo da requisição que está sendo enviada. Nesse caso estamos enviando como um formulário (application/x-www-form-urlencoded)
Authorization	Informação codificada em Base64, no seguinte formato: CLIENT_ID:CLIENT_SECRET (senha de acesso do serviço consumidor)(utilizar codificador para Base64  para gerar codificação). A palavra Basic deve está antes da informação.

Exemplo de header:

Content-Type:application/x-www-form-urlencoded
Authorization: Basic
ZWM0MzE4ZDYtZjc5Ny00ZDY1LWI0ZjctMzlhMzNiZjRkNTQ0OkFJSDRoaXBfTUJYcVJkWEVQSVJkWkdBX2dRdjdWRWZqYlRFT2NWMHlFQll4aE1iYUJzS0xwSzRzdUVkSU5FcS1kNzlyYWpaZ3I0SGJuVUM2WlRXV1lJOA==

Parâmetros da Query para requisição Post https://oauth.staging.acesso.gov.br/v1/token

Exemplo de query

https://oauth.staging.acesso.gov.br/v1/token?grant_type=authorization_code&code=8bfac143-c4ca-daf-8ea8-517f0d93db7a&redirect_uri=http%3A%2F%2Fappcliente.com.br%2Fphpcliente%2Floginecidadao.Php&client_id=ec4318d6-f797-4d65-b4f7-39a33bf4d544

O serviço retornará, em caso de sucesso, no formato JSON, as informações conforme exemplo:

{
        "access_token": "(Token de acesso a recursos protegidos do autenticador, bem como serviços do Login Único.)",
        "token_type": "(O tipo do token gerado. Padrão: Bearer)",
        "expires_in": "(Tempo de vida do token em segundos.)"
}

4. De posse das informações do json anterior, a aplicação consumidora está habilitada para concluir revalidação da senha.
5. Antes de utilizar as informações do JSON anterior, de forma especifica o ACCESS_TOKEN, para revalidação da senha, há necessidade da aplicação consumidora validar se as informações foram geradas pelos serviços do Login Único. Esta validação ocorrerá por meio da consulta da chave pública disponível no serviço https://oauth.staging.acesso.gov.br/v1/jwks. Para isso, verificar o método processToClaims dos Exemplos de Integração.
6. Verificado o access token, a aplicação cliente consegue, através do atributo sub, saber qual usuário confirmou sua identidade gov.br com sucesso e continuar o processo no sistema integrado.

   
   

7.  

• Acesso ao Serviço de Recuperação do Tipo de Certificado

1. Na requisição de autenticação, adicionar o escopo “govbr_recupera_certificadox509“, conforme exemplo:

Exemplo de requisição

https://sso.staging.acesso.gov.br/authorize?response_type=code&client_id=minha-aplicacao&scope=openid+email+phone+profile+govbr_recupera_certificadox509&redirect_uri=http%3A%2F%2Fappcliente.com.br%2Fphpcliente%2Floginecidadao.Php&nonce=3ed8657fd74c&state=358578ce6728b

2. Com o usuário autenticado, a aplicação deverá realizar uma requisição por meio do método GET a URL https://sso.staging.acesso.gov.br/api/x509/info enviando as seguintes informações:

Parâmetros para requisição GET https://sso.staging.acesso.gov.br/api/x509/info

3. O resultado em formato JSON é tipo de certificado da autenticação, conforme o exemplo abaixo:

Exemplo de requisição

[
        {
          "provider":"(Indicará qual o provedor disponibilizará o certificado. Aparecerá para certificado em nuvem)",
          "amr":["(Lista de forma de certificados autenticados. Padrão é x509)"],
          "certificate":"(Demonstra o nome do cerfificado da autenticação)",
          "type":"(Informa qual tipo de certificado utilizado para autenticação. O contéudo será <device> para certificados A1 e A3 e <cloud> para indicar certificado em núvem)"
        }
]

• Resultados Esperados ou Erros do Acesso ao Serviços do Login Único

Os acessos aos serviços do Login Único ocorrem por meio de chamadas de URLs e as respostas são códigos presentes conforme padrão do protocolo http por meio do retorno JSON, conforme exemplo:

{
      "error": "(Código HTTP do erro)",
      "erro_description": "(Descrição detalhada do erro ocorrido. )"
}

Cadastro Base do Cidadão (CBC - CPF) - APIs Governamentais

Ministério da Economia – Secretaria de Governo Digital (ME/SGD)

O Cadastro Base do Cidadão - CBC foi instituído pelo Decreto 10.046/2019 e é a base de referência de cadastros de pessoas físicas para todos os órgãos da Administração Direta, Autárquica e Fundacional. Em sua primeira versão, o CBC utiliza a base cadastral de pessoas físicas da Receita Federal - CPF.

Estão inscritos os brasileiros e aqueles estrangeiros que possuam alguma relação fiscal com a RFB, para fins de identificação dos contribuintes.  Essa base conta hoje com cerca de 250 milhões de registros (considerando brasileiros, estrangeiros e falecidos)

Conheça o impacto desta API

Estudo realizado pela SGD demonstra que a utilização desta API na oferta de serviços públicos digitais proporciona, em cada transação, uma economia de tempo de 3 minutos e 10 segundos para o cidadão e de 6 minutos e 29 segundos para o governo. Esta economia ocorre devido à eliminação das necessidades de preenchimento de formulários e apresentação de documentos pelo cidadão e de conferência e validação das informações pelo governo.  Em termos monetários, esta redução de tempo significa uma economia de R$ 8,00 por transação.

Como acessar a API

Gratuito para órgãos do Poder Executivo Federal que façam adesão ao contrato centralizado da Secretaria de Governo Digital - SGD/ME

A Secretaria de Governo Digital (SGD), enquanto Gestora a Plataforma de Interoperabilidade instituída pelo Decreto 10.046/2019, oferece gratuitamente o acesso à API do CBC para os órgãos e entidades integrantes do SISP (Administração Direta, Autárquica e Fundacional Federal).

Caso sua organização não pertença ao SISP, os dados cadastrais do CPF podem ser obtidos alternativamente pela solução Infoconv, também catalogada neste Portal. 

Os órgãos ou entidades do SISP que desejem utilizar a API por meio do contrato centralizado disponibilizado pela SGD, sem custo para o órgão ou entidade, devem: 

1. Solicitar autorização à RFB

• Verificar se o órgão ou entidade possui convênio vigente ou autorização de acesso a dados do CPF junto à Receita Federal do Brasil (RFB). 
• Caso não possua, solicitar à RFB autorização para acesso a dados do CPF e autorização para acesso por meio da tecnologia API CPF Light. Ambas autorizações podem ser solicitadas por meio de ofício único, que deve ser assinado pelo dirigente máximo do órgão ou entidade.
• Caso possua, só é necessário solicitar à RFB a autorização para acesso por meio da tecnologia API CPF Light, por meio de ofício assinado por ocupante de cargo DAS 5 ou equivalente.

2. Aderir ao contrato centralizado

• Solicitar a adesão ao contrato centralizado disponibilizado pela SGD, indicando o volume estimado de consultas e os serviços públicos/sistemas que irão utilizar a integração, dentre outras informações por meio do link abaixo:

https://www.gov.br/pt-br/servicos/solicitar-adesao-para-acesso-ao-cadastro-base-do-cidadao

• Anexar a autorização da RFB à solicitação de adesão.
• Assinar o Termo de Adesão gerado pela solicitação de adesão e encaminhar à SGD por meio do email  conecta@economia.gov.br ;
• Receber da SGD ofício de deferimento ao Termo de Adesão.

3. Integrar seus serviços públicos/sistemas à API CPF Light

• Indicar um integrante responsável pela chave de acesso à API CPF Light que será utilizada para a integração. O integrante em questão deve possuir certificado digital e deverá assinar Termo de Responsabilidade sobre o uso dos dados de CPF.
• Receber as orientações técnicas para acesso e geração da chave de acesso.
• Executar os passos para a geração da chave de acesso.
• Evoluir seus serviços públicos/sistemas, incluindo o desenvolvimento da integração com a API CPF Light.

4. Dar apoio ao processo de fiscalização contratual sob responsabilidade da SGD

• Conferir e confirmar declaração de prestação de serviço da API CPF Light mensalmente, auxiliando no ateste dos volumes consumidos e do cumprimento dos níveis de serviço.

Dados buscados dos Cidadãos

Serviço de Consultas On-line para obtenção dos dados cadastrais do cidadão.

Campos Retornados

OBS: Atualmente existem CPFs com nome, nome da mãe ou data de nascimento vazios. CPFs nessa situação constarão na situação cadastral como “3. Suspenso”.

Possíveis problemas

Diante da integração com o gov.br ser algo novo pelo time Vingadores, pode ser que durante o desenvolvimento da implementação venha aparecer possíveis problemas, os quais durante a realização desse SPIKE,  não foram identificados, fora isso, ate o momento, não a nem um possível problema.

Complexidade de cada funcionalidade

• As funcionalidades necessárias para atender à integração
  Solicitação e Alteração de Configuração - PO
  Administração das chaves PGP para credenciais do Login Único - 5 pontos
• Passo-a-Passo para Integrar
  • Realização da Autenticação - 21 pontos
    

    A utilização da autenticação do Login Único depende dos treze passos citados a cima

    E necessário remover o Sauron e ajustar as funcionalidades existente para o GOV.BR

• • Acesso ao serviço de Catálogo de Confiabilidades (Selos) - 5 pontos
  • Acesso ao Serviço de Log Out - 5 pontos
  • Acesso ao Serviço de Revalidação de Senha - 5 pontos
  • Acesso ao Serviço de Recuperação do Tipo de Certificado - 3 pontos

Total: 44 pontos

Valor agregado

Com a implementação da autenticação com o gov.br o Cidadão irar acessar o sistema de forma mais segura, em vista da existência do CBC - Cadastro Base do Cidadão, para que nem uma pessoa se passe por outra, levando em conta que essa base conta hoje tem cerca de 250 milhões de registros (considerando brasileiros, estrangeiros e falecidos), de modo que em sua primeira versão, o CBC utiliza a base cadastral de pessoas físicas da Receita Federal - CPF.

4. Conclusão

O presente estudo objetivou encontrar a melhor maneira de realizar a integração do portal do cidadão com a Plataforma de Autenticação Digital do Cidadão – Login Único, onde foi possível revisar sobre a arquitetura de serviço e alguns conceitos utilizados pela Plataforma, além de uma explicação sobre procedimentos administrativos essenciais para autorizar o acesso à Plataforma.

Diante disso, tornasse possível a implementação, em vista que no presente estudo contém as formas de chamadas a operações, parâmetros e métodos de integração, assim como os dados buscados do cidadão, e, por último, os procedimentos para permitir a conectividade entre os ambientes de implantação.

5. Referências

https://manual-roteiro-integracao-login-unico.servicos.gov.br/pt/stable/index.html

Plano de Integração. - https://manual-roteiro-integracao-login-unico.servicos.gov.br/pt/stable/arquivos/Modelo_PlanodeIntegracao_LOGINUNICO_Versao-4.doc

https://dsgov.estaleiro.serpro.gov.br/components/signin?tab=desenvolvedor

https://manual-roteiro-integracao-login-unico.servicos.gov.br/pt/stable/arquivos/ExemploIntegracaoGovBr.java

https://www.gov.br/conecta/catalogo/apis/cadastro-base-do-cidadao-cbc-cpf

https://www.gov.br/pt-br/servicos/solicitar-adesao-para-acesso-ao-cadastro-base-do-cidadao