MCP API 대상 열기 Smithy 대상 API Gateway Lambda 프라이빗 자격 증명 공급자 제한 사항 및 고려 사항

게이트웨이 대상에 대한 Amazon Bedrock AgentCore 게이트웨이 VPC 송신 구성

AgentCore Gateway 서비스는 애플리케이션에 대해 안전하고 제어된 송신 트래픽 관리를 제공하므로 Virtual Private Cloud(VPC) 내의 리소스와 원활하게 통신할 수 있습니다. 이 문서에서는 외부 트래픽이 AgentCore Gateway를 통해 VPC 리소스에 도달하는 방법을 간략하게 설명합니다. 지원되는 게이트웨이 대상 유형( AgentCore 런타임을 통한 Lambda, API Gateway 및 MCP 서버), 구성 요구 사항 및 각 대상 유형에 지원되는 인증 방법에 대해 알아봅니다. 이 가이드에서는 네트워크 격리를 유지하고 아키텍처 전체에서 최소 권한 원칙을 준수하면서 적절한 송신 트래픽 흐름을 활성화하는 데 필요한 보안 고려 사항, 라우팅 메커니즘 및 모범 사례를 다룹니다.

MCP

AgentCore Gateway는 모델 컨텍스트 프로토콜(MCP) 서버를 대상 엔드포인트로 지원하여 다양한 고객 요구 사항을 충족하는 유연한 배포 옵션을 제공합니다. MCP 서버는 인프라 요구 사항 및 보안 요구 사항에 따라 여러 가지 방법으로 구성할 수 있습니다.

MCP 대상은 AgentCore에서 호스팅되지 않거나 AgentCore 런타임 또는 게이트웨이에서 호스팅되는 두 가지 유형일 수 있습니다. 아래에서 둘 다 설명합니다.

AgentCore에서 호스팅되지 않는 MCPs

AgentCore Gateway는 Amazon VPC Lattice로 구동되는 프라이빗 엔드포인트를 사용하여 VPC 내에서 실행되는 자체 호스팅 MCP 서버에 연결할 수 있도록 지원합니다. 퍼블릭 인터넷privateEndpoint에 노출하지 않고 트래픽을 MCP 서버로 비공개로 라우팅하도록 게이트웨이 대상에서를 구성할 수 있습니다.

다음 예제에서는 관리형 Lattice를 사용하여 프라이빗 MCP 서버 대상을 생성합니다.


{
  "name": "my-private-mcp-target",
  "privateEndpoint": {
    "managedVpcResource": {
      "vpcIdentifier": "vpc-0abc123def456",
      "subnetIds": ["subnet-0abc123", "subnet-0def456"],
      "endpointIpAddressType": "IPV4",
      "securityGroupIds": ["sg-0abc123def"]
    }
  },
  "targetConfiguration": {
    "mcp": {
      "mcpServer": {
        "endpoint": "https://my-mcp-server.internal.example.com/mcp"
      }
    }
  }
}

VPC 엔드포인트 또는 내부 로드 밸런서와 같은 중간 구성 요소를 통해 트래픽을 라우팅하려면 routingDomain를 지정할 수 있습니다. 자세한 내용은 중간 도메인을 통해 트래픽 라우팅을 참조하세요.

MCP 서버가 프라이빗 인증 기관에서 발급한 TLS 인증서를 사용하는 경우 그 앞에 퍼블릭 ACM 인증서가 있는 내부 Application Load Balancer를 배치할 수 있습니다. 자세한 내용은 프라이빗 인증서에 대한 해결 방법: ALB를 참조하세요.

자체 관리형 Lattice, 교차 계정 설정 및 고급 구성은 VPC Lattice를 사용하여 VPC의 프라이빗 리소스에 연결을 참조하세요.

AgentCore 런타임 또는 게이트웨이

AgentCore 런타임은 관리형 인프라 접근 방식을 통해 VPC 내의 리소스와 통신하기 위한 기본 지원을 제공합니다. AgentCore Gateway와 AgentCore 런타임 간의 모든 통신은 AWS 백본에 유지되므로 데이터가 퍼블릭 인터넷을 통과하지 않습니다(중국 데이터 센터에 대한 리전 간 호출 제외). 자세한 내용은 Amazon VPC FAQ의 연결 섹션을 참조하세요. FAQs AgentCore 런타임을 VPC에 연결하는 방법에 대한 자세한 설정 지침은 Configure Amazon Bedrock AgentCore Runtime and tools for VPC를 참조하세요.

