# Gateway エンドポイントのカスタムドメイン名の設定
<a name="gateway-custom-domains"></a>

デフォルトでは、ゲートウェイエンドポイントには 形式の AWSマネージドドメイン名が提供されます`<gateway-id>.gateway.bedrock-agentcore.<region>.amazonaws.com`。本番稼働環境や、よりユーザーフレンドリなエクスペリエンスを作成するには、ゲートウェイエンドポイントにカスタムドメイン名を使用することをお勧めします。このセクションでは、Amazon CloudFront をリバースプロキシとして使用してカスタムドメイン名を設定する方法について説明します。

## 前提条件
<a name="gateway-custom-domains-prereq"></a>

開始する前に、以下があることを確認してください。
+ 作業ゲートウェイエンドポイント
+ DNS 委任 (Route 53 ドメインがパブリックにアクセス可能である必要がある場合)
+  AWS CDK のインストールと設定 (CDK アプローチに従う場合)
+ CloudFront ディストリビューション、Route 53 ホストゾーン、ACM 証明書を作成および管理するための適切な IAM アクセス許可

## ソリューションの概要
<a name="gateway-custom-domains-overview"></a>

このソリューションには、次のコンポーネントが必要です。
+  **Route 53 ホストゾーン**: カスタムドメインの DNS レコードを管理します。
+  **ACM 証明書**: カスタムドメインの SSL/TLS 暗号化を提供します
+  **CloudFront ディストリビューション**: リバースプロキシとして機能し、カスタムドメインから Gateway エンドポイントにリクエストを転送します。
+  **Route 53 A Record** : カスタムドメインを CloudFront ディストリビューションにマッピングします

次の手順では、 AWS CDK を使用してこれらのコンポーネントを設定する方法について説明します。

## 実装手順
<a name="gateway-custom-domains-steps"></a>

### ステップ 1: Route 53 ホストゾーンを作成する
<a name="gateway-custom-domains-hosted-zone"></a>

まず、カスタムドメインの Route 53 ホストゾーンを作成します。

```
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);
```

**注記**  
スタックの更新または削除中にホストゾーンが誤って削除されないように`RETAIN`、 の削除ポリシーを適用します。

### ステップ 2: DNS 検証済み証明書を作成する
<a name="gateway-custom-domains-certificate"></a>

次に、DNS 検証で AWS Certificate Manager (ACM) を使用して、カスタムドメインの SSL/TLS 証明書を作成します。

```
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);
```

DNS 検証は、Route 53 ホストゾーンに必要な検証レコードを自動的に作成します。

### ステップ 3: CloudFront ディストリビューションを作成する
<a name="gateway-custom-domains-cloudfront"></a>

ゲートウェイエンドポイントのリバースプロキシとして機能する CloudFront ディストリビューションを作成します。

```
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
});
```

**重要**  
CloudFront が Gateway エンドポイントからのレスポンスをキャッシュしないように `cachePolicy: CachePolicy.CACHING_DISABLED`を設定します。これは動的な API インタラクションにとって重要です。

をゲートウェイ ID `<mymcpserver>`に、 を AWS リージョン (例: ) `us-east-1` `<region>`に置き換えます。

### ステップ 4: Route 53 A レコードを作成する
<a name="gateway-custom-domains-dns-record"></a>

カスタムドメインを CloudFront ディストリビューションにポイントする Route 53 A レコードを作成します。

```
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
});
```

これにより、カスタムドメインを CloudFront ディストリビューションにマッピングするエイリアスレコードが作成されます。

### ステップ 5: インフラストラクチャをデプロイする
<a name="gateway-custom-domains-deploy"></a>

CDK スタックをデプロイしてリソースを作成します。

```
cdk deploy
```

デプロイプロセス、特に証明書の検証と CloudFront ディストリビューションの作成には時間がかかる場合があります。

## カスタムドメインのテスト
<a name="gateway-custom-domains-testing"></a>

インフラストラクチャをデプロイしたら、カスタムドメインが正しく設定されていることを確認します。

### DNS 解決の検証
<a name="gateway-custom-domains-testing-dns"></a>

`dig` コマンドを使用して、カスタムドメインが CloudFront ディストリビューションに解決されることを確認します。

```
dig my.example.com
```

出力には、ドメインが CloudFront の IP アドレスに解決されたことが示されます。

### SSL 証明書の検証
<a name="gateway-custom-domains-testing-ssl"></a>

を使用して`curl`、SSL 証明書が正しく設定されていることを確認します。

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

出力には、証明書エラーなしで成功した SSL ハンドシェイクが表示されます。

## MCP クライアントの設定
<a name="gateway-custom-domains-client-config"></a>

カスタムドメインを設定して検証したら、それを使用するように MCP クライアントを設定できます。

