View a markdown version of this page

Configuration de noms de domaine personnalisés pour les points de terminaison Gateway - Amazon Bedrock AgentCore
Conditions préalablesPrésentation de la solutionÉtapes d’implémentationTester votre domaine personnaliséConfiguration des clients MCPConsidérations supplémentairesRésolution des problèmesConclusion

Configuration de noms de domaine personnalisés pour les points de terminaison Gateway

Par défaut, les points de terminaison Gateway sont AWS dotés d'un nom de domaine géré au format. <gateway-id>.gateway.bedrock-agentcore.<region>.amazonaws.com Pour les environnements de production ou pour créer une expérience plus conviviale, vous pouvez utiliser un nom de domaine personnalisé pour le point de terminaison de votre passerelle. Cette section vous explique comment configurer un nom de domaine personnalisé en utilisant Amazon CloudFront comme proxy inverse.

Conditions préalables

Avant de commencer, assurez-vous de disposer des éléments suivants :

  • Un point de terminaison Gateway fonctionnel

  • Délégation DNS (si votre domaine Route 53 doit être accessible au public)

  • AWS CDK installé et configuré (si vous suivez l'approche CDK)

  • Autorisations IAM appropriées pour créer et gérer des CloudFront distributions, des zones hébergées Route 53 et des certificats ACM

Présentation de la solution

La solution implique les éléments suivants :

  • Zone hébergée Route 53 : gère les enregistrements DNS pour votre domaine personnalisé

  • Certificat ACM : fournit un SSL/TLS cryptage pour votre domaine personnalisé

  • CloudFront Distribution : agit comme un proxy inverse, transférant les demandes de votre domaine personnalisé vers le point de terminaison Gateway

  • Route 53 A Record : associe votre domaine personnalisé à la CloudFront distribution

Les étapes suivantes vous guideront dans la configuration de ces composants à l'aide de AWS CDK.

Étapes d’implémentation

Étape 1 : Création d'une zone hébergée Route 53

Créez d'abord une zone hébergée Route 53 pour votre domaine personnalisé :

import { RemovalPolicy } from 'aws-cdk-lib';
import { PublicHostedZone } from 'aws-cdk-lib/aws-route53';

const domainName = 'my.example.com';

const hostedZone = new PublicHostedZone(this, 'HostedZone', {
    zoneName: domainName,
});
this.hostedZone.applyRemovalPolicy(RemovalPolicy.RETAIN);
Note

Nous appliquons une politique de suppression visant RETAIN à empêcher la suppression accidentelle de la zone hébergée lors des mises à jour ou de la suppression de la pile.

Étape 2 : Création d'un DNS-validated certificat

Créez ensuite un SSL/TLS certificat pour votre domaine personnalisé à l'aide de AWS Certificate Manager (ACM) avec validation DNS :

import { RemovalPolicy } from 'aws-cdk-lib';
import { Certificate, CertificateValidation } from 'aws-cdk-lib/aws-certificatemanager';

const certificate = new Certificate(this, 'SSLCertificate', {
    domainName: domainName, // route53 hosted zone domain name from step 1
    validation: CertificateValidation.fromDns(hostedZone), // route53 hosted zone from step 1
});
this.certificate.applyRemovalPolicy(RemovalPolicy.RETAIN);

La validation DNS crée automatiquement les enregistrements de validation nécessaires dans votre zone hébergée Route 53.

Étape 3 : Création d'une CloudFront distribution

Créez une CloudFront distribution qui servira de proxy inverse pour votre point de terminaison Gateway :

import {
  AllowedMethods,
  CachePolicy,
  Distribution,
  OriginProtocolPolicy,
  ViewerProtocolPolicy
} from 'aws-cdk-lib/aws-cloudfront';
import { HttpOrigin } from 'aws-cdk-lib/aws-cloudfront-origins';

const bedrockAgentCoreGatewayHostName = '<mymcpserver>.gateway.bedrock-agentcore.<region>.amazonaws.com'
const bedrockAgentCoreGatewayPath = '/mcp' // can also be left undefined, depending on your requirement

const distribution = new Distribution(this, 'Distribution', {
    defaultBehavior: {
        origin: new HttpOrigin(bedrockAgentCoreGatewayHostName, {
            protocolPolicy: OriginProtocolPolicy.HTTPS_ONLY,
            originPath: bedrockAgentCoreGatewayPath,
        }),
        viewerProtocolPolicy: ViewerProtocolPolicy.HTTPS_ONLY,
        cachePolicy: CachePolicy.CACHING_DISABLED, // important since caching is enabled by default and hence is not suitable for a reverse proxy
        allowedMethods: AllowedMethods.ALLOW_ALL,
    },
    domainNames: [domainName], // route53 hosted zone domain name from step 1
    certificate: certificate, // ssl certificate for the route53 domain from step 2
});
Important

Configurez cachePolicy: CachePolicy.CACHING_DISABLED pour que les réponses de votre point de terminaison Gateway CloudFront ne soient pas mises en cache, ce qui est important pour les interactions dynamiques avec les API.

<mymcpserver>Remplacez-le par votre identifiant de passerelle et <region> par votre AWS région (par exemple,us-east-1).

Étape 4 : Création d'un enregistrement Route 53 A

Créez un enregistrement Route 53 A qui pointe votre domaine personnalisé vers la CloudFront distribution :

import { ARecord, RecordTarget } from 'aws-cdk-lib/aws-route53';
import { CloudFrontTarget } from 'aws-cdk-lib/aws-route53-targets';

const aRecord = new ARecord(this, 'AliasRecord', {
    zone: hostedZone, // route53 hosted zone from step 1
    recordName: domainName, // route53 hosted zone domain name from step 1
    target: RecordTarget.fromAlias(new CloudFrontTarget(distribution)), // cloudfront distribution from step 3
});

Cela crée un enregistrement d'alias qui associe votre domaine personnalisé à la CloudFront distribution.

Étape 5 : Déployez votre infrastructure

Déployez votre pile CDK pour créer les ressources :

cdk deploy

Le processus de déploiement peut prendre un certain temps, en particulier pour la validation des certificats et la création CloudFront de distribution.

Tester votre domaine personnalisé

Après avoir déployé votre infrastructure, vérifiez que votre domaine personnalisé est correctement configuré :

Vérifier la résolution DNS

Utilisez la dig commande pour vérifier que votre domaine personnalisé correspond à la CloudFront distribution :

dig my.example.com

Le résultat doit indiquer que votre domaine correspond à CloudFront des adresses IP.

Vérifier le certificat SSL

curlÀ utiliser pour vérifier que le certificat SSL est correctement configuré :

curl -v https://my.example.com

Le résultat doit montrer une poignée de main SSL réussie sans erreur de certificat.

Configuration des clients MCP

Une fois votre domaine personnalisé configuré et vérifié, vous pouvez configurer vos clients MCP pour qu'ils l'utilisent :

Configuration du curseur

Pour Cursor, mettez à jour votre fichier de configuration :

{
  "mcpServers": {
    "my-mcp-server": {
      "url": "https://my.example.com"
    }
  }
}

Autres clients MCP

Pour les clients MCP qui ne prennent pas en charge nativement le protocole HTTP streamable :

{
  "mcpServers": {
    "my-mcp-server": {
      "command": "/path/to/uvx",
        "args": [
            "mcp-proxy",
            "--transport",
            "streamablehttp",
            "https://my.example.com"
        ]
    }
  }
}

Considérations supplémentaires

Incidences financières

L'utilisation en CloudFront tant que proxy inverse entraîne des coûts supplémentaires pour le transfert de données et le traitement des demandes. Passez en revue le modèle de CloudFront tarification pour comprendre les implications financières pour votre cas d'utilisation spécifique.

Considérations de sécurité

Envisagez de mettre en œuvre des mesures de sécurité supplémentaires telles que :

  • Règles WAF pour protéger votre terminal contre les exploits Web courants

  • Geo-restrictions pour limiter l'accès à des régions géographiques spécifiques

  • En-têtes personnalisés ou signature de demandes pour ajouter une couche d'authentification supplémentaire

Surveillance et journalisation

Activez les journaux CloudFront d'accès et configurez les CloudWatch alarmes pour surveiller l'état et les performances de votre configuration de domaine personnalisée.

Renouvellement du certificat

Les certificats ACM émis par validation DNS sont automatiquement renouvelés tant que les enregistrements DNS restent en place. Assurez-vous de ne pas supprimer les enregistrements de validation.

Point de terminaison de ressource protégé par OAuth avec domaines personnalisés

Par défaut, le /.well-known/oauth-protected-resource point de terminaison renvoie une URL de ressource contenant le domaine de passerelle au lieu de votre domaine personnalisé. Cela peut entraîner l'échec de l'authentification des clients OAuth lorsqu'ils utilisent des domaines personnalisés.

Pour résoudre ce problème, vous pouvez implémenter une fonction Lambda @Edge qui intercepte la réponse de découverte OAuth et génère une nouvelle réponse avec l'URL de domaine personnalisée correcte. Voici l'approche :

  • Utilisez Lambda @Edge avec le type d'événement ORIGIN_RESPONSE : créez une fonction qui déclenche les réponses d'origine pour intercepter la réponse du point de terminaison de la ressource protégée OAuth.

  • Générer une nouvelle réponse : Lambda @Edge ne peut pas lire les corps de réponse d'origine. Par conséquent, au lieu de modifier la réponse existante, générez une toute nouvelle réponse JSON avec le domaine personnalisé.

  • Associer au CloudFront comportement : configurez la fonction Lambda @Edge pour qu'elle se déclenche spécifiquement pour le modèle de /.well-known/oauth-protected-resource chemin.

    Après avoir implémenté cette solution, le point de terminaison de la ressource protégée OAuth renverra le domaine personnalisé correct :

    curl https://my-custom-domain.com/.well-known/oauth-protected-resource
{
  "authorization_servers": ["https://my-org.okta.com/oauth2/default"],
  "resource": "https://my-custom-domain.com/mcp"
}
    Note

    Lambda @Edge fournit une solution à ce problème, mais la mise en œuvre de domaines personnalisés pour AgentCore Gateway sans support intégré nécessite une complexité supplémentaire qui n'est peut-être pas optimale pour tous les clients. Considérez cette approche comme une solution de contournement jusqu'à ce que la prise en charge native de la découverte OAuth avec des domaines personnalisés soit disponible.

Résolution des problèmes

Problèmes de résolution du DNS

Si votre domaine personnalisé ne se résout pas correctement :

  • Vérifiez que l'enregistrement A est correctement configuré dans votre zone hébergée Route 53

  • Vérifiez que les serveurs de noms de votre domaine sont correctement configurés par votre bureau d'enregistrement de domaines

  • Prévoyez du temps pour la propagation du DNS (jusqu'à 48 heures dans certains cas)

Problèmes liés aux certificats SSL

Si vous rencontrez des erreurs de certificat SSL :

  • Vérifiez que le certificat est émis et actif dans la console ACM

  • Vérifiez que le certificat est correctement associé à votre CloudFront distribution

  • Assurez-vous que le certificat couvre le nom de domaine exact que vous utilisez

Problèmes de connectivité de la passerelle

Si votre domaine personnalisé ne se connecte pas à votre passerelle :

  • Vérifiez que le domaine d'origine et le chemin de votre CloudFront distribution sont corrects

  • Vérifiez que le point de terminaison de votre passerelle est directement accessible

  • Vérifiez les journaux CloudFront de distribution pour détecter toute erreur

Conclusion

La configuration d'un nom de domaine personnalisé pour votre point de terminaison Gateway améliore l'apparence professionnelle de votre application et offre de la flexibilité dans la gestion de vos points de terminaison d'API. En suivant les étapes décrites dans ce guide, vous pouvez créer une configuration de domaine personnalisée sécurisée et fiable CloudFront en utilisant un proxy inverse.

Pour plus d'informations sur les fonctionnalités et fonctionnalités de Gateway, consultez Amazon Bedrock AgentCore Gateway : connectez en toute sécurité des outils et d'autres ressources à votre passerelle.