AgentCore Gateway에서 AgentCore 런타임으로의 아웃바운드 권한 부여를 위해 두 가지 인증 방법이 지원됩니다. 권한 부여 없음(프로덕션 사용에 권장되지 않음)과 클라이언트 자격 증명 부여가 있는 OAuth(machine-to-machine 인증)입니다. 권한 부여가 구성되지 않은 경우 AgentCore Gateway에서 AgentCore 런타임으로의 요청에는 인증 토큰이 없습니다. 이 아키텍처는 보안 격리를 유지하면서 원활한 연결 경로를 제공합니다. 보안 모범 사례로 AgentCore 런타임과 AgentCore Gateway 모두에 대해 제한적인 인증 및 권한 부여 권한을 구성하여 특정 사용 사례에 필요한 리소스 및 작업으로만 액세스를 제한합니다. AgentCore Gateway에서 AgentCore 런타임의 송신 및 수신에 사용하도록 OAuth 자격 증명을 구성하려면 다음 문서를 사용합니다.

AgentCore Gateway가 프라이빗 링크 엔드포인트에 연결할 수 없음을 보여주는 아키텍처 다이어그램입니다.

AgentCore 런타임을 대상으로 사용하는 CreateGatewayTarget 예제

다음 예제에서는 AgentCore 런타임을 사용하여 게이트웨이 대상을 생성하는 방법을 보여줍니다.


POST /gateways/gatewayIdentifier/targets/ HTTP/1.1
Content-type: application/json

    {
    "clientToken": "string",
    "credentialProviderConfigurations": [
      {
         "credentialProvider": {
            "oauthCredentialProvider": {
               "providerArn": "string",
               "scopes": [ "string" ],
               ...
            }
         },
         "credentialProviderType": "OAUTH"
      }
    ],
    "description": "string",
    "metadataConfiguration": {
      "allowedQueryParameters": [ "string" ],
      "allowedRequestHeaders": [ "string" ],
      "allowedResponseHeaders": [ "string" ]
    },
    "name": "string",
    "targetConfiguration": {
      "mcp": {
         "mcpServer": {
            "endpoint": "https://bedrock-agentcore.<region>.amazonaws.com/runtimes/<runtime-id>/invocations?qualifier=DEFAULT&accountId=<account-id>"
         }
      }
    }
}

참고

불필요한 추가 네트워크 홉을 방지하기 privateEndpoint 위해에서 VPC 엔드포인트(VPCE) URL을 사용하지 마세요. 대신 트래픽이 AWS 백본에 남아 있는 직접 AgentCore 런타임 엔드포인트를 사용합니다.

API 대상 열기

Open API Target을 통한 API Gateway 엔드포인트

API Gateway를 대상으로 직접 추가할 수 없는 경우 항상 리소스를 OpenAPI 사양으로 내보내고 사양을 AgentCore Gateway로 OpenAPI 대상으로 가져올 수 있습니다.

API Gateway에 프라이빗 REST APIs 있는 경우 API Gateway의 프라이빗 REST APIs 지침을 따릅니다.

기타 엔드포인트

구성을 사용하여 VPC 내의 프라이빗 엔드포인트에 도달하도록 Open API 대상을 구성할 수 있습니다privateEndpoint. AgentCore Gateway는 Amazon VPC Lattice를 사용하여 엔드포인트를 퍼블릭 인터넷에 노출하지 않고 엔드포인트에 대한 프라이빗 연결을 설정합니다.

다음 예시에서는 관리형 Lattice를 사용하여 프라이빗 OpenAPI 대상을 생성합니다.


{
  "name": "my-private-openapi-target",
  "privateEndpoint": {
    "managedVpcResource": {
      "vpcIdentifier": "vpc-0abc123def456",
      "subnetIds": ["subnet-0abc123", "subnet-0def456"],
      "endpointIpAddressType": "IPV4",
      "securityGroupIds": ["sg-0abc123def"]
    }
  },
  "targetConfiguration": {
    "mcp": {
      "openApiSchema": {
        "inlinePayload": "<your OpenAPI spec JSON with server URL pointing to your private endpoint>"
      }
    }
  }
}

엔드포인트가 프라이빗 인증 기관에서 발급한 TLS 인증서를 사용하는 경우 그 앞에 퍼블릭 ACM 인증서가 있는 내부 Application Load Balancer를 배치할 수 있습니다. 자세한 내용은 프라이빗 인증서에 대한 해결 방법: ALB를 참조하세요.

자체 관리형 Lattice, 교차 계정 설정 및 고급 구성은 VPC Lattice를 사용하여 VPC의 프라이빗 리소스에 연결을 참조하세요.

참고

