Autenticação com mTLS

O que é mTLS?

O Mutual Transport Layer Security (mTLS) é uma extensão do protocolo TLS (Transport Layer Security) que permite autenticação mútua entre cliente e servidor ao estabelecer uma conexão segura.

O TLS, protocolo base do mTLS, utiliza a técnica chamada criptografia de chave pública ou criptografia assimétrica para criptografar a comunicação entre cliente e servidor que é composto de chave pública e chave privada. A chave pública é usada para criptografar e a chave privada para descriptografar.

Desse modo, o mTLS assegura que ambas as partes são confiáveis, pois tanto cliente quanto servidor devem se identificar com seus certificados e chaves.

Benefícios do mTLS

1. Autenticação Mútua: Tanto o cliente quanto o servidor têm suas identidades verificadas antes de estabelecer uma conexão. Garantindo que a comunicação ocorra entre clientes e serviços desejados e evita o uso indevido das APIs.
2. Confidencialidade e integridade dos dados: Os dados transmitidos entre o cliente e o servidor são criptografados e protegidos de qualquer alteração durante a transmissão.
3. Proteção contra os ataques Man-in-the-middle: Dificulta ataques man-in-the-middle. O atacante não consegue autenticar nem o cliente nem o servidor, pois não tem acesso aos certificados e chaves válidos, impedindo a descriptografia dos dados e a simulação de uma das partes envolvidas.

Fluxo de autenticação com mTLS

Para realizar a autenticação com mTLS é necessário possuir a chave privada e o certificado assinado por nós. É necessário enviar a chave privada e o certificado em todas as chamadas da nossa API.

Como obter o certificado e a chave privada

Caso você ainda não possua o certificado e a chave privada, entre em contato com nosso time de Suporte através do e-mail meajuda@4all.com.

OS CERTIFICADOS SÃO GERADOS COM VALIDADE DE 5 ANOS.

MANTENHA A CHAVE PRIVADA ARMAZENADA DE FORMA SEGURA

Antes de fazer qualquer operação com as APIs da 4all, você primeiro deverá obter um token de acesso para autenticar suas solicitações. Esse token é obtido através de uma requisição para o endpoint de geração de tokens (POST /v2/token), por meio de um usuário e senha.

Para poder se autenticar, será necessário informar seu username e password para dar inicio ao fluxo de autenticação. Além do seu certificado e da sua chave privada.

Essas informações devem ser enviadas por meio do fluxo de autenticação básico. A autenticação básica é um esquema de autenticação simples integrado ao protocolo HTTP. Para usá-lo, envie sua requisição com um header chamado Authorization, contendo a palavra Basic seguida por um espaço e uma string codificada em base64 no seguinte formato: username:password

Exemplo: Authorization: Basic bWV1X3VzdWFyaW86bWluaGFfc2VuaGE=

Exemplo cURL:

curl --location --request POST 'https://api.4all.com/v2/token' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--header 'Authorization: Basic bWV1X3VzdWFyaW86bWluaGFfc2VuaGE=' \
--data-urlencode 'grant_type=client_credentials' \
--cert ./CERTIFICADO.crt \
--key ./CHAVE_PRIVADA.key

Exemplo de como fazer o envio com Node.js (axios):

const axios = require('axios');
const fs = require('fs');
const https = require('https');
const querystring = require('querystring');

// Configurações do cliente HTTPS com certificados
const httpsAgent = new https.Agent({
    cert: fs.readFileSync('./CERTIFICADO.crt'), // Certificado do cliente
    key: fs.readFileSync('./CHAVE_PRIVADA.key'), // Chave privada do cliente
    rejectUnauthorized: true // Rejeitar conexões não autorizadas
});

// Dados da requisição
const data = querystring.stringify({ 'grant_type': 'client_credentials' });

const config = {
    method: 'post',
    url: 'https://api.4all.com/v2/token',
    headers: {
        'Content-Type': 'application/x-www-form-urlencoded',
        'Authorization': 'Basic bWV1X3VzdWFyaW86bWluaGFfc2VuaGE=',
    },
    data,
    httpsAgent,
};

axios(config)
    .then((response) => {
        console.log(response.data);
    })
    .catch((error) => {
        console.error(error);
    });

Exemplo de como fazer o envio com Python (requests):

import requests

response = requests.post(
    url='https://api.4all.com/v2/token',
    data={"grant_type": "client_credentials", },
    headers={
        'Content-Type': "application/x-www-form-urlencoded",
        'Authorization': "Basic bWV1X3VzdWFyaW86bWluaGFfc2VuaGE="
    },
    cert=(
        "./CERTIFICADO.crt",
        "CHAVE_PRIVADA.key"
    )
)

if response.status_code != 200:
    raise SyntaxError(response.json())

response_content = response.json()
print('response-content', response_content)

Exemplo utilizando o POSTMAN:

As orientações para usar o Postman com certificado podem ser acessadas na seguinte documentação: https://learning.postman.com/docs/sending-requests/authorization/certificates/#adding-client-certificates

Deve-se preencher os campos com as seguintes informações:

• Host: api.4all.com;
• CRT file: selecione o CERTIFICADO.crt;
• KEY file: selecione o CHAVE_PRIVADA.key

Access Token

Quando a autenticação for efetuada com sucesso, um objeto será retornado contendo diversos atributos, dentre eles, o access_token. O access_token é um token JWT, que deverá ser usado em todas as outras requisições feitas para nossas APIs, garantindo assim que quem está utilizando nossas APIs foi devidamente autorizado.

Tokens JWT são uma forma simples e poderosa de garantir segurança ao transmitir informações em objetos JSON, pois podem ser testados e validados para garantir sua confiabilidade. Você pode saber mais sobre este assunto consultando o site oficial.

Os dados completos da requisição estão descritos aqui.

Como posso obter os dados de acesso

Caso você ainda não possua um usuário e senha, entre em contato com nosso time de Suporte, através do e-mail meajuda@4all.com.

Referência