Configure mTLS em um workload

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.

Última atualização

Ver como Markdown Configurar agente

Você pode ativar o mutual TLS (mTLS) em um workload pela Azion CLI ou pela API. Para servir HTTPS no seu domínio com um certificado de servidor próprio, consulte Envie um 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.

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.
  • 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.
  • Azion 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 <workload-id>.
  • Um token pessoal para o header Authorization, no formato Token [TOKEN VALUE]. Para criar um token, consulte Tokens pessoais.
  • curl ou outro cliente HTTP.
  • O ID do workload. azion create workload o imprime como Created Workload with ID <workload-id>.

Envie o certificado de CA confiável

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.

Para enviar o certificado pela Azion CLI, passe o arquivo PEM da sua CA, aqui ca.pem:

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:

Created Digital Certificate with ID <trusted-ca-id>

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:

Shell
01curl --request POST \
02 --url https://api.azion.com/v4/workspace/tls/certificates \
03 --header 'Accept: application/json' \
04 --header 'Authorization: Token [TOKEN VALUE]' \
05 --header 'Content-Type: application/json' \
06 --data {
07 "name": "my-trusted-ca",
08 "type": "trusted_ca_certificate",
09 "certificate": "-----BEGIN CERTIFICATE-----\n<certificate-body>\n-----END CERTIFICATE-----\n"
10}

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.

Para enviar a CRL pela Azion CLI, passe o arquivo PEM dela, aqui ca.crl, e o nome da CA que a emitiu:

azion create crl --name my-crl --issuer "My CA" --crl ca.crl

O comando imprime o ID da nova CRL:

Created Certificate Revocation List with ID <crl-id>

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:

Shell
01curl --request POST \
02 --url https://api.azion.com/v4/workspace/tls/crls \
03 --header 'Accept: application/json' \
04 --header 'Authorization: Token [TOKEN VALUE]' \
05 --header 'Content-Type: application/json' \
06 --data {
07 "name": "my-crl",
08 "issuer": "My CA",
09 "crl": "-----BEGIN X509 CRL-----\n<crl-body>\n-----END X509 CRL-----\n"
10}

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.

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
01{
02 "id": <workload-id>,
03 "mtls": {
04 "enabled": true,
05 "config": { "certificate": <trusted-ca-id>, "crl": [<crl-id>], "verification": "enforce" }
06 }
07}

Atualize o workload com o arquivo:

azion update workload --file mtls.json

O comando imprime o ID do workload que atualizou:

Updated Workload with ID <workload-id>

Para confirmar a alteração, descreva o workload:

azion describe workload --workload-id <workload-id> --format json

Este trecho da saída mostra o objeto mtls como o workload o armazena:

JSON
01{
02 "mtls": { "config": { "certificate": <trusted-ca-id>, "crl": [<crl-id>], "verification": "enforce" }, "enabled": true }
03}

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:

Shell
01curl --request PATCH \
02 --url https://api.azion.com/v4/workspace/workloads/<workload-id> \
03 --header 'Accept: application/json' \
04 --header 'Authorization: Token [TOKEN VALUE]' \
05 --header 'Content-Type: application/json' \
06 --data {
07 "mtls": {
08 "enabled": true,
09 "config": { "certificate": <trusted-ca-id>, "crl": [<crl-id>], "verification": "enforce" }
10 }
11}

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.

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:

curl -skv https://<your-domain>/ -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:

Texto
01* (304) (IN), TLS handshake, Request CERT (13):
02* (304) (IN), TLS handshake, Certificate (11):
03* (304) (IN), TLS handshake, CERT verify (15):
04* (304) (IN), TLS handshake, Finished (20):
05* (304) (OUT), TLS handshake, Certificate (11):
06* (304) (OUT), TLS handshake, Finished (20):
07* SSL connection using TLSv1.3 / AEAD-AES256-GCM-SHA384 / [blank] / UNDEF
08* 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:

curl -sk --cert client.pem --key client.key https://<your-domain>/ -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:

200

Os mesmos resultados valem no workload domain, <id>.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 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.

Esta regra nega as requisições a <your-domain> cujo certificado de cliente não passou na validação:

JSON
01{
02 "name": "deny-unverified-clients",
03 "active": true,
04 "criteria": [
05 [
06 { "variable": "${host}", "conditional": "if", "operator": "is_equal", "argument": "<your-domain>" },
07 { "variable": "${client_certificate_validation}", "conditional": "and", "operator": "is_not_equal", "argument": "true" }
08 ]
09 ],
10 "behaviors": [{ "type": "deny" }]
11}

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.

Depois que a regra se propagar, uma requisição a <your-domain> 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 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
01{
02 "name": "mtls-client-certificate",
03 "active": true,
04 "criteria": [[{ "variable": "${ssl_client_escaped_cert}", "conditional": "if", "operator": "exists", "argument": "" }]],
05 "behaviors": [{ "type": "add_request_header", "attributes": { "value": "Escaped-Client-Cert: ${ssl_client_escaped_cert}" } }]
06}

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. As outras variáveis de certificado de cliente estão listadas em Variáveis de 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

mTLSConsulte cada campo do objeto mtls, o que cada modo de verificação faz e os erros.Vincule um firewall a um workloadColoque um firewall no deployment do workload, para que as regras dele possam negar clientes não verificados.Rules Engine para ApplicationsEncontre cada variável de certificado de cliente que uma regra pode ler e passar para a origem.Solucionar problemas de WorkloadsDescubra por que um certificado é recusado ou um handshake TLS falha.