Guides

Habilitar mTLS em produção

O mTLS cria uma camada adicional de segurança além das credenciais de API.

Atualmente, o mTLS só está disponível em produção. Por isto, você deve validar toda a integração em sandbox de forma normal. Para ir a produção será necessário apenas mudar o domínio e adicionar os certificados na chamada do seu client.

Os domínios mTLS são prefixados com .mtls, ficando assim:

  • api.mtls.transfeera.com
  • login-api.mtls.transfeera.com
  • contacerta-api.mtls.transfeera.com

Para começar, você precisa gerar um CSR (Certificate signing request) public.csr, junto será gerada uma chave privada (private.key). Esta nunca deve ser compartilhada, e deve ser armazenada de forma segura no seu ambiente. Ela será necessária para fazer as chamadas.

Usando o OpenSSL, gere o arquivo CSR desta forma:

openssl req -new -newkey rsa:2048 -nodes -keyout private.key -out public.csr

Preencha as seguintes informações corretamente, com os dados da sua empresa, para que possamos identificar corretamente do nosso lado.

Country Name (2 letter code) []: BR
State or Province Name (full name) []: Estado
Locality Name (eg, city) []: Cidade
Organization Name (eg, company) []: Minha empresa LTDA
Organizational Unit Name (eg, section) []: Minha empresa LTDA
Common Name (eg, fully qualified host name) []: Minha empresa LTDA
Email Address []: [email protected]

Após isso, entre em contato com o nosso Suporte solicitando a habilitação do mTLS para a sua conta e anexe o arquivo public.csr.

🚧

Por favor não compartilhe a sua chave privada.

Após as tratativas do nosso lado, você deve receber um link para baixar seu certificado (*.crt). Este certificado deve ser usado em conjunto com a chave privada gerada anteriormente private.key.

Para testar a chamada e garantir que está tudo certo, você deve conseguir realizar este curl com sucesso:

curl --cert certificate.crt --key private.key https://api.mtls.transfeera.com/status

Caso você tenha algum erro na sua integração, receberá este erro HTTP com o código: 403:

{
    "error": "Forbidden",
    "statusCode": 403,
    "message": "mTLS required"
}

Verifique que está enviando corretamente o certificado e a chave privada na sua requisição e usando os domínios mTLS. Em caso de dúvidas, contate o nosso suporte para auxiliá-lo.

Caso você já esteja integrado

Caso você já esteja integrado com a nossa API, sem fazer uso do mTLS, será necessário realizar a migração.

Nosso time está preparado para auxiliar na migração de forma que não aconteçam interrupções.

Funciona assim:

  1. Gere o arquivo CSR e envie para nós, conforme instruído acima.
🚧

Por favor não compartilhe a sua chave privada.

  1. Você receberá o Certificado para baixar.
  2. A sua integração continua funcionando aqui.
  3. Faça os ajustes na sua integração, que consistem em:
    1. Alterar os endpoints para prefixar .mtls conforme mencionado acima.
    2. Incluir o certificado e chave privada em todas as requisições no seu client.
  4. Assim que você confirmar que está tudo funcionando, notifique o time de Suporte que realizou a migração.
  5. Nosso time irá desabilitar o fluxo sem mTLS para a sua conta, e somente aqui deixará de funcionar os endpoints sem mTLS.

Qualquer dúvida conte com o nosso time de Suporte para lhe auxiliar. Lembrando que a migração é importante para a sua segurança, ao adicionar mais uma camada de proteção entre a comunicação do seu sistema com a Transfeera.