이 페이지를 사용하여 Service Extensions를 통해 에이전트 게이트웨이의 승인을 IAP(Identity-Aware Proxy), Model Armor 및 기타 맞춤 승인 엔진에 위임하는 방법을 알아보세요.
승인 정책을 사용하면 에이전트 게이트웨이에서 게시한 엔드포인트를 통과하는 트래픽에 중앙 집중식 액세스 제어 및 거버넌스 정책을 적용할 수 있습니다. 이러한 정책을 사용하면 mTLS ID, 요청 및 응답 속성을 기반으로 액세스를 제어하여 트래픽을 관리하고 사용된 프로토콜별 속성 (예: MCP 서버)을 기반으로 맞춤설정할 수도 있습니다.
승인 정책은 정책 프로필을 사용하여 실행할 승인 유형을 결정합니다. HTTP 요청 헤더의 정보를 기반으로 트래픽을 허용하거나 거부하는 요청 기반 승인 정책(REQUEST_AUTHZ)을 사용할 수 있습니다. 또는 트래픽을 허용하거나 거부하기 위해 애플리케이션 페이로드를 더 자세히 검사해야 하는 경우 콘텐츠 기반 승인 정책(CONTENT_AUTHZ)을 사용할 수 있습니다.
승인 정책, 정책 프로필 및 사용 사례에 대해 자세히 알아보려면 승인 정책 개요를 참고하세요.
승인 확장 프로그램
경우에 따라 복잡한 승인 결정을 승인 정책을 사용하여 쉽게 표현할 수 없습니다. Agent Gateway를 사용하면 승인 확장 프로그램으로 승인 정책을 구성하여 승인 결정을 맞춤 승인 엔진에 위임할 수 있습니다.
승인 확장 프로그램을 사용하면 에이전트 게이트웨이 배포를 통과하는 요청을 가로채고 평가할 수 있습니다. 목적지로 계속 이동하기 전에 트래픽을 검사, 수정 또는 차단할 수 있도록 관리하는 외부 서비스에 실시간 gRPC 호출을 실행합니다.
확장 프로그램은 구성된 승인 정책에 따라 데이터를 검사합니다. 요청 기반 및 콘텐츠 기반 승인 정책에 대해 승인 확장 프로그램을 별도로 구성하거나 포괄적인 보안을 위해 둘 다 사용할 수 있습니다.
시작하기 전에
시작하기 전에 다음 요구사항을 충족하는지 확인하세요.
에이전트 게이트웨이가 배포됩니다. 에이전트 게이트웨이 구성을 참고하세요.
게이트웨이에 승인 정책을 연결하려면 배포된 에이전트 게이트웨이 리소스에 대한
agentGateway.useIAM 권한이 있어야 합니다.
확장 프로그램으로 승인 정책 구성
이 섹션에서는 승인 및 콘텐츠 보안 결정을 Identity-Aware Proxy, Model Armor, 기타 맞춤 서비스에 위임하는 승인 정책을 구성하는 방법을 보여줍니다.
IAP에 승인 위임
승인 정책의 액세스 결정을 IAP에 위임하도록 요청 승인 확장 프로그램을 구성할 수 있습니다.
다음 예시에서는 에이전트 게이트웨이 인스턴스의 승인 정책을 사용하여 승인 확장 프로그램을 구성하는 방법을 보여줍니다.
콘솔
Google Cloud 콘솔을 사용하여 에이전트 게이트웨이에 IAP를 사용 설정하려면 다음 단계를 따르세요.
- 에이전트 및 도구에 필요한 IAM 이그레스 정책을 만듭니다. 자세한 내용은 IAM 에이전트 정책 만들기를 참고하세요.
에이전트-애니웨어 (이그레스) 모드에서 에이전트 게이트웨이 구성을 참고하여 에이전트 게이트웨이를 만드는 동안(액세스 승인 매개변수 사용) IAP를 사용 설정하세요.
IAP를 사용하려면 에이전트가 게이트웨이에 바인드된 에이전트 레지스트리 리소스에 등록되어 있어야 합니다.
gcloud
IAP를 가리키도록 승인 확장 프로그램을 구성합니다.
YAML 파일에 확장 프로그램을 정의합니다. 제공된 샘플 값을 사용합니다.
cat >iap-request-authz-extension.yaml <<EOF name: my-iap-request-authz-ext service: iap.googleapis.com failOpen: true EOF승인 정책을 적용하지 않고 테스트하기 위해 테스트 실행 감사 전용 모드로 확장 프로그램을 배포하려면
DRY_RUN필드를 지정하면 됩니다. 이를 통해 정책을 확인하고 구성 오류로 인한 트래픽 중단 위험을 최소화할 수 있습니다.cat >iap-request-authz-extension.yaml <<EOF name: my-iap-request-authz-ext service: iap.googleapis.com failOpen: true metadata: ' iamEnforcementMode: DRY_RUN ' EOF승인 확장 프로그램을 가져옵니다. 다음 샘플 값과 함께
gcloud beta service-extensions authz-extensions import명령어를 사용합니다.gcloud beta service-extensions authz-extensions import my-iap-request-authz-ext \ --source=iap-request-authz-extension.yaml \ --location=LOCATION
동일한 프로젝트에서 결정을 확장 프로그램에 위임하는 승인 정책을 구성합니다.
my-iap-authz-request-ext확장 프로그램을 게이트웨이와 연결하는 승인 정책을 정의합니다. 제공된 샘플 값을 사용합니다.cat >iap-request-authz-policy.yaml <<EOF name: my-iap-request-authz-policy target: resources: - "projects/PROJECT_ID/locations/LOCATION/agentGateways/AGENT_GATEWAY_NAME" policyProfile: REQUEST_AUTHZ action: CUSTOM customProvider: authzExtension: resources: - "projects/PROJECT_ID/locations/LOCATION/authzExtensions/my-iap-request-authz-ext" EOF여기서
PROJECT_ID를 프로젝트 ID로 바꿉니다.승인 정책을 프로젝트로 가져옵니다. 다음 샘플 값과 함께
gcloud beta network-security authz-policies import명령어를 사용합니다.gcloud beta network-security authz-policies import my-iap-request-authz-policy \ --source=iap-request-authz-policy.yaml \ --location=LOCATION
Model Armor에 승인 위임
승인 정책의 콘텐츠 보안 결정을 Model Armor에 위임하도록 승인 확장 프로그램을 구성할 수 있습니다.
다음 예시에서는 에이전트 게이트웨이의 승인 정책을 사용하여 이러한 승인 확장 프로그램을 구성하는 방법을 보여줍니다.
콘솔
Google Cloud 콘솔을 사용하여 에이전트 게이트웨이의 Model Armor를 사용 설정하려면 다음 단계를 수행하세요.
필요한 Model Armor 템플릿을 만듭니다.
에이전트 게이트웨이를 만드는 동안(모델 아머 사용 설정 체크박스를 사용하여) 모델 아머를 사용 설정하려면 에이전트 게이트웨이 구성을 참고하세요. Model Armor 템플릿은 Client-to-Agent 모드와 Agent-to-Anywhere 모드 모두에서 지원됩니다.
Model Armor 템플릿이 게이트웨이와 다른 프로젝트에 있는 경우 에이전트 게이트웨이 서비스 계정에 필요한 역할을 수동으로 부여해야 합니다. 서비스 계정의 형식은
service-PROJECT_NUMBER@gcp-sa-dep.iam.gserviceaccount.com입니다. 여기서 PROJECT_NUMBER는 게이트웨이를 만든 프로젝트의 프로젝트 번호입니다.다음 역할을 부여합니다.
- 게이트웨이가 포함된 프로젝트의
roles/modelarmor.calloutUser및roles/serviceusage.serviceUsageConsumer역할 - Model Armor 템플릿이 포함된 프로젝트의
roles/modelarmor.user역할
이 단계를 완료하려면 gcloud CLI를 사용해야 합니다.
gcloud projects add-iam-policy-binding GATEWAY_PROJECT_ID \ --member=serviceAccount:service-GATEWAY_PROJECT_NUMBER@gcp-sa-dep.iam.gserviceaccount.com \ --role=roles/modelarmor.calloutUser gcloud projects add-iam-policy-binding GATEWAY_PROJECT_ID \ --member=serviceAccount:service-GATEWAY_PROJECT_NUMBER@gcp-sa-dep.iam.gserviceaccount.com \ --role=roles/serviceusage.serviceUsageConsumer gcloud projects add-iam-policy-binding MODEL_ARMOR_PROJECT_ID \ --member=serviceAccount:service-GATEWAY_PROJECT_NUMBER@gcp-sa-dep.iam.gserviceaccount.com \ --role=roles/modelarmor.user
다음을 바꿉니다.
GATEWAY_PROJECT_ID: 게이트웨이를 만든 프로젝트의 프로젝트 ID입니다.GATEWAY_PROJECT_NUMBER: 게이트웨이를 만든 프로젝트의 프로젝트 번호입니다.MODEL_ARMOR_PROJECT_ID: Model Armor 템플릿이 포함된 프로젝트의 프로젝트 ID입니다.
Agent Runtime에 게이트웨이를 사용하는 경우 에이전트 게이트웨이를 통해 Agent Runtime 트래픽 라우팅에 설명된 대로 추론 엔진 서비스 에이전트에도 이러한 권한이 필요합니다.
- 게이트웨이가 포함된 프로젝트의
gcloud
필요한 Model Armor 템플릿을 만듭니다.
Model Armor 템플릿이 게이트웨이와 다른 프로젝트에 있는 경우 에이전트 게이트웨이 서비스 계정에 필요한 역할을 수동으로 부여해야 합니다. 서비스 계정은
service-PROJECT_NUMBER@gcp-sa-dep.iam.gserviceaccount.com형식입니다. 여기서 PROJECT_NUMBER는 게이트웨이를 만든 프로젝트의 프로젝트 번호입니다.다음 역할을 부여합니다.
- 게이트웨이가 포함된 프로젝트의
roles/modelarmor.calloutUser및roles/serviceusage.serviceUsageConsumer역할 - Model Armor 템플릿이 포함된 프로젝트의
roles/modelarmor.user역할
gcloud projects add-iam-policy-binding GATEWAY_PROJECT_ID \ --member=serviceAccount:service-GATEWAY_PROJECT_NUMBER@gcp-sa-dep.iam.gserviceaccount.com \ --role=roles/modelarmor.calloutUser gcloud projects add-iam-policy-binding GATEWAY_PROJECT_ID \ --member=serviceAccount:service-GATEWAY_PROJECT_NUMBER@gcp-sa-dep.iam.gserviceaccount.com \ --role=roles/serviceusage.serviceUsageConsumer gcloud projects add-iam-policy-binding MODEL_ARMOR_PROJECT_ID \ --member=serviceAccount:service-GATEWAY_PROJECT_NUMBER@gcp-sa-dep.iam.gserviceaccount.com \ --role=roles/modelarmor.user
다음을 바꿉니다.
GATEWAY_PROJECT_ID: 게이트웨이를 만든 프로젝트의 프로젝트 ID입니다.GATEWAY_PROJECT_NUMBER: 게이트웨이를 만든 프로젝트의 프로젝트 번호입니다.MODEL_ARMOR_PROJECT_ID: Model Armor 템플릿이 포함된 프로젝트의 프로젝트 ID입니다.
- 게이트웨이가 포함된 프로젝트의
Model Armor를 가리키도록 승인 확장 프로그램을 구성합니다.
YAML 파일에 확장 프로그램을 정의합니다. 제공된 샘플 값을 사용합니다.
cat >ma-content-authz-extension.yaml <<EOF name: my-ma-content-authz-ext service: modelarmor.LOCATION.rep.googleapis.com metadata: model_armor_settings: '[ { "response_template_id": "projects/MODEL_ARMOR_PROJECT_ID/locations/LOCATION/templates/TEMPLATE_ID", "request_template_id": "projects/MODEL_ARMOR_PROJECT_ID/locations/LOCATION/templates/TEMPLATE_ID" } ]' failOpen: true timeout: 1s EOF승인 확장 프로그램을 가져옵니다. 다음 샘플 값과 함께
gcloud beta service-extensions authz-extensions import명령어를 사용합니다.gcloud beta service-extensions authz-extensions import my-ma-content-authz-ext \ --source=ma-content-authz-extension.yaml \ --location=LOCATION
확장 프로그램으로 승인 정책을 구성합니다.
확장 프로그램
my-ma-content-authz-ext을 에이전트 게이트웨이와 연결하는 승인 정책을 정의합니다.cat >ma-content-authz-policy.yaml <<EOF name: my-ma-content-authz-policy target: resources: - "projects/PROJECT_ID/locations/LOCATION/gateways/AGENT_GATEWAY_NAME" policyProfile: CONTENT_AUTHZ action: CUSTOM customProvider: authzExtension: resources: - "projects/PROJECT_ID/locations/LOCATION/authzExtensions/my-ma-content-authz-ext" EOF콘텐츠 승인 정책의 경우
policyProfile값이CONTENT_AUTHZ으로 설정됩니다. 이 값은 맞춤 정책 제공자가 본문 처리를 포함한 요청 및 응답 트래픽을 처리함을 나타냅니다.승인 정책을 프로젝트로 가져옵니다. 다음 샘플 값과 함께
gcloud beta network-security authz-policies import명령어를 사용합니다.gcloud beta network-security authz-policies import my-ma-content-authz-policy \ --source=ma-content-authz-policy.yaml \ --location=LOCATION
맞춤 승인 확장 프로그램에 승인 위임
결정을 맞춤 서비스에 위임하도록 맞춤 승인 확장 프로그램을 구성할 수 있습니다. 이러한 맞춤 확장 프로그램은 정규화된 도메인 이름 (FQDN)만 타겟팅할 수 있습니다.
FQDN 타겟을 사용하는 경우 확장 프로그램은 TLS 암호화가 적용된 HTTP2 프로토콜을 사용하여 포트 443의 엔드포인트와 통신합니다. 하지만 확장 프로그램은 서버 인증서를 검증하지 않습니다. 따라서 보안을 강화하려면 확인된 엔드포인트가 VPC 네트워크 내에 있어야 합니다. 또한 에이전트 게이트웨이 프로젝트와 VPC 네트워크 간에 DNS 피어링이 설정되어 있는지 확인합니다.
mycustomauthz.internal.net과 같은 특정 FQDN에 대한 승인 정책으로 승인 확장 프로그램을 구성하려면 다음 예와 같이 확장 프로그램 YAML 파일에서service의 값으로 지정합니다. 이 예에서는ext_authz프로토콜을 구현하는 서버가 VPC 네트워크에 배포되어 있다고 가정합니다.cat >custom-authz-extension.yaml <<EOF name: my-custom-authz-ext service: mycustomauthz.internal.net failOpen: true wireFormat: EXT_AUTHZ_GRPC EOF커스텀 서비스를 가리키는 승인 확장 프로그램을 만듭니다.
gcloud beta service-extensions authz-extensions import custom-authz-extension
--source=custom-authz-extension.yaml
--location=LOCATION확장 프로그램을 만든 후 승인 확장 프로그램에 결정을 위임하는
CUSTOM승인 정책을 구성합니다.$ cat >authz-policy.yaml <<EOF name: authz-with-extension target: resources: - "projects/PROJECT_ID/locations/LOCATION/agentGateways/AGENT_GATEWAY_NAME" policyProfile: REQUEST_AUTHZ action: CUSTOM customProvider: authzExtension: resources: - projects/PROJECT_ID/locations/LOCATION/authzExtensions/custom-authz-extension EOF승인 정책을 만듭니다.
gcloud beta network-security authz-policies import authz-policy-with-extension \ --source=authz-policy.yaml \ --location=LOCATION
이 예에 표시된 대로 REQUEST_AUTHZ 프로필을 사용하여 승인 확장 프로그램이 승인 정책과 연결되면 게이트웨이는 요청 헤더가 도착할 때만 확장 프로그램을 호출합니다. 요청 본문, 응답 헤더, 응답 본문은 승인 확장 프로그램에 표시되지 않습니다.
IAP 승인과 Model Armor 보호 장치 결합
포괄적인 보안을 위해 REQUEST_AUTHZ 정책 프로필이 있는 맞춤 승인 정책과 CONTENT_AUTHZ 정책 프로필이 있는 또 다른 맞춤 승인 정책을 설정하는 것이 좋습니다.
다음 예에서는 IAP를 중앙 집중식 요청 승인 시스템으로 사용하고 AI 가드레일에는 Model Armor를 사용합니다. 이전 예에 표시된 것처럼 서비스 확장 프로그램으로 각각 교체하여 자체 맞춤 솔루션을 사용할 수 있습니다.
IAP에 위임하는
REQUEST_AUTHZ승인 확장 프로그램과 확장 프로그램을 가리키는 승인 정책을 구성합니다.승인 확장 프로그램을 정의합니다.
$ cat >iap-extension.yaml <<EOF name: iap-extension service: iap.googleapis.com failOpen: true EOF승인 확장 프로그램을 만듭니다.
gcloud beta service-extensions authz-extensions import iap-extension \ --source=iap-extension.yaml \ --location=LOCATION
LOCATION을 확장 프로그램의 리전으로 바꿉니다.확장 프로그램에 위임하는
REQUEST_AUTHZ승인 정책을 구성합니다.$ cat >authz-policy-request-authz.yaml <<EOF name: authz-iap target: resources: - "projects/PROJECT_ID/locations/LOCATION/agentGateways/AGENT_GATEWAY_NAME" policyProfile: REQUEST_AUTHZ action: CUSTOM customProvider: authzExtension: resources: - "projects/PROJECT_ID/locations/LOCATION/authzExtensions/iap-extension" EOF다음을 바꿉니다.
PROJECT_ID: 프로젝트 ID입니다.LOCATION: 리소스의 위치입니다.AGENT_GATEWAY_NAME: 에이전트 게이트웨이의 이름입니다.
승인 정책을 만듭니다.
gcloud beta network-security authz-policies import authz-iap \ --source=authz-policy-request-authz.yaml \ --location=LOCATION
Model Armor에 위임하는
CONTENT_AUTHZ승인 확장 프로그램과 확장 프로그램을 가리키는 승인 정책을 구성합니다.확장 프로그램을 정의합니다.
$ cat >ma-extension-file.yaml <<EOF name: ma-extension service: modelarmor.LOCATION.rep.googleapis.com metadata: model_armor_settings: '[ { "response_template_id": "projects/MODEL_ARMOR_PROJECT_ID/locations/LOCATION/templates/RESPONSE_TEMPLATE_ID", "request_template_id": "projects/MODEL_ARMOR_PROJECT_ID/locations/LOCATION/templates/REQUEST_TEMPLATE_ID" } ]' failOpen: true timeout: 1s EOF다음을 바꿉니다.
LOCATION: Model Armor 템플릿이 있는 리전입니다.MODEL_ARMOR_PROJECT_ID: Model Armor 템플릿이 포함된 프로젝트 ID입니다.RESPONSE_TEMPLATE_ID: 응답 템플릿의 ID입니다.REQUEST_TEMPLATE_ID: 요청 템플릿의 ID입니다.
승인 확장 프로그램을 만듭니다.
gcloud beta service-extensions authz-extensions import ma-extension \ --source=ma-extension-file.yaml \ --location=LOCATION
확장 프로그램에 위임하는
CONTENT_AUTHZ승인 정책을 구성합니다.$ cat >authz-policy-content-authz.yaml <<EOF name: authz-ma target: resources: - "projects/PROJECT_ID/locations/LOCATION/agentGateways/AGENT_GATEWAY_NAME" policyProfile: CONTENT_AUTHZ action: CUSTOM customProvider: authzExtension: resources: - "projects/PROJECT_ID/locations/LOCATION/authzExtensions/ma-extension" EOF승인 정책을 만듭니다.
gcloud beta network-security authz-policies import ma-authz-policy \ --source=authz-policy-content-authz.yaml \ --location=LOCATION
승인 확장 프로그램이 CONTENT_AUTHZ 프로필과 연결되면 요청 및 응답 헤더, 본문, 트레일러를 포함한 모든 ext_proc 이벤트를 수신합니다. ext_proc 기반 승인 확장 프로그램이 요청 시간 승인과 콘텐츠 기반 승인을 모두 처리할 수 있는 경우 CONTENT_AUTHZ 정책 프로필을 사용하여 단일 CUSTOM 승인 정책을 구성하는 것이 좋습니다. 이 정책은 다용도 승인 확장 프로그램을 가리켜야 합니다. 이 접근 방식을 사용하면 단일 확장 프로그램과 ext_proc 연결을 통해 두 가지 유형의 승인을 모두 사용할 수 있으므로 REQUEST_AUTHZ 및 CONTENT_AUTHZ 프로필에 별도의 확장 프로그램을 사용하는 경우에 비해 지연 시간을 개선할 수 있습니다.
MCP 프로토콜 속성에 기반한 승인
에이전트 게이트웨이는 요청에서 MCP 프로토콜 페이로드를 파싱하고 추출된 속성을 승인 정책에 사용할 수 있도록 합니다.
특정 도구의 이름과 같은 MCP 메서드 매개변수를 기반으로 액세스를 제한할 수 있습니다. 이 섹션에서는 ALLOW 정책과 DENY 정책의 두 가지 예를 보여줍니다.
승인 정책을 구성합니다.
ALLOW정책 예시이 예시에서는 MCP 서버 및 기본 프로토콜 기능의 특정 도구 세트에 대한 액세스를 허용하지만 프롬프트 및 리소스에 대한 액세스는 허용하지 않습니다.
ALLOW정책을 작성할 때는 초기화, 로깅, 완료, 알림, 핑과 같은 액세스 비특정 MCP RPC가 계속 작동하도록baseProtocolMethodsOption: MATCH_BASE_PROTOCOL_METHODS를 지정해야 합니다. 그렇지 않으면 MCP 세션을 설정할 수 없습니다.$ cat >authz-policy-restrict-tools.yaml <<EOF name: my-authz-policy-restrict-tools target: resources: - "projects/PROJECT_ID/locations/LOCATION/agentGateways/AGENT_GATEWAY_NAME" policyProfile: REQUEST_AUTHZ httpRules: - to: operations: - mcp: baseProtocolMethodsOption: MATCH_BASE_PROTOCOL_METHODS methods: - name: "tools/list" - name: "tools/call" params: - exact: "get_weather" - exact: "get_location" action: ALLOW EOFDENY정책 예시이 예시에서는 에이전트 게이트웨이 뒤에 있는 MCP 서버에 대한 모든 프롬프트/ 메서드 액세스를 허용하지 않습니다.
$ cat >authz-policy-disallow-prompts.yaml <<EOF name: my-authz-policy-disallow-prompts target: resources: - "projects/PROJECT_ID/locations/LOCATION/agentGateways/AGENT_GATEWAY_NAME" policyProfile: REQUEST_AUTHZ httpRules: - to: operations: - mcp: methods: - name: "prompts" action: DENY EOF승인 정책을 만듭니다.
gcloud beta network-security authz-policies import AUTHZ_POLICY_NAME \ --source=AUTH_POLICY_YAML_FILE_PATH \ --location=LOCATION
다음을 바꿉니다.
AUTHZ_POLICY_NAME: 승인 정책 이름입니다.AUTH_POLICY_YAML_FILE_PATH: 승인 정책 YAML 파일의 경로입니다.LOCATION: 리소스의 위치입니다.
제한사항
승인 정책을 사용할 때는 다음 제한사항이 적용됩니다.
- 정책 프로필과 관계없이 에이전트 게이트웨이당 최대 4개의 맞춤 승인 정책을 구성할 수 있습니다.
CONTENT_AUTHZ프로필과 함께 맞춤 승인 확장 프로그램을 사용하는 경우 본문 이벤트에ext_proc프로토콜과FULL_DUPLEX_STREAMED모드를 지원해야 합니다.- 동일한 프로필을 사용하는 맞춤 승인 정책을 여러 개 구성하는 경우 실행 순서가 보장되지 않습니다.
또한 승인 확장 프로그램의 제한사항에 대한 자세한 내용은 다음 섹션을 참고하세요.
모든 확장 프로그램에 적용되는 제한사항은 확장 프로그램의 제한사항을 참고하세요.
콜아웃에 적용되는 제한사항은 콜아웃 제한사항을 참고하세요.