Écrire le code de la fonction de CloudFront connexion pour la validation mutuelle du protocole TLS (viewer)

CloudFront Les fonctions de connexion vous permettent d'écrire des JavaScript fonctions légères pour la validation des certificats mTLS et la logique d'authentification personnalisée. Votre code de fonction de connexion permet de valider les certificats clients, de mettre en œuvre des règles d'authentification spécifiques à l'appareil, de gérer les scénarios de révocation de certificats et de prendre des allow/deny décisions concernant les connexions TLS sur des sites périphériques dans CloudFront le monde entier.

Les fonctions de connexion constituent un moyen puissant d'étendre CloudFront la validation des certificats intégrée à votre propre logique métier. Contrairement aux fonctions de demande et de réponse de l'utilisateur qui traitent les données HTTP, les fonctions de connexion fonctionnent au niveau de la couche TLS et ont accès aux informations de certificat, aux adresses IP des clients et aux détails de connexion TLS. Ils sont donc idéaux pour mettre en œuvre des modèles de sécurité Zero Trust, des systèmes d'authentification des appareils et des politiques de validation de certificats personnalisées qui vont au-delà de la validation PKI standard.

Le code de votre fonction de connexion s'exécute dans un environnement isolé et sécurisé avec des temps de démarrage inférieurs à la milliseconde et peut être adapté pour gérer des millions de connexions par seconde. Le runtime est optimisé pour les charges de travail de validation des certificats et fournit une intégration intégrée CloudFront KeyValueStore pour les opérations de recherche de données en temps réel, permettant des scénarios d'authentification sophistiqués tels que la vérification des listes de révocation de certificats et la validation des listes d'autorisation des appareils.

Pour vous aider à écrire un code de fonction de connexion efficace, consultez les rubriques suivantes. Pour des exemples de code complets et des step-by-step didacticiels, consultez les sections du didacticiel de ce guide et explorez les exemples de fonctions de connexion disponibles dans la CloudFront console.

CloudFront Cas d'utilisation et objectifs de la fonction de connexion

Avant d'écrire votre fonction de CloudFront connexion, déterminez soigneusement le type de logique d'authentification ou de validation de certificat que vous devez implémenter. Les fonctions de connexion sont conçues pour des cas d'utilisation spécifiques qui nécessitent une validation personnalisée allant au-delà de la vérification des certificats PKI standard. Comprendre votre cas d'utilisation vous permet de concevoir un code efficace qui répond à vos exigences de sécurité tout en maintenant des performances optimales.

Les cas d'utilisation courants des fonctions de connexion incluent :

Les fonctions de connexion s'exécutent CloudFront après avoir effectué la validation standard des certificats (vérification de la chaîne de confiance, contrôles d'expiration et validation des signatures) mais avant que la connexion TLS ne soit établie. Ce calendrier vous donne la flexibilité d'ajouter des critères de validation personnalisés tout en bénéficiant CloudFront de la validation des certificats intégrée. Votre fonction reçoit les résultats de la validation standard et peut prendre des décisions éclairées quant à l'autorisation ou au refus de la connexion en fonction de critères standard et personnalisés.

Lorsque vous concevez votre fonction de connexion, tenez compte des implications de votre logique de validation en termes de performances. Les fonctions ayant une limite d'exécution de 5 millisecondes, les opérations complexes doivent être optimisées en termes de rapidité. Utilisez-le KeyValueStore pour des recherches de données rapides plutôt que pour des calculs complexes, et structurez votre logique de validation de manière à ce qu'elle échoue rapidement en cas de certificats non valides.

CloudFront Structure des événements de la fonction de connexion et format de réponse

CloudFront Les fonctions de connexion reçoivent une structure d'événements différente de celle des fonctions de demande et de réponse de l'utilisateur. Au lieu des request/response données HTTP, les fonctions de connexion reçoivent des informations de certificat et de connexion que vous pouvez utiliser pour prendre des décisions d'authentification.

Structure d'événements pour les fonctions de connexion

Les fonctions de connexion reçoivent un objet d'événement contenant des informations de certificat et de connexion. La structure des événements de la fonction est illustrée ci-dessous :

{
  "clientCertificate": {
    "certificates": {
      "leaf": {
        "serialNumber": "string",
        "issuer": "string",
        "subject": "string",
        "validity": {
          "notBefore": "string",
          "notAfter": "string",
        },
        "sha256Fingerprint": "string"
      }
    }
  },
  "clientIp": "string",
  "endpoint": "string",
  "distributionId": "string",
  "connectionId": "string"
}

Vous trouverez ci-dessous un exemple de structure d'objet d'événement :

