# Associar uma função de conexão do CloudFront
As funções de conexão do CloudFront permitem implementar uma lógica personalizada de validação de certificados durante handshakes do TLS, oferecendo extensões aos recursos integrados de autenticação mTLS.
## O que são funções de conexão?
As funções de conexão são funções JavaScript executadas no handshake do TLS após a validação de certificados de cliente. O certificado de cliente validado é transmitido à função de conexão, momento em que a função de conexão pode determinar se deseja conceder acesso ou não. Para ter informações mais detalhadas sobre como funções de conexão, consulte [Personalizar na borda com o CloudFront Functions](cloudfront-functions.md).
## Como as funções de conexão funcionam com a mTLS
Quando um cliente tenta estabelecer uma conexão mTLS com uma distribuição do CloudFront, ocorre a seguinte sequência de eventos:
1. O cliente inicia o handshake do TLS com o local da borda do CloudFront.
1. O CloudFront solicita e recebe o certificado do cliente.
1. O CloudFront executa a validação padrão do certificado em relação ao armazenamento confiável.
1. Se o certificado passar pela validação padrão, o CloudFront invocará a função de conexão. Se **IgnoreCertificateExpiry** estiver habilitada em **ViewerMtlsConfig**, os certificados expirados, mas válidos, também serão transmitidos à função de conexão. Se os certificados de cliente forem inválidos, as funções de conexão não serão invocadas.
1. A função de conexão recebe informações analisadas do certificado e detalhes da conexão.
1. A função toma a decisão de permitir/negar com base em uma lógica personalizada.
1. O CloudFront conclui ou encerra a conexão TLS com base em sua decisão.
As funções de conexão são invocadas tanto para o modo de verificação quanto para o modo opcional (quando os clientes apresentam certificados).
## Criar uma função de conexão
É possível criar funções de conexão usando o console do CloudFront ou a AWS CLI.
### Como criar uma função de conexão (console)
1. Faça login no Console de gerenciamento da AWS e abra o console do CloudFront em [https://console.aws.amazon.com/cloudfront/v4/home](https://console.aws.amazon.com/cloudfront/v4/home).
1. Selecione **Functions ** (Funções) no painel de navegação.
1. Escolha a guia **Funções de conexão** e selecione **Criar função de conexão**.
1. Insira um nome de função que seja exclusivo em sua conta da AWS.
1. Escolha **Continuar**.
1. No editor de funções, escreva o código JavaScript para validação do certificado. O manipulador de função deve chamar allow ou deny.
1. Opcional: um armazenamento KeyValue pode ser associado à função de conexão para implementar o controle de revogação.
1. Escolha **Salvar alterações**.
### Como criar uma função de conexão (AWS CLI)
O seguinte exemplo mostra como criar uma função de conexão:
Escreva o código da função em um arquivo separado (por exemplo, code.js):
```
function connectionHandler(connection) {
connection.allow();
}
```
```
aws cloudfront create-connection-function \
--name "certificate-validator" \
--connection-function-config '{
"Comment": "Client certificate validation function",
"Runtime": "cloudfront-js-2.0"
}' \
--connection-function-code fileb://code.js
```
## Estrutura do código da função de conexão
As funções de conexão implementam uma função connectionHandler que recebe um objeto de conexão contendo informações de certificado e conexão. A função deve usar `connection.allow()` ou `connection.deny()` para tomar uma decisão sobre a conexão.
### Exemplo de uma função de conexão básica
O seguinte exemplo mostra uma função de conexão simples que verifica o campo de assunto de certificados de cliente:
```
function connectionHandler(connection) {
// Only process if a certificate was presented
if (!connection.clientCertificate) {
console.log("No certificate presented");
connection.deny();
}
// Check the subject field for specific organization
const subject = connection.clientCertificate.certificates.leaf.subject;
if (!subject.includes("O=ExampleCorp")) {
console.log("Certificate not from authorized organization");
connection.deny();
} else {
// All checks passed
console.log("Certificate validation passed");
connection.allow();
}
}
```
A especificação completa das propriedades do certificado do cliente disponíveis no objeto de conexão é apresentada aqui:
```
{
"connectionId": "Fdb-Eb7L9gVn2cFakz7wWyBJIDAD4-oNO6g8r3vXDV132BtnIVtqDA==", // Unique identifier for this TLS connection
"clientIp": "203.0.113.42", // IP address of the connecting client (IPv4 or IPv6)
"clientCertificate": {
"certificates": {
"leaf": {
"subject": "CN=client.example.com,O=Example Corp,C=US", // Distinguished Name (DN) of the certificate holder
"issuer": "CN=Example Corp Intermediate CA,O=Example Corp,C=US", // Distinguished Name (DN) of the certificate authority that issued this certificate
"serialNumber": "4a:3f:5c:92:d1:e8:7b:6c", // Unique serial number assigned by the issuing CA (hexadecimal)
"validity": {
"notBefore": "2024-01-15T00:00:00Z", // Certificate validity start date (ISO 8601 format)
"notAfter": "2025-01-14T23:59:59Z" // Certificate expiration date (ISO 8601 format)
},
"sha256Fingerprint": "a1b2c3d4e5f6...abc123def456", // SHA-256 hash of the certificate (64 hex characters)
},
},
},
}
```
## Associar uma função de conexão
Depois de criar uma função de conexão, é necessário publicá-la no estágio ATIVO e associá-la à distribuição.
### Como publicar e associar uma função de conexão (console)
1. Faça login no Console de gerenciamento da AWS e abra o console do CloudFront em [https://console.aws.amazon.com/cloudfront/v4/home](https://console.aws.amazon.com/cloudfront/v4/home).
1. Selecione **Funções** no painel de navegação
1. Escolha a guia **Funções de conexão** e selecione uma função de conexão.
1. Escolha **Publicar** para movê-la para o estágio ATIVO.
1. Escolha **Adicionar associação** na tabela de distribuições associadas abaixo da seção de publicação.
1. Selecione a distribuição com a mTLS de visualizador habilitada que você deseja associar.
Alternativamente, as funções de conexão publicadas também podem ser associadas na página de detalhes da distribuição.
1. Acesse a página inicial do console, na qual todas as suas distribuições estão listadas.
1. Selecione a distribuição que você deseja associar.
1. Escolha a guia **Geral**.
1. Na seção **Configurações**, escolha **Editar**.
1. Na seção **Conectividade**, encontre **Autenticação mútua (mTLS) de visualizador**.
1. Em **Função de conexão**, selecione sua função.
1. Escolha **Salvar alterações**.
### Como associar uma função de conexão (AWS CLI)
O seguinte exemplo mostra como associar uma função de conexão a uma distribuição:
```
// DistributionConfig:
{
...other settings,
"ConnectionFunctionAssociation": {
"Id": "cf_30c2CV2elHwCoInb3LtcaUJkZeD"
}
}
```
## Casos de uso de funções de conexão
As funções de conexão permitem vários casos de uso avançados de mTLS:
+ **Validação de atributos do certificado**: verifique campos específicos nos certificados de cliente, como requisitos da unidade organizacional ou padrões de nome alternativo de assunto.
+ **Verificação de revogação de certificados**: implemente uma verificação personalizada de revogação de certificados usando KeyValueStore para armazenar números de série de certificados revogados.
+ **Políticas de certificado baseadas em IP**: utilize políticas de certificado diferentes com base no endereço IP do cliente ou em restrições geográficas.
+ **Validação de vários locatários**: implemente regras de validação específicas para locatários em que diferentes requisitos de certificado se apliquem com base em nomes de host ou atributos de certificado.
**nota**
As funções de conexão são executadas uma vez por conexão de cliente durante o handshake do TLS.
As funções de conexão só podem permitir ou negar conexões, não modificar solicitações/respostas HTTP.
Somente funções no estágio ATIVO (publicadas) podem ser associadas a distribuições.
Cada distribuição pode ter no máximo uma função de conexão.
## Próximas etapas
Após a associação de uma função de conexão a uma distribuição do CloudFront, é possível definir configurações opcionais para personalizar o comportamento da implementação de mTLS. Para ver instruções detalhadas sobre como definir configurações adicionais, como um modo opcional de validação de certificados de cliente, consulte [Definir configurações adicionais](configuring-additional-settings.md).