Ir para o conteúdo

Autenticação

A segurança do Porto Sem Papel é baseada em SSL/TLS, sendo obrigatória a utilização de certificados digitais. Desta forma, será necessário que o sistema externo que queira utilizar os Web services de cada um dos sistemas, realize a importação do certificado de chave pública da(s) máquina(s) que acessarão o Porto Sem Papel, a fim de possibilitar a realização da devida autenticação.

Observação:

1. Para os ambientes de homologação e treinamento o serviço suporta certificados dos tipos A1(e-CPF, e-CNPJ e e-EQUIPAMENTO/e-SERVIDOR) e A3(e-CPF e e-CNPJ), do padrão ICP-Brasil. Já no ambiente de produção somente é suportado o certificado do tipo A1(e-EQUIPAMENTO/e-SERVIDOR) também do padrão ICP-Brasil.

2. Pode ser importado mais de um certificado para a comunicação com o sistema.

Abaixo estão descritos todos os passos necessários para a realização da autenticação de um sistema externo com o Porto sem Papel.

1. Configurações para Autenticação

1.1 Extração da Chave Pública do Certificado

Inicialmente deve-se extrair o certificado de chave pública que se encontra no certificado digital que fará a comunicação com o sistema, nos formatos .crt ou .pem. Essa extração pode ser feita através do prompt de comando, utilizando a seguinte linha de comando da biblioteca openSSL:

openssl pkcs12 -in [nome_arquivo_certificado .p12 ou .pfx] -out [nome_novo_arquivo .pem ou .crt] -clcerts -nokeys

Alternativamente, caso não se tenha instalado a biblioteca openSSL, pode-se realizar a extração do certificado de chave pública através do navegador.

No Chrome o caminho para extrair o certificado é através do menu "Configurações", item de menu "Privacidade e Segurança", clicar em "Mais" e então acessar o menu "Gerenciar Certificados". Será exibida uma janela com os certificados, sendo que ao se optar por "visualizar" no certificado desejado será exibida a opção "Exportar". Na janela com o nome do arquivo ao qual o certificado será extraído, preencher o mesmo nas extensões .pem ou .crt.

Já no Firefox o caminho para extração do certificado é através do menu "Preferências", item de menu "Avançado", e então ir na aba "Certificados". Selecionar o certificado desejado e clicar no botão "Ver". Será então aberta uma janela, onde deverá ser acessada a aba "Detalhes" que exibirá a opção "Exportar". Na janela com o nome do arquivo ao qual o certificado será extraído, preencher o mesmo nas extensões .pem ou .crt.

Outra alternativa para exportação da chave pública no ambiente windows pode ser visualizada neste passo-a-passo.

Atenção:

1. Dependendo do navegador/sistema operacional a extração do certificado de chave pública só terá a opção de ser realizada na extensão .cer. Nesse caso realize a extração normalmente e depois ajuste a extensão do arquivo salvo para os formatos .pem ou .crt.

2.Após a extração do arquivo com o certificado de chave pública verificar se o arquivo salvo está realmente só com a extensão .pem ou .crt, pois em alguns casos, mesmo que se preencha no momento da extração o formato indicado, o sistema operacional salva com uma extensão .cer o arquivo. Nesse caso basta retirar essa extensão .cer e colocar o formato .pem ou .crt.

1.2 Download das Cadeias de Certificados do SERPRO

Para a realização da autenticação, também será necessário que os sistemas externos baixem as cadeias de certificados do SERPRO em suas máquinas que acessarão o sistema, para que possam reconhecer a autenticidade do Servidor do Porto Sem Papel. As cadeias de certificados necessárias para o ambiente de homologação podem ser baixadas aqui. Já as cadeias necessárias para o ambiente de produção podem ser baixadas aqui.

2. Processo de Autenticação

Ao acionar o serviço de autenticação, através da requisição ao endpoint indicado no item 3 desta página, será preciso realizar o processo de handshake SSL/TLS entre a aplicação cliente e o Porto Sem Papel, apresentando um certificado digital válido, cuja chave pública tenha sido previamente importada, conforme citado na sessão anterior. No momento da requisição de autenticação podem ocorrer alguns erros, conforme descrito no item 7 desta página.

Atenção:

1. No momento do handshake entre a aplicação cliente e o servidor, o certificado a ser utilizado pelo sistema externo deve ser o certificado completo, incluindo a sua chave privada, e não o arquivo somente com o certificado de chave pública importado na tela do sistema anteriormente. A chave privada é utilizada para comunicação com o servidor e estabelecimento do canal SSL/TLS e não é armazenada pelo Porto Sem Papel.

2. Caso se trate de um certificado do tipo e-EQUIPAMENTO/e-SERVIDOR, o sistema, no momento da autenticação, não valida o domínio (URL) informado no campo "Common Name(CN)" do certificado. Apenas é validado se aquele certificado pertence à cadeia de certificação da ICP-Brasil e se sua chave pública está cadastrada no Cadastro de Integração com Sistemas Externos. Desta forma, caso seja necessário, o mesmo arquivo de certificado pode ser utilizado em várias máquinas distintas na comunicação com o Porto Sem Papel.

2.1 Passo a Passo do Processo de Autenticação