{
  "clientCertificate": {
    "certificates": {
      "leaf": {
        "serialNumber": "00:9e:2a:af:16:56:e5:47:25:7d:2e:38:c3:f9:9d:57:fa",
        "issuer": "C=US, O=Ram, OU=Edge, ST=WA, CN=mTLS-CA, L=Snoqualmie",
        "subject": "C=US, O=Ram, OU=Edge, ST=WA, CN=mTLS-CA, L=Snoqualmie",
        "validity": {
          "notBefore": "2025-09-10T23:43:10Z",
          "notAfter": "2055-09-11T00:43:02Z"
        },
        "sha256Fingerprint": "_w6bJ7aOAlGOj7NUhJxTfsfee-ONg_xop3_PTgTJpqs="
      }
    }
  },
  "clientIp": "127.0.0.1",
  "endpoint": "d3lch071jze0cb.cloudfront.net",
  "distributionId": "E1NXS4MQZH501R",
  "connectionId": "NpvTe1925xfj24a67sPQr7ae42BIq03FGhJJKfrQYWZcWZFp96SIIg=="
}

Format de réponse des fonctions de connexion

Votre fonction de connexion doit renvoyer un objet de réponse indiquant s'il faut autoriser ou refuser la connexion. Utilisez les méthodes d'assistance pour prendre des décisions de connexion :

function connectionHandler(connection) {
    // Helper methods to allow or deny connections
    if (/* some logic to determine if function should allow connection */) {
        connection.allow();
    } else {
        connection.deny();
    }
}

Contrairement aux fonctions de demande et de réponse de l'utilisateur, les fonctions de connexion ne peuvent pas modifier les requêtes ou les réponses HTTP. Ils peuvent uniquement autoriser ou refuser la connexion TLS.

CloudFront Fonctionnalités JavaScript d'exécution des fonctions de connexion

CloudFront Les fonctions de connexion utilisent le CloudFront Functions JavaScript Runtime 2.0, qui fournit un environnement sécurisé et performant spécifiquement optimisé pour les charges de travail de validation de certificats. Le runtime est conçu pour démarrer en quelques millisecondes et gérer des millions d'exécutions simultanées sur le réseau périphérique CloudFront mondial.

L'environnement d'exécution inclut une prise en charge JavaScript linguistique complète :

Les fonctions de connexion sont optimisées pour garantir des performances élevées dans les scénarios de validation de certificats. Le moteur d'exécution gère automatiquement la gestion de la mémoire, le ramassage des déchets et le nettoyage des ressources afin de garantir des performances constantes sur des millions de connexions simultanées. Toutes les opérations sont conçues pour être déterministes et rapides, les recherches s'effectuant généralement KeyValueStore en quelques microsecondes.

L'environnement d'exécution est complètement isolé entre les exécutions de fonctions, ce qui garantit l'absence de fuite de données entre les différentes connexions client. Chaque exécution de fonction commence par un état propre et n'a aucun accès aux résultats d'exécution précédents ni aux données client provenant d'autres connexions.

CloudFront Méthodes d'assistance à la fonction de connexion et APIs

CloudFront Les fonctions de connexion fournissent des méthodes d'assistance spécialisées conçues pour simplifier les décisions de validation des certificats et améliorer l'observabilité. Ces méthodes sont optimisées pour le flux de travail de validation des connexions et s'intègrent parfaitement aux systèmes CloudFront de journalisation et de surveillance des connexions.

Ces méthodes fournissent une interface claire et déclarative pour prendre des décisions de connexion et enregistrer les informations pertinentes pour la surveillance et le débogage. Le allow/deny modèle garantit que l'intention de votre fonction est claire et CloudFront peut optimiser la gestion des connexions en fonction de votre décision. Les données de journalisation personnalisées sont immédiatement disponibles dans les journaux de CloudFront connexion et peuvent être utilisées avec les outils d'analyse des journaux pour la surveillance de la sécurité et des informations opérationnelles.

Appelez toujours connection.allow () ou connection.deny () avant que votre fonction ne soit terminée. Si aucune des deux méthodes n'est appelée, CloudFront refusera la connexion par défaut pour des raisons de sécurité.

CloudFront KeyValueStore Intégration de la fonction de connexion

CloudFront Les fonctions de connexion peuvent être utilisées CloudFront KeyValueStore pour effectuer des recherches de données ultrarapides pour les scénarios de validation de certificats. KeyValueStore est particulièrement puissant pour les fonctions de connexion, car il fournit un accès global aux données, finalement cohérent, avec des temps de recherche en microsecondes sur tous les CloudFront emplacements périphériques. Il est donc idéal pour gérer les listes de révocation de certificats, les listes d'appareils autorisés, les configurations des locataires et les autres données de validation qui doivent être accessibles lors des connexions TLS.

KeyValueStore l'intégration est conçue spécifiquement pour les flux de travail de validation des connexions à hautes performances :

KeyValueStore les opérations sont asynchrones et doivent être utilisées avec la syntaxe async/await. KeyValueStore Il a une limite de taille totale de 10 Mo et prend en charge jusqu'à 10 millions de paires clé-valeur. KeyValueStore les données sont finalement cohérentes sur tous les sites périphériques, les mises à jour se propageant généralement en quelques secondes.