### カーソル設定
<a name="gateway-custom-domains-client-config-cursor"></a>

カーソルの場合は、設定ファイルを更新します。

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

### その他の MCP クライアント
<a name="gateway-custom-domains-client-config-other"></a>

ストリーミング可能な HTTP をネイティブにサポートしていない MCP クライアントの場合:

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

## その他の考慮事項
<a name="gateway-custom-domains-considerations"></a>

 **コストへの影響**   
CloudFront をリバースプロキシとして使用すると、データ転送とリクエスト処理に追加のコストが発生します。CloudFront 料金モデルを確認して、特定のユースケースのコストへの影響を理解します。

 **セキュリティに関する考慮事項**   
次のような追加のセキュリティ対策の実施を検討してください。  
+ 一般的なウェブエクスプロイトからエンドポイントを保護するための WAF ルール
+ 特定の地理的リージョンへのアクセスを制限するための地理的制限
+ カスタムヘッダーまたはリクエスト署名で認証レイヤーを追加する

 **モニタリングとログ記録**   
CloudFront アクセスログを有効にし、CloudWatch アラームを設定して、カスタムドメイン設定の状態とパフォーマンスをモニタリングします。

 **証明書の更新**   
DNS 検証によって発行された ACM 証明書は、DNS レコードが残っている限り、自動的に更新されます。検証レコードを削除しないようにしてください。

 **カスタムドメインを持つ OAuth で保護されたリソースエンドポイント**   
デフォルトでは、`/.well-known/oauth-protected-resource`エンドポイントはカスタムドメインではなくゲートウェイドメインを含むリソース URL を返します。これにより、カスタムドメインの使用時に OAuth クライアントが認証に失敗する可能性があります。  
この問題を解決するには、OAuth 検出レスポンスを傍受し、正しいカスタムドメイン URL で新しいレスポンスを生成する Lambda@Edge 関数を実装できます。アプローチは次のとおりです。  
+  **ORIGIN\_RESPONSE イベントタイプで Lambda@Edge** を使用する: オリジンレスポンスをトリガーして OAuth で保護されたリソースエンドポイントレスポンスを傍受する関数を作成します。
+  **新しいレスポンスを生成する**: Lambda@Edge はオリジンレスポンス本文を読み取ることができないため、既存のレスポンスを変更する代わりに、カスタムドメインでまったく新しい JSON レスポンスを生成します。
+  **CloudFront の動作に関連付ける**: Lambda@Edge 関数を設定して、`/.well-known/oauth-protected-resource`パスパターン専用にトリガーします。

  このソリューションを実装すると、OAuth で保護されたリソースエンドポイントは正しいカスタムドメインを返します。

  ```
  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"
  }
  ```
**注記**  
Lambda@Edge はこの問題の解決策を提供しますが、サポートが組み込まれていない AgentCore Gateway のカスタムドメインを実装するには、すべてのお客様にとって最適とは限らない、さらなる複雑さが必要です。カスタムドメインによる OAuth 検出のネイティブサポートが利用可能になるまで、このアプローチを回避策として検討してください。

## トラブルシューティング
<a name="gateway-custom-domains-troubleshooting"></a>

 **DNS 解決の問題**   
カスタムドメインが正しく解決されない場合:  
+ Route 53 ホストゾーンで A レコードが正しく設定されていることを確認します。
+ ドメインレジストラでドメインのネームサーバーが正しく設定されていることを確認します。
+ DNS 伝達に時間がかかる (場合によっては最大 48 時間)

 **SSL 証明書の問題**   
SSL 証明書エラーが発生した場合:  
+ ACM コンソールで証明書が発行され、アクティブであることを確認します。
+ 証明書が CloudFront ディストリビューションに正しく関連付けられていることを確認します。
+ 証明書が使用している正確なドメイン名をカバーしていることを確認します。

 **ゲートウェイ接続の問題**   
カスタムドメインがゲートウェイに接続しない場合:  
+ CloudFront ディストリビューションのオリジンドメインとパスが正しいことを確認します。
+ ゲートウェイエンドポイントに直接アクセス可能であることを確認する
+ CloudFront ディストリビューションログにエラーがないか確認する

## 結論
<a name="gateway-custom-domains-conclusion"></a>

Gateway エンドポイントのカスタムドメイン名を設定すると、アプリケーションのプロフェッショナルな外観が向上し、API エンドポイントを柔軟に管理できます。このガイドで説明されているステップに従うことで、CloudFront をリバースプロキシとして使用して、安全で信頼性の高いカスタムドメイン設定を作成できます。

Gateway の機能と機能の詳細については、[「Amazon Bedrock AgentCore Gateway: ツールやその他のリソースを Gateway に安全に接続する](gateway.md)」を参照してください。