Ir para o conteúdo principal

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

Realizar um estudo de caso de como integrar com o gov.br

 

OBJETIVO

Ter informações mais claras de como integrar Portal do Cidadão com gov.br, 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 79 do time Vingadores.

 

JUSTIFICATIVA

Para que possamos planejar como será realizada a implementação dessa necessidade

Todo usuário do sistema precisa de um Login e Senha que venha ser acessado de forma segura, onde só possa existir um cidadão, com seu devido CPF, onde seu cadastro seja validado, para que nem uma pessoa se passe 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.

 

RESULTADOS ESPERADOS

Integração da autenticação e dados do cidadão.
Contato da equipe técnica do gov.br enviado pelo whats.
Saber se é possível buscarmos os dados do cidadão, e se buscar, quais são os dados.

 

RESULTADOS DA PESQUISA

Introdução

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.

 

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

Client_id

Identificação do Client_id que deseja alterar

URL de Retorno

URL Retorno deseja adicionar

URL Lançador de Serviços

URL Lançador de Serviços deseja alterar

URL de Logout

URL de Logout deseja adicionar

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. Realize download do aplicativo Gpg4win ;
    2. Siga os passos até finalizar instalação;
    3. Execute o programa Kleopatra.
    1. Selecione item do Menu Arquivo / Novo Par de chaves;
    1. Selecione opção Criar um par de chaves OpenPGP pessoal;
    1. 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
    1. Concluída a criação clique no botão Terminar;
    1. Selecione a chave criada, clique item do Menu Arquivo / Exportar para salvar chave pública;
    1. 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.
    1. Selecione item do Menu Arquivo / Descriptografar/Verificar;
    1. Selecione o arquivo com a credencial criptografada, digite a senha da geração do par de chaves, clique no botão OK;
    1. 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:

    1. A chamada para autenticação deverá ocorrer pelo botão com o conteúdo Entrar com GOV.BR. Para o formato do botão, seguir as orientações do Design System do Governo Federal site externo.
    2. Ao requisitar autenticação via Provedor, o mesmo verifica se o usuário está logado. Caso o usuário não esteja logado o provedor redireciona para a página de login.
    3. A requisição é feita através de um GET para o endereço https://sso.staging.acesso.gov.br/authorize passando as seguintes informações:
    VariavélDescrição
    response_typeEspecifica para o provedor o tipo de autorização. Neste caso será code
    client_idChave de acesso, que identifica o serviço consumidor fornecido pelo Login Único para a aplicação cadastrada
    scopeEspecifica os recursos que o serviço consumidor quer obter. Um ou mais escopos inseridos para a aplicação cadastrada. Informação a ser preenchida por padrão: openid+email+phone+profile+govbr_confiabilidades.
    redirect_uriURI de retorno cadastrada para a aplicação cliente no formato URL Encode. Este parâmetro não pode conter caracteres especiais conforme consta na especificação auth 2.0 Redirection Endpoint
    nonceSequência de caracteres usado para associar uma sessão do serviço consumidor a um Token de ID e para atenuar os ataques de repetição. Pode ser um valor aleatório, mas que não seja de fácil dedução. Item obrigatório.
    stateValor usado para manter o estado entre a solicitação e o retorno de chamada. Item obrigatório.
    Exemplo de requisição:
    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
    1. 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:
    VariavélDescrição
    codeCódigo de autenticação gerado pelo provedor. Será utilizado para obtenção do Token de Resposta. Possui tempo de expiração e só pode ser utilizado uma única vez.
    stateState passado anteriormente do https://sso.staging.acesso.gov.br/authorize que pode ser utilizado para controle da aplicação cliente. Pode correlacionar com o code gerado. O cliente consegue saber se o CODE veio de um state gerado por ele.
    1. 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 ;
    2. 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élDescrição
    Content-TypeTipo do conteúdo da requisição que está sendo enviada. Nesse caso estamos enviando como um formulário
    AuthorizationInformação codificada em Base64, no seguinte formato: CLIENT_ID:CLIENT_SECRET (senha de acesso do serviço consumidor)(utilizar codificador para Base64 site externo 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

    VariavélDescrição
    grant_typeEspecifica para o provedor o tipo de autorização. Neste caso será authorization_code
    codeCódigo retornado pela requisição anterior (exemplo: Z85qv1)
    redirect_uriURI de retorno cadastrada para a aplicação cliente no formato URL Encode. Este parâmetro não pode conter caracteres especiais conforme consta na especificação auth 2.0 Redirection Endpoint

    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.)"
}
    1. 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.
    2. 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.
    3. 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.
    1. 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:
    VariavélDescrição
    Authorizationpalavra Bearer e o ACCESS_TOKEN da requisição POST do https://sso.staging.acesso.gov.br/token

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

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

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

     

     

     

     

     

     

    Complexidade de cada funcionalidade

     

    Possíveis problemas.

    Valor agregado

    e conclusão do estudo

    ENVOLVIDOS:

    Gustavo Felix Gomes (DEV Team)

    Rafael Passos dos Santos (DEV Team)

    Emanuel Rufino Alcantara de Lima (Dev Team)

    Lucas de Souza e Sousa (Estagiário Dev Team)

    Lucas Tavares Viana de Souza (Estagiário Scrum Master)

    Gerente de Desenvolvimento:

    Janderson de Castro Thomaz

    Product Owner:

    Euriane Nogueira Frota (Product Owner)

    Scrum Master:

    Moisés Santos Rodrigues (Scrum Master)

    GLOSSÁRIO:

    CONCLUSÃO


    O presente estudo objetivou encontrar a melhor maneira de realizar a publicação de aplicações PWAs em AspNetCore para iPhone na App Store, que é a loja que se tem mais critérios específicos para se publicar aplicativos e se o App for uma PWA vale ressaltar que o IOS está começando a ter compatibilidade com a tecnologia agora.

    e a Apple está focando nas APIs que são relevantes para a plataforma IOS, com isso seu suporte para a tecnologia PWAs é parcial, sendo uma das ultimas empresas entre Google, mozilla, Microsoft na adoção da tecnologia, sendo assim a partir da versão 11.3 ela introduziu suporte parcial a PWA, E na 12.2 ela realizou mais updates.

     

    		 
      

    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

     

     

     

     

    Voltar ao topo