privateEndpoint 구성은 OpenAPI 스키마의 단일 도메인에 적용됩니다. 스키마가 도메인이 다른 여러 서버 엔드포인트를 참조하는 경우 AWS 지원 사례를 열어에 대한 지원을 요청합니다privateEndpointOverrides.

Smithy 대상

프라이빗 엔드포인트(privateEndpoint) 구성은 현재 Smithy 대상에 대해 지원되지 않습니다. Smithy 대상에 프라이빗 연결이 필요한 경우 AWS 지원 사례를 열어 지원을 요청합니다.

API Gateway

AgentCore Gateway는 API Gateway를 대상 유형으로 지원하며, 이는 VPC 리소스에 액세스하기 위한 중간 계층 역할을 할 수 있습니다. AgentCore Gateway는 리전 엔드포인트로 구성된 REST API Gateway만 지원합니다. 게이트웨이로부터의 직접 VPC 통신은 현재 사용할 수 없지만(이 기능은 향후 릴리스 예정), 게이트웨이는 AWS 백본을 통해 API Gateway와 통신하여 트래픽이 퍼블릭 인터넷을 통과하지 않도록 합니다(중국 데이터 센터에 대한 리전 간 호출 제외). 그런 다음 API Gateway는 VPC 링크를 사용하여 리소스와 통신하여 AgentCore Gateway가 네트워크 격리를 유지하면서 내부 서비스에 도달할 수 있는 보안 경로를 생성할 수 있습니다.

보안 모범 사례를 구현하려면 인바운드 트래픽을 AgentCore Gateway 서비스 보안 주체 또는 구성된 API 키로만 제한하도록 API Gateway를 구성하여 다른 소스의 무단 액세스를 방지합니다. AgentCore Gateway에서 API Gateway로의 아웃바운드 권한 부여의 경우 IAM 기반 인증(게이트웨이 서비스 역할을 사용하여 AWS 서명 버전 4로 인증) 및 API 키 인증( AgentCore Gateway에서 관리)의 두 가지 인증 방법만 지원됩니다. API Gateway 대상에는 OAuth 기반 권한 부여 및 교차 계정 API Gateway가 지원되지 않습니다. 이에 대해 Open API Target을 통해 API Gateway 엔드포인트를 사용하세요. 광범위한 API Gateway 액세스 권한을 부여하지 않고 필요한 특정 API Gateway 엔드포인트만 호출하도록 AgentCore Gateway 실행 역할 권한을 제한하여 게이트웨이가 의도하지 않은 API 리소스와 상호 작용하지 않도록 하고 아키텍처 전체에서 최소 권한 원칙을 유지합니다.

대상으로서 Amazon API Gateway REST API 단계

IAM Auth를 사용한 API Gateway 통합에 대한 권한

AgentCore Gateway로 잠긴 API Gateway 리소스 정책

다음 리소스 정책은 AgentCore Gateway에 대한 API Gateway 액세스를 제한합니다.


{
"Version": "2012-10-17",
    "Statement": [
      {
        "Effect": "Allow",
        "Principal": {
          "Service": "bedrock-agentcore.amazonaws.com"
        },
        "Action": "execute-api:Invoke",
        "Resource": [
          "arn:aws:execute-api:us-west-2:111122223333:rest-api-id/api-stage/*/*"
        ],
        "Condition": {
          "ArnEquals": {
            "aws:SourceArn": "arn:aws:bedrock-agentcore:us-west-2:111122223333:gateway/my-gateway-d4jrgkaske"
          }
        }
      }
    ]
}

AgentCore 게이트웨이 실행 역할 정책

다음 정책은 게이트웨이에 API Gateway를 호출할 수 있는 권한을 부여합니다.


{
"Version": "2012-10-17",
    "Statement": [
      {
        "Effect": "Allow",
        "Action": [
          "execute-api:Invoke"
        ],
        "Resource": [
          "arn:aws:execute-api:us-west-2:111122223333:abcd123/prod/*/*"
        ]
      }
    ]
}

AgentCore Gateway 실행 역할 신뢰 정책

다음 신뢰 정책은 AgentCore Gateway가 실행 역할을 수임하도록 허용합니다.


{
"Version": "2012-10-17",
    "Statement": [
      {
        "Effect": "Allow",
        "Principal": {
          "Service": "bedrock-agentcore.amazonaws.com"
        },
        "Action": "sts:AssumeRole",
        "Condition": {
          "StringEquals": {
            "aws:SourceAccount": "111122223333"
          },
          "ArnLike": {
            "aws:SourceArn": "arn:aws:bedrock-agentcore:us-west-2:111122223333:gateway/*"
          }
        }
      }
    ]
}