As plataformas de desenvolvimento atuais já implementam o fluxo de Handshake SSL/TLS. Em geral, basta configurar algumas variáveis de ambiente e a API se encarrega de executar o protocolo. Em resumo, o processo acontece da seguinte forma:

  1. O cliente SSL ou TLS envia uma mensagem "client hello" que lista informações criptográficas, como a versão de SSL ou TLS e, na ordem de preferência do cliente, os CipherSuites(conjunto de algoritmos criptográficos) suportados pelo cliente. A mensagem também contém uma cadeia de bytes aleatória que é utilizada em cálculos subsequentes. O protocolo permite que o client hello inclua métodos de compactação de dados suportados pelo cliente;

  2. O servidor SSL ou TLS responde com uma mensagem server hello que contém o CipherSuite escolhido pelo servidor a partir da lista fornecida pelo cliente, o ID de sessão e outra sequência de bytes aleatória. O servidor também envia seu certificado digital. Se o servidor exigir um certificado digital para a autenticação do cliente, o servidor envia um "pedido de certificado de cliente" que inclui uma lista dos tipos de certificados suportados e os Nomes Distintos de Autoridades de Certificação (CAs) aceitáveis;

  3. O cliente SSL ou TLS valida a cadeia de certificados digitais do servidor;

  4. O cliente SSL ou TLS envia a sequência de bytes aleatória que permite ao cliente e ao servidor calcular a chave secreta a ser usada para a criptografia de dados de mensagens subsequentes. A própria cadeia de bytes aleatória é criptografada com a chave pública do servidor;

  5. Se o servidor SSL ou TLS enviou uma "solicitação de certificado de cliente", o cliente envia uma sequência de bytes aleatória criptografada com a chave privada do cliente, juntamente com o certificado digital do cliente ou um "nenhum alerta de certificado digital". Este alerta é apenas um aviso, mas com algumas implementações, o protocolo de reconhecimento falha em caso de obrigatoriedade da autenticação do cliente;

  6. O servidor SSL ou TLS valida o certificado do cliente;

  7. O cliente SSL ou TLS envia a um servidor uma mensagem de "concluído", que é criptografada com a chave secreta, indicando que a parte do handshake do cliente está concluída;

  8. O servidor SSL ou TLS envia ao cliente uma mensagem "concluído", que é criptografada com a chave secreta, indicando que a parte do handshake do servidor está concluída;

  9. O processo de handshake é finalizado e o cliente pode realizar requisições aos demais serviços;

2.2 Token de Segurança

Ao final do processo de autenticação, caso ele ocorra com sucesso, será devolvido no corpo da requisição da resposta ao serviço de autenticação um token JWT, conforme definido no item 4 desta página. Este token deverá ser encaminhado posteriormente no header de cada uma das requisições aos Web services do Porto Sem Papel, conforme definido no item 5 desta página, a fim de confirmar a autenticação/autorização do sistema externo que encaminha as requisições, bem como garantir que as mensagens trocadas não tenham sido adulteradas.

O token também possui um prazo de expiração de 30 minutos após sua geração, e, passado esse prazo, o sistema externo deverá realizar uma nova autenticação para poder acionar novamente os serviços.

Atenção:

Recomendamos que a autenticação seja realizada uma única vez e o token gerado utilizado em todas as requisições de serviços pelo período máximo de expiração. Evite utilizar o serviço de autenticação antes de cada requisição aos serviços pois isto impacta no desempenho do sistema.

3. EndPoint para Autenticação

GET url_base/psp-autenticacao-rest-integracao/api/autenticacao

4. Atributo do Retorno da Requisição de Autenticação

  • O seguinte atributo será retornado no body da resposta da requisição de autenticação caso ela ocorra com sucesso:
Nome Descrição Tipo Local
pspJwt JSON Web Token (JWT) contendo as informações do usuário. Conforme o padrão JWT, esse token poderá ser decodificado (Base64) a fim de se extrair as informações do usuário para que as mesmas sejam utilizadas na aplicação cliente. O token é assinado digitalmente pelo servidor e verificado a cada requisição, garantindo a sua inviolabilidade. String body

5. Atributo obrigatório em todas as requisições web service após a autenticação

  • O seguinte atributo deverá ser encaminhado no header de cada requisição após a autenticação:
Nome Descrição Tipo Local
Authorization inicio com "Bearer " seguido do JSON Web Token (JWT) contendo as informações do usuário. Este token é recuperado no parâmetro pspJwt no response da autenticação. ex: Authorization: Bearer ey... String header

ou (forma legada)

Nome Descrição Tipo Local
psp-jwt JSON Web Token (JWT) contendo as informações do usuário. Este token é recuperado no parâmetro pspJwt no response da autenticação String header

6. Erros na Importação do Certificado via Tela

Mensagem Observação
Certificado Inválido O certificado importado não segue o formato padrão de certificados X509
Certificado não é do tipo ICP-Brasil O certificado importado não foi emitido por uma entidade participante da ICP-Brasil
Certificado deve ser do tipo e-Equipamento O certificado importado não é um certificado de máquina(e-Equipamento ou e-Servidor)

Validação existente somente no ambiente de produção

7. Erros na Requisição de Autenticação

Código de Erro Mensagem Observação
AUT001 Nenhum certificado X509 encontrado no request.
AUT002 Não autorizado A chave pública do certificado não foi cadastrada anteriormente no "Cadastro de Integração com Sistemas Externos" ou existe divergência entre a chave cadastrada e a chave apresentada no momento da autenticação.

8. Erros gerais na requisição aos serviços web relacionados a autenticação

  • As seguintes mensagens de erro serão exibidas no momento da requisição aos serviços web do Porto Sem Papel quando ocorre alguma divergência em relação a autenticação:
Código de Erro Mensagem Observação
WS001 Token expirado. O token expira dentro de 30 minutos após sua geração, passado esse prazo o sistema deve refazer sua autenticação.
WS002 Sem permissão para a funcionalidade. Apesar do sistema externo estar autenticado se ele encaminhar uma requisição a um serviço web que ele não tenha acesso receberá essa mensagem no retorno. Todos os serviços web indicam na sessão "Atores que podem utilizar o Serviço" a informação de quais atores tem permissão de acesso aquele serviço.
WS003 Token não encontrado no header.
WS004 Token inválido.