Pour des performances optimales, structurez vos KeyValueStore clés afin de minimiser les opérations de recherche. Utilisez les numéros de série des certificats comme clés pour une simple vérification de révocation, ou créez des clés composites combinant le hachage de l'émetteur et le numéro de série pour les environnements multi-CA. Tenez compte des compromis entre complexité clé et KeyValueStore capacité lors de la conception de votre structure de données.

Utilisez l'async et attendez

Les fonctions de connexion prennent en charge les opérations asynchrones à l'aide de async/await la syntaxe, ce qui est essentiel lorsque vous travaillez avec KeyValueStore des opérations ou d'autres tâches asynchrones. Ce async/await modèle garantit que votre fonction attend la fin des recherches avant de KeyValueStore prendre des décisions de connexion, tout en conservant les caractéristiques de haute performance requises pour le traitement des poignées de main TLS.

Une async/await utilisation appropriée est essentielle pour les fonctions de connexion, car les KeyValueStore opérations, bien que très rapides, restent des opérations réseau qui nécessitent une coordination au sein CloudFront de l'infrastructure distribuée. Le moteur d'exécution gère automatiquement la résolution des promesses et garantit que votre fonction s'exécute dans le délai d'exécution de 5 millisecondes.

import cf from 'cloudfront';

async function connectionHandler(connection) {
    const kvsHandle = cf.kvs();
    
    // Async operation to check KeyValueStore for certificate revocation
    const isRevoked = await kvsHandle.exists(connection.clientCertificate.certificates.leaf.serialNumber);
    
    if (isRevoked) {
        // Log the revocation decision with certificate details
        connection.logCustomData(`REVOKED_CERT:${connection.clientCertificate.certificates.leaf.serialNumber}:${connection.clientCertificate.certificates.leaf.issuer}`);
        console.log(`Denying connection for revoked certificate: ${connection.clientCertificate.certificates.leaf.serialNumber}`);
        return connection.deny();
    }
    
    // Log successful validation for monitoring
    connection.logCustomData(`VALID_CERT:${connection.clientCertificate.certificates.leaf.serialNumber}`);
    console.log(`Allowing connection for valid certificate: ${connection.clientCertificate.certificates.leaf.serialNumber}`);
    return connection.allow();
}

À toujours utiliser async/await lors de l'appel de KeyValueStore méthodes ou d'autres opérations asynchrones. Le moteur d'exécution de la fonction de connexion gère automatiquement la résolution des promesses et garantit un flux d'exécution correct dans les limites temporelles strictes du traitement des poignées de main TLS. Évitez d'utiliser .then () ou des modèles de rappel, car async/await permet une gestion des erreurs plus propre et de meilleures performances dans l'environnement des fonctions de connexion.

Lorsque vous concevez des fonctions de connexion asynchrones, structurez votre code de manière à minimiser le nombre d' KeyValueStore opérations et exécutez-les le plus tôt possible dans votre logique de validation. Cela garantit des performances maximales et réduit le risque de problèmes de temporisation pendant les périodes de forte affluence. Envisagez de regrouper les contrôles de validation associés et d'utiliser la KeyValueStore méthode la plus efficace (exists () vs get ()) pour votre cas d'utilisation.

Exemples de code de fonction de connexion

Les exemples suivants illustrent les modèles de fonctions de connexion courants pour différents scénarios de validation. Utilisez ces exemples comme points de départ pour vos propres implémentations de fonctions de connexion.

async function connectionHandler(connection) {
    // Custom validation: check device serial number format
    const serialNumber = connection.clientCertificate.certificates.leaf.serialNumber;
    if (!serialNumber.startsWith("DEV")) {
        connection.logCustomData(`INVALID_SERIAL:${serialNumber}`);
        return connection.deny();
    }
    
    // Validate certificate subject contains required organizational unit
    const subject = connection.clientCertificate.certificates.leaf.subject;
    if (!subject.includes("OU=AuthorizedDevices")) {
        connection.logCustomData(`INVALID_OU:${subject}`);
        return connection.deny();
    }
    
    // Allow connection for valid devices
    connection.logCustomData(`VALID_DEVICE:${serialNumber}`);
    return connection.allow();
}

async function connectionHandler(connection) {
    if (connection.clientCertificate) {
        // mTLS connection - enhanced validation for certificate holders
        const subject = connection.clientCertificate.certificates.leaf.subject;
        connection.logCustomData(`MTLS_SUCCESS:${subject}:${connection.clientIp}`);
        console.log(`mTLS connection from: ${subject}`);
        return connection.allow();
    } else {
        // Non-mTLS connection - apply IP-based restrictions
        const clientIp = connection.clientIp;
        
        // Only allow non-mTLS from specific IP ranges
        if (clientIp.startsWith("203.0.113.") || clientIp.startsWith("198.51.100.")) {
            connection.logCustomData(`NON_MTLS_ALLOWED:${clientIp}`);
            console.log(`Non-mTLS connection allowed from: ${clientIp}`);
            return connection.allow();
        }
        
        connection.logCustomData(`NON_MTLS_DENIED:${clientIp}`);
        return connection.deny();
    }
}