# mTLS Mutual TLS (mTLS), também chamado de autenticação mútua, adiciona uma verificação do cliente ao handshake TLS: o cliente também apresenta um certificado, e o servidor o valida. Em um [workload](/pt-br/documentacao/plataforma/workloads/), a Azion valida o certificado de cliente em relação a um certificado de CA confiável, um dos tipos listados em [Certificados](/pt-br/documentacao/plataforma/workloads/certificate-manager/certificados/). O mTLS é opcional em um workload, e o modelo Open Banking o exige, por isso workloads que atendem serviços financeiros e pagamentos costumam precisar dele. Para a linha `mtls` entre todos os outros campos de um workload, consulte [Configurações de workload](/pt-br/documentacao/plataforma/workloads/configuracoes/#mtls). --- ## Campos O objeto `mtls` de um workload ativa a verificação do certificado de cliente e indica em relação a que o workload verifica. Defina-o com `PATCH /v4/workspace/workloads/{workload_id}`, ou no arquivo JSON de `azion update workload --file`, que lê o ID do workload de uma chave `"id"` no arquivo. | Campo da API | Tipo | Valores | Padrão | Flag da CLI | | -------------------------- | ------------------------------------------------ | ------------------------------------------------------- | ------- | ---------------- | | `mtls.enabled` | boolean | `true` ativa a verificação, `false` a desativa | `false` | somente `--file` | | `mtls.config.certificate` | integer, ou `null` | o ID de um certificado do tipo `trusted_ca_certificate` | `null` | somente `--file` | | `mtls.config.crl` | array de integer, no máximo 100 itens, ou `null` | os IDs de listas de revogação de certificados (CRLs) | `null` | somente `--file` | | `mtls.config.verification` | enum, ou `null` | `enforce`, `permissive` | `null` | somente `--file` | O certificado de CA confiável é o certificado da autoridade que assina os certificados dos seus clientes. Você o envia sem chave privada, e a API recusa o ID de um certificado de servidor em `mtls.config.certificate`. Um certificado de CA confiável aparece como `inactive` no Certificate Manager até que um workload o indique, e como `active` a partir de então. Uma CRL lista certificados que o emissor revogou antes de expirarem. Uma CRL é anexada a um workload somente por meio de `mtls.config.crl`, em um workload com `mtls.enabled` definido como `true`, e um workload pode indicar várias CRLs no mesmo array. Por exemplo, um workload que admite somente clientes que a sua autoridade de certificação assinou, e que anexa uma CRL, envia este arquivo, salvo como `mtls.json`: ```json { "id": , "mtls": { "enabled": true, "config": { "certificate": , "crl": [], "verification": "enforce" } } } ``` Aplique-o com a CLI: ```bash azion update workload --file mtls.json ``` O comando imprime o ID do workload que alterou: ```text Updated Workload with ID ``` Em seguida, o workload é lido de volta com este objeto `mtls`: ```json { "mtls": { "config": { "certificate": , "crl": [], "verification": "enforce" }, "enabled": true } } ``` Na API v3, o mTLS pertencia ao objeto de domínio, em `is_mtls_enabled`, `mtls_verification` e `mtls_trusted_ca_certificate_id`. Na API v4, as mesmas configurações são `mtls.enabled`, `mtls.config.verification` e `mtls.config.certificate` no workload. Para o mapeamento completo entre os dois modelos, consulte [API v4 Migration](/pt-br/documentacao/fundamentos/api-v4-migration/). --- ## Modos de verificação O campo `mtls.config.verification` decide o que um workload faz com um cliente que não apresenta certificado, ou que apresenta um certificado que a CA confiável não assinou. No modo `enforce`, o workload solicita o certificado de cliente durante o handshake TLS e encerra o handshake quando a verificação falha. A tabela mostra o que cada cliente recebe de um workload em cada modo: | O cliente apresenta | `enforce` | `permissive` | | ------------------------------------------- | ---------------------------------------------------------- | ---------------------------------------------------------- | | Nenhum certificado | O handshake falha, e a requisição nunca chega à aplicação. | O handshake é concluído, e a requisição chega à aplicação. | | Um certificado que a CA confiável assinou | O handshake é concluído, e a requisição chega à aplicação. | O handshake é concluído, e a requisição chega à aplicação. | | Um certificado que outra autoridade assinou | O handshake falha, e a requisição nunca chega à aplicação. | O handshake é concluído, e a requisição chega à aplicação. | `enforce` bloqueia todo cliente cuja identidade o workload não consegue verificar, tanto nos seus próprios domínios quanto no workload domain. Use-o quando todo cliente legítimo tiver um certificado que a sua autoridade de certificação assinou. `permissive` permite que todo cliente conclua o handshake e deixa a decisão para as suas regras. Use-o para testar o mTLS, ou para admitir clientes sob condições específicas. Para recusar os demais, adicione uma regra de firewall sobre a variável Client Certificate Validation, como descreve a seção Dados do certificado de cliente em regras. Uma alteração em `mtls` leva vários minutos para chegar a toda a infraestrutura distribuída da Azion, e a propagação é feita com o melhor esforço. Até que ela termine, algumas requisições encontram o modo antigo e outras o novo. Antes de depender de uma alteração, envie uma requisição sem certificado de cliente e confirme que o resultado corresponde ao novo modo. --- ## Dados do certificado de cliente em regras Rules Engine lê detalhes do certificado de cliente, para que uma regra possa agir conforme a identidade do cliente. No Rules Engine for Firewall, a variável Client Certificate Validation avalia se o certificado da requisição é válido em relação à CA confiável do workload. Em um workload no modo `permissive`, uma regra que nega requisições em que Client Certificate Validation não é igual a `true` retorna `403 Forbidden` a todo cliente sem um certificado válido. O critério Client Certificate Validation aparece somente em uma conta em que o mTLS está ativado. Uma regra de firewall também pode corresponder a atributos do certificado de cliente, como o Common Name (CN), o emissor ou a impressão digital (fingerprint), que as variáveis de header de mTLS carregam. Essas variáveis devem ser definidas na sua aplicação antes que uma regra de firewall possa usá-las como critérios. Uma aplicação define as variáveis de header de mTLS como headers de requisição, por exemplo para atender aos requisitos do Open Banking. A lista de variáveis que Rules Engine aceita está em [Rules Engine para Applications](/pt-br/documentacao/plataforma/applications/rules-engine/). Para a configuração da regra passo a passo, consulte [Configure mTLS em um workload](/pt-br/documentacao/guias/seguranca-de-aplicacoes/tls-e-certificados/associar-um-certificado-mtls/). --- ## Requisitos Um workload verifica certificados de cliente somente quando estas condições são atendidas: - **O mTLS está ativado na sua conta.** A Azion ativa o mTLS por conta. Para ativá-lo, entre em contato com a equipe de Vendas. - **O workload atende HTTPS.** O certificado de cliente trafega no handshake TLS, por isso o mTLS funciona somente em conexões HTTPS. As configurações de mTLS em um workload que atende somente HTTP não verificam nada. - **Existe um certificado de CA confiável no Certificate Manager.** Uma autoridade de certificação de terceiros o emite, e você o envia antes de definir `mtls.config.certificate`. Um certificado que a Azion gera, como o certificado Azion SAN, não pode servir como CA confiável. - **Os clientes enviam SNI no modo `enforce`.** Server Name Indication (SNI) é a extensão TLS que indica o host no handshake. Uma conexão sem SNI chega à configuração padrão, que apresenta o certificado Azion SAN. Em um workload no modo `enforce`, a Azion fecha essa conexão antes de resolver uma rota da sua aplicação. Para o número de certificados que uma conta pode ter e o tamanho máximo de um certificado de CA confiável, consulte [Limites de Workloads](/pt-br/documentacao/plataforma/workloads/limites/). --- ## Erros A API recusa as duas primeiras requisições abaixo com a mensagem da primeira coluna. A CLI imprime a mensagem dentro de `Error: Failed to update the Workload: [...]`, seguida de `Check your settings and try again. If the error persists, contact Azion support.` A última linha é o que um cliente vê, não uma mensagem da API. | Mensagem | Causa | O que fazer | | ------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `Invalid certificate type, MUST be a Trusted CA.` | `mtls.config.certificate` contém o ID de um certificado de servidor, do tipo `edge_certificate`. | Envie o ID de um certificado do tipo `trusted_ca_certificate`. | | `Invalid certificate type, MUST be an Edge Certificate.` | `tls.certificate` contém o ID de um certificado de CA confiável, que pertence a `mtls.config.certificate`. | Mova o ID para `mtls.config.certificate` e envie o ID de um `edge_certificate`, ou `null`, em `tls.certificate`. | | O curl termina com o código `56` após a solicitação de certificado do servidor; LibreSSL informa `reason(1116)`, certificado exigido | O workload está no modo `enforce`, e o cliente não apresentou certificado ou apresentou um certificado que a CA confiável não assinou. | Apresente um certificado de cliente que a CA confiável assinou, com as opções `--cert` e `--key` do curl, ou defina `mtls.config.verification` como `permissive` e decida em uma regra de firewall. | A falha do handshake aparece na saída detalhada do curl. Envie uma requisição sem certificado de cliente a um workload no modo `enforce`: ```bash curl -skv https:/// -o /dev/null ``` O workload solicita um certificado, o cliente não envia nenhum e a conexão termina: ```text * (304) (IN), TLS handshake, Request CERT (13): * (304) (IN), TLS handshake, Certificate (11): * (304) (IN), TLS handshake, CERT verify (15): * (304) (IN), TLS handshake, Finished (20): * (304) (OUT), TLS handshake, Certificate (11): * (304) (OUT), TLS handshake, Finished (20): * SSL connection using TLSv1.3 / AEAD-AES256-GCM-SHA384 / [blank] / UNDEF * LibreSSL SSL_read: LibreSSL/3.3.6: error:1404C45C:SSL routines:ST_OK:reason(1116), errno 0 ``` --- ## Recursos relacionados - [Certificados](/pt-br/documentacao/plataforma/workloads/certificate-manager/certificados.md): Os certificados de CA confiável e as CRLs que um workload indica no mTLS, e como enviar cada um. - [Configure mTLS em um workload](/pt-br/documentacao/guias/seguranca-de-aplicacoes/tls-e-certificados/associar-um-certificado-mtls.md): Os passos que enviam uma CA confiável, ativam o mTLS em um workload e adicionam uma regra permissive. - [Configurações de workload](/pt-br/documentacao/plataforma/workloads/configuracoes.md): Todos os outros campos de um workload, de domínios e portas ao certificado de servidor em TLS. - [Limites de Workloads](/pt-br/documentacao/plataforma/workloads/limites.md): Os limites de certificados por conta e do tamanho de um certificado de CA confiável.