API Gateway의 프라이빗 REST API

프라이빗 엔드포인트가 있는 API Gateway 대상은 기본적으로 지원되지 않습니다. 그러나 프라이빗 API Gateway를 OpenAPI 스키마로 내보내고 로 구성된 해당 스키마와 함께 Open API 대상을 사용할 수 있습니다privateEndpoint. routingDomain를 API Gateway VPC 엔드포인트(VPCE) DNS 이름으로 설정하고 OpenAPI 스키마 서버 URL이 퍼블릭 TLS 인증서와 일치하는 도메인을 사용하는지 확인합니다.


{
  "name": "my-private-apigw-target",
  "privateEndpoint": {
    "managedVpcResource": {
      "vpcIdentifier": "vpc-0123456789abcdef0",
      "subnetIds": ["subnet-0123456789abcdef0", "subnet-0abcdef1234567890"],
      "endpointIpAddressType": "IPV4",
      "routingDomain": "<vpce-id>.execute-api.<region>.vpce.amazonaws.com"
    }
  },
  "targetConfiguration": {
    "mcp": {
      "openApiSchema": {
        "inlinePayload": "<OpenAPI spec JSON with server URL matching the public certificate domain for your API Gateway, for example https://<api-id>.execute-api.<region>.amazonaws.com>"
      }
    }
  }
}

프라이빗 엔드포인트 구성에 대한 자세한 내용은 VPC Lattice를 사용하여 VPC의 프라이빗 리소스에 연결을 참조하세요.

Lambda

AgentCore Gateway는 Lambda 대상을 대상 유형 중 하나로 지원하므로 VPC 내의 리소스와 통신할 수 있는 Lambda 함수를 원활하게 호출할 수 있습니다. 이 기능은 out-of-the-box 사용할 수 있으며 고객의 추가 구성이 필요하지 않습니다. 게이트웨이는 데이터베이스, APIs 또는 기타 서비스와 같은 내부 리소스에 도달하기 위해 VPC 액세스 권한으로 구성된 Lambda 함수를 즉시 호출할 수 있습니다. 보안 모범 사례를 유지하려면 최소한의 권한으로 AgentCore Gateway 실행 역할을 구성하는 것이 좋습니다. 특히 광범위한 Lambda 실행 권한을 부여하는 대신 의도한 Lambda 함수만 호출하도록 제한하는 것이 좋습니다. 이 최소 권한 원칙은 게이트웨이 또는 동일한 역할을 사용하는 다른 호출자가 의도하지 않은 Lambda 함수를 실수로 호출하여 보안 공격 표면을 줄이고 AWS 환경 내에서 엄격한 액세스 제어를 유지할 수 없도록 합니다.

프라이빗 자격 증명 공급자

AgentCore는 이제 인바운드 JWT 권한 부여 및 아웃바운드 OAuth 자격 증명 공급자 모두에 대해 프라이빗 OAuth 자격 증명 공급자에 대한 연결을 지원합니다. 이를 통해 퍼블릭 인터넷에 노출되지 않고 VPC 내에서 실행되는 Keycloak, PingFederate 또는 기타 OIDC 호환 권한 부여 서버와 같은 자체 호스팅 IdPs를 사용할 수 있습니다.

자세한 구성 지침은 VPC의 프라이빗 자격 증명 공급자에 연결을 참조하세요.

또는 인바운드 인증에 인터셉터 Lambda 함수를 사용하고 아웃바운드 인증에 사용할 인터셉터 Lambda의 권한 부여 헤더를 재정의할 수 있습니다.

제한 사항 및 고려 사항

인바운드 권한 부여 필요: 게이트웨이에 인터셉터 Lambda가 구성되지 않은 한 로 구성된 게이트웨이 대상은를 인바운드 권한 부여자 유형NO_AUTH으로 사용할 수 privateEndpoint 없습니다.

교차 계정 연결 및 DNS TTL 구성과 관련된 추가 제한 사항은 VPC Lattice를 사용하여 VPC의 프라이빗 리소스에 연결의 제한 및 고려 사항을 참조하세요. VPC Lattice를 사용하여 VPC의 프라이빗 리소스에 연결

javascript가 브라우저에서 비활성화되거나 사용이 불가합니다.

AWS 설명서를 사용하려면 Javascript가 활성화되어야 합니다. 지침을 보려면 브라우저의 도움말 페이지를 참조하십시오.

문서 규칙

프라이빗 연결을 생성하려면 AWS PrivateLink 사용

VPC Lattice를 사용한 VPC 송신