--- name: azion-configure-mtls-em-um-workload description: >- Envie um certificado de CA confiável e uma CRL, ative o mTLS em um workload e teste o handshake, pela Azion CLI ou pela API. --- # Configure mTLS em um workload Você pode ativar o mutual TLS ([mTLS](/pt-br/documentacao/plataforma/workloads/mtls/)) em um [workload](/pt-br/documentacao/plataforma/workloads/) pela [Azion CLI](/pt-br/documentacao/devtools/cli/) ou pela API. Para servir HTTPS no seu domínio com um certificado de servidor próprio, consulte [Envie um certificado digital](/pt-br/documentacao/guias/seguranca-de-aplicacoes/tls-e-certificados/certificado-digital/). Com o mTLS ativado, o workload solicita um certificado a cada cliente durante o handshake TLS. Ele verifica esse certificado em relação a um certificado de CA confiável: o certificado da autoridade de certificação (CA) que assina os certificados dos seus clientes. A configuração usa três objetos: o certificado de CA confiável, uma lista de revogação de certificados (CRL) opcional da mesma CA e o objeto `mtls` do workload. Uma conta que opera na API v3 com Domains define o mTLS em cada domínio, em vez disso. Para mais informações, consulte [Domains](/pt-br/documentacao/plataforma/workloads/domains/). --- Selecione uma interface. Os pré-requisitos e os passos de cada tarefa seguem a sua escolha. ## Pré-requisitos - mTLS ativado na sua conta. A Azion ativa o mTLS por conta, então entre em contato com a equipe de vendas da Azion para ativá-lo. - Um workload cujo deployment indica uma aplicação, servido por HTTPS. O certificado de cliente trafega no handshake TLS, então o mTLS verifica somente conexões HTTPS. Para criar um workload, consulte [Primeiros passos com Workloads](/pt-br/documentacao/plataforma/workloads/primeiros-passos/). - O certificado da sua CA, em formato PEM. Uma CA de terceiros o emite. Um certificado que a Azion gera não pode servir como CA confiável. - (Opcional) Uma CRL em formato PEM, assinada pela mesma CA. - Um certificado de cliente que essa CA assinou, com a chave privada dele, para testar o workload. **CLI** - [Azion CLI](/pt-br/documentacao/devtools/cli/), autorizada com a sua conta. Esta página corresponde à Azion CLI 4.23.0. - O ID do workload. `azion create workload` o imprime como `Created Workload with ID `. **API** - Um token pessoal para o header `Authorization`, no formato `Token [TOKEN VALUE]`. Para criar um token, consulte [Tokens pessoais](/pt-br/documentacao/fundamentos/personal-tokens/). - `curl` ou outro cliente HTTP. - O ID do workload. `azion create workload` o imprime como `Created Workload with ID `. --- ## Envie o certificado de CA confiável [Certificate Manager](/pt-br/documentacao/plataforma/workloads/#certificate-manager) armazena o certificado de CA confiável com o tipo `trusted_ca_certificate` e sem chave privada. O arquivo deve estar em formato PEM, com as linhas `-----BEGIN CERTIFICATE-----` e `-----END CERTIFICATE-----`, e Certificate Manager recusa qualquer outro formato. Quando a sua cadeia tiver certificados intermediários, inclua-os no mesmo arquivo. **CLI** Para enviar o certificado pela Azion CLI, passe o arquivo PEM da sua CA, aqui `ca.pem`: ```bash azion create digital-certificate --name my-trusted-ca --certificate ca.pem --certificate-type trusted_ca_certificate ``` O comando imprime o ID do novo certificado. A atualização do workload em Ative o mTLS no workload precisa dele: ```text Created Digital Certificate with ID ``` **API** Para enviar o certificado pela API, envie uma requisição `POST` ao endpoint de certificados. Escreva o certificado como uma única string, com cada quebra de linha como `\n`: ```bash curl --request POST \ --url https://api.azion.com/v4/workspace/tls/certificates \ --header 'Accept: application/json' \ --header 'Authorization: Token [TOKEN VALUE]' \ --header 'Content-Type: application/json' \ --data '{ "name": "my-trusted-ca", "type": "trusted_ca_certificate", "certificate": "-----BEGIN CERTIFICATE-----\n\n-----END CERTIFICATE-----\n" }' ``` A API responde `201` com o novo certificado. Guarde o `id` dele para a atualização do workload. O certificado de CA confiável aparece como `inactive` no Certificate Manager até que um workload o indique no objeto `mtls`. --- ## Envie uma lista de revogação de certificados Uma CRL lista os certificados que uma CA revogou antes da data de expiração deles, e a CA a assina. Um workload com mTLS ativado indica até 100 CRLs em `mtls.config.crl`. Esta tarefa é opcional: pule-a quando a sua CA não publicar CRL. **CLI** Para enviar a CRL pela Azion CLI, passe o arquivo PEM dela, aqui `ca.crl`, e o nome da CA que a emitiu: ```bash azion create crl --name my-crl --issuer "My CA" --crl ca.crl ``` O comando imprime o ID da nova CRL: ```text Created Certificate Revocation List with ID ``` **API** Para enviar a CRL pela API, envie uma requisição `POST` ao endpoint de CRLs. Escreva a CRL como uma única string, com cada quebra de linha como `\n`: ```bash curl --request POST \ --url https://api.azion.com/v4/workspace/tls/crls \ --header 'Accept: application/json' \ --header 'Authorization: Token [TOKEN VALUE]' \ --header 'Content-Type: application/json' \ --data '{ "name": "my-crl", "issuer": "My CA", "crl": "-----BEGIN X509 CRL-----\n\n-----END X509 CRL-----\n" }' ``` A API responde `201` com a nova CRL. Guarde o `id` dela para a atualização do workload. Certificate Manager armazena a CRL e lê as datas `last_update` e `next_update` da própria CRL. --- ## Ative o mTLS no workload O objeto `mtls` do workload ativa a verificação e indica o certificado de CA confiável, as CRLs e o modo de verificação. Escolha o modo em `verification`: - `enforce`: o workload encerra o handshake quando um cliente não apresenta certificado, ou apresenta um certificado que a CA confiável não assinou. - `permissive`: todo cliente conclui o handshake, e uma regra de firewall decide quais requisições recusar. Para o que cada modo faz com cada tipo de cliente, consulte [Modos de verificação](/pt-br/documentacao/plataforma/workloads/mtls/#modos-de-verificacao). **CLI** Para ativar o mTLS pela Azion CLI, salve um arquivo JSON com o ID do workload e o objeto `mtls`, aqui como `mtls.json`. Envie `null` em `crl` quando o workload não indicar nenhuma CRL: ```json { "id": , "mtls": { "enabled": true, "config": { "certificate": , "crl": [], "verification": "enforce" } } } ``` Atualize o workload com o arquivo: ```bash azion update workload --file mtls.json ``` O comando imprime o ID do workload que atualizou: ```text Updated Workload with ID ``` Para confirmar a alteração, descreva o workload: ```bash azion describe workload --workload-id --format json ``` Este trecho da saída mostra o objeto `mtls` como o workload o armazena: ```json { "mtls": { "config": { "certificate": , "crl": [], "verification": "enforce" }, "enabled": true } } ``` **API** Para ativar o mTLS pela API, envie uma requisição `PATCH` ao workload com o objeto `mtls`. Envie `null` em `crl` quando o workload não indicar nenhuma CRL: ```bash curl --request PATCH \ --url https://api.azion.com/v4/workspace/workloads/ \ --header 'Accept: application/json' \ --header 'Authorization: Token [TOKEN VALUE]' \ --header 'Content-Type: application/json' \ --data '{ "mtls": { "enabled": true, "config": { "certificate": , "crl": [], "verification": "enforce" } } }' ``` A API aceita a atualização. O certificado de CA confiável agora aparece como `active` no Certificate Manager. O novo modo leva vários minutos para chegar a toda a infraestrutura distribuída da Azion. Até lá, algumas requisições ainda encontram a configuração anterior, então repita um teste antes de confiar no resultado dele. A atualização falha quando um ID de certificado está no campo errado. Um certificado de servidor em `mtls.config.certificate` é recusado com `Invalid certificate type, MUST be a Trusted CA.` Um certificado de CA confiável em `tls.certificate` é recusado com `Invalid certificate type, MUST be an Edge Certificate.` A CLI imprime a mensagem dentro de `Error: Failed to update the Workload: [...]`. Para as duas correções, consulte [Erros de mTLS](/pt-br/documentacao/plataforma/workloads/mtls/#erros). --- ## Teste o handshake Duas requisições a um domínio do workload mostram se ele verifica os clientes: uma sem certificado de cliente e uma com um certificado que a CA confiável assinou. Envie-as depois que a alteração do mTLS se propagar. Para enviar uma requisição sem certificado de cliente, execute `curl` no modo verbose: ```bash curl -skv https:/// -o /dev/null ``` No modo `enforce`, o workload solicita um certificado, o cliente não envia nenhum, e o handshake falha. `curl` termina com o código `56`. Com `curl` compilado com LibreSSL, a saída verbose termina assim: ```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 ``` Para enviar uma requisição com o certificado de cliente, passe o certificado e a chave privada dele, aqui `client.pem` e `client.key`: ```bash curl -sk --cert client.pem --key client.key https:/// -o /dev/null -w '%{http_code}\n' ``` O handshake é concluído, e `curl` imprime o código de status que a sua aplicação retorna: ```text 200 ``` Os mesmos resultados valem no workload domain, `.map.azionedge.net`. No modo `permissive`, as duas requisições concluem o handshake e chegam à aplicação, assim como uma requisição com um certificado que outra CA assinou. --- ## Negue requisições sem um certificado de cliente válido No modo `permissive`, o workload não recusa nenhum cliente, então uma regra no [Rules Engine para Firewall](/pt-br/documentacao/plataforma/firewall/rules-engine/) deve recusar as requisições cujo certificado de cliente falhou na verificação. A regra só age quando o firewall está no deployment do workload. Para vincular um, consulte [Vincule um firewall a um workload](/pt-br/documentacao/guias/seguranca-de-aplicacoes/firewall-e-waf/proteja-seu-dominio/). Esta regra nega as requisições a `` cujo certificado de cliente não passou na validação: ```json { "name": "deny-unverified-clients", "active": true, "criteria": [ [ { "variable": "${host}", "conditional": "if", "operator": "is_equal", "argument": "" }, { "variable": "${client_certificate_validation}", "conditional": "and", "operator": "is_not_equal", "argument": "true" } ] ], "behaviors": [{ "type": "deny" }] } ``` No Azion Console, a mesma regra usa as variáveis *Host* e *Client Certificate Validation*, os operadores *is equal* e *is not equal* e o behavior *Deny (403 Forbidden)*. Para criar a regra pelo Azion Console, pela CLI ou pela API, consulte [Rules Engine para Firewall](/pt-br/documentacao/plataforma/firewall/rules-engine/). Depois que a regra se propagar, uma requisição a `` sem um certificado de cliente válido recebe `403 Forbidden`. Um cliente cujo certificado a CA confiável assinou continua chegando à aplicação. --- ## Passe os detalhes do certificado de cliente para a origem O modelo Open Banking exige que a origem receba o certificado de cliente em headers de requisição, a partir das variáveis `${ssl_client_escaped_cert}` e `${ssl_client_s_dn_parsed}`. `${ssl_client_escaped_cert}` contém o certificado de cliente como uma string PEM codificada para URL, e `${ssl_client_s_dn_parsed}` contém o Common Name (CN) do subject dele. Uma regra da Request Phase no [Rules Engine para Applications](/pt-br/documentacao/plataforma/applications/rules-engine/) adiciona cada header com o behavior `add_request_header`, na aplicação do deployment do workload. Esta regra adiciona o certificado de cliente a toda requisição que traz um, no header `Escaped-Client-Cert`: ```json { "name": "mtls-client-certificate", "active": true, "criteria": [[{ "variable": "${ssl_client_escaped_cert}", "conditional": "if", "operator": "exists", "argument": "" }]], "behaviors": [{ "type": "add_request_header", "attributes": { "value": "Escaped-Client-Cert: ${ssl_client_escaped_cert}" } }] } ``` O argumento do header tem a forma `Header-Name: value`, e Azion Console recusa qualquer outra forma com `Header must follow the header-name: value format`. Adicione uma segunda regra da mesma forma para `${ssl_client_s_dn_parsed}`, com um nome de header da sua escolha. Para criar as regras pelo Azion Console, pela CLI ou pela API, consulte [Rules Engine para Applications](/pt-br/documentacao/plataforma/applications/rules-engine/). As outras variáveis de certificado de cliente estão listadas em [Variáveis de mTLS](/pt-br/documentacao/plataforma/applications/rules-engine/#variaveis-de-mutual-transport-layer-security-mtls). Depois que as regras se propagarem, cada requisição que a Azion envia à origem para um cliente com certificado traz os headers. --- ## Próximos passos - [mTLS](/pt-br/documentacao/plataforma/workloads/mtls.md): Consulte cada campo do objeto mtls, o que cada modo de verificação faz e os erros. - [Vincule um firewall a um workload](/pt-br/documentacao/guias/seguranca-de-aplicacoes/firewall-e-waf/proteja-seu-dominio.md): Coloque um firewall no deployment do workload, para que as regras dele possam negar clientes não verificados. - [Rules Engine para Applications](/pt-br/documentacao/plataforma/applications/rules-engine.md): Encontre cada variável de certificado de cliente que uma regra pode ler e passar para a origem. - [Solucionar problemas de Workloads](/pt-br/documentacao/plataforma/workloads/solucao-de-problemas.md): Descubra por que um certificado é recusado ou um handshake TLS falha.