Service Extensions로 승인 위임

이 페이지에서는 Service Extensions를 사용하여 Agent Gateway의 승인을 IAP(Identity-Aware Proxy), Model Armor, 기타 커스텀 승인 엔진에 위임하는 방법을 알아봅니다.

승인 정책 및 확장 프로그램

승인 정책을 사용하면 Agent Gateway에서 게시한 엔드포인트를 통과하는 트래픽에 중앙 집중식 액세스 제어 및 거버넌스 정책을 적용할 수 있습니다. 복잡한 액세스 제어, 콘텐츠 안전, 거버넌스 결정을 처리하기 위해 Agent Gateway를 사용하면 승인 및 콘텐츠 안전 결정을 원하는 지정된 승인 엔진에 위임할 수 있는 승인 확장 프로그램으로 승인 정책을 구성할 수 있습니다.

승인 확장 프로그램은 Agent Gateway 배포를 통과하는 요청을 가로채고 지정된 승인 서비스에 실시간 gRPC 호출을 수행합니다. 이렇게 하면 서비스가 트래픽을 대상으로 계속 전송하기 전에 검사, 수정 또는 차단할 수 있습니다. Identity-Aware Proxy, Model Armor, 시맨틱 거버넌스 정책과 같은 Google Cloud 서비스 또는 원하는 커스텀 승인 엔진에 승인을 위임할 수 있습니다.

승인 정책은 정책 프로필을 사용하여 승인 확장 프로그램으로 전송되는 트래픽 데이터 유형을 결정합니다.

  • 요청 기반 승인(REQUEST_AUTHZ): 애플리케이션 페이로드가 처리되기 전에 HTTP 요청 헤더를 평가합니다. 이 프로필은 본인 인증 및 액세스 제어(예: IAP(Identity-Aware Proxy)에 승인 위임)에 사용됩니다.
  • 콘텐츠 기반 승인(CONTENT_AUTHZ): 전체 HTTP 요청 및 응답 페이로드를 평가합니다. 이 프로필은 프롬프트 및 응답 안전을 위해 Model Armor에 위임하거나 자연어 제약 조건 시행을 위해 시맨틱 거버넌스 정책에 위임하는 등 심층 콘텐츠 검사 및 AI 안전에 사용됩니다.

커스텀 승인 엔진은 헤더 또는 전체 애플리케이션 페이로드를 검사하는지 여부에 따라 REQUEST_AUTHZ 또는 CONTENT_AUTHZ 확장 프로그램을 사용할 수 있습니다.

요청 기반 정책과 콘텐츠 기반 정책에 대해 승인 확장 프로그램을 별도로 구성하거나 게이트웨이에서 두 정책을 결합하여 포괄적인 보안을 구현할 수 있습니다. 권장 구성은 권장 인그레스 및 이그레스 구성을 참조하세요.

승인 정책, 정책 프로필, 사용 사례에 대해 자세히 알아보려면 승인 정책 개요를 참조하세요.

전체 에이전트 수명 주기에 걸쳐 포괄적인 보안을 제공하려면 다음 멀티 게이트웨이 아키텍처 패턴을 사용하는 것이 좋습니다.

  • 클라이언트-에이전트 게이트웨이: 클라이언트-에이전트(인그레스) 게이트웨이는 단일 CONTENT_AUTHZ 정책만 지원합니다. 즉, 인그레스에서 Model Armor와 시맨틱 거버넌스 정책을 함께 사용할 수 없습니다. 프롬프트 인젝션 공격을 방지하려면 Model Armor CONTENT_AUTHZ 정책을 사용하는 것이 좋습니다. 하지만 시맨틱 거버넌스 정책 확장 프로그램을 대신 사용하려면 게이트웨이에 Model Armor가 구성되지 않았는지 확인해야 합니다. 다른 유형의 서비스 확장 프로그램은 인그레스 게이트웨이에 지원되지 않습니다.

  • Agent-to-Anywhere 게이트웨이: Agent-to-Anywhere(이그레스) 게이트웨이는 최대 4개의 승인 정책을 지원합니다. 이그레스 게이트웨이는 REQUEST_AUTHZ 및 CONTENT_AUTHZ 정책 프로필을 모두 지원하며, 이 한도 내에서 각 유형의 정책을 여러 개 구성할 수 있습니다.

    다음 구성을 사용하는 것이 좋습니다.

    • 에이전트 ID를 승인하기 위해 IAP(Identity-Aware Proxy)에 위임하는 REQUEST_AUTHZ 정책
    • 민감한 정보 노출을 방지하고 발신 도구 호출 및 응답에 자연어 제약 조건을 적용하기 위해 추가 결정을 Model Armor 또는 시맨틱 거버넌스 정책에 위임하는 하나 이상의 CONTENT_AUTHZ 정책

    정책 평가 방법에 대한 자세한 내용은 이그레스 정책 평가를 참조하세요.

이 멀티 게이트웨이 토폴로지는 Model Armor가 수신 프롬프트를 검사하는 동시에 IAP, Model Armor, 시맨틱 거버넌스 정책이 발신 응답을 검사하도록 합니다.

이그레스 정책 평가

이그레스 게이트웨이에 여러 승인 정책이 구성된 경우 정책 프로필 유형에 따라 순차적으로 평가됩니다.

  1. REQUEST_AUTHZ(헤더 기반) 정책: 이러한 정책 유형이 먼저 평가됩니다. 예를 들어 IAP 확장 프로그램은 콘텐츠가 처리되기 전에 호출 에이전트의 mTLS ID를 확인하고 IAM 허용 정책을 검증합니다. 요청이 이 검사를 통과하지 못하면 즉시 거부됩니다.
  2. CONTENT_AUTHZ(콘텐츠 기반) 정책: 이러한 정책 유형은 다음에 평가됩니다. 요청이 헤더 기반 검사를 통과하면 페이로드가 콘텐츠 기반 승인 확장 프로그램(예: 시맨틱 거버넌스 정책 엔진)으로 스트리밍되어 심층 콘텐츠 검사 및 규정 준수 평가를 수행합니다.

시작하기 전에

시작하기 전에 다음 요구사항을 충족하는지 확인하세요.

  • Agent Gateway가 배포됩니다. Agent Gateway 구성을 참조하세요.

  • 게이트웨이에 승인 정책을 연결하려면 배포된 Agent Gateway 리소스에 대한 networkservices.agentGateways.use IAM 권한이 있어야 합니다.

확장 프로그램으로 승인 정책 구성

이 섹션에서는 승인 및 콘텐츠 안전 결정을 IAP(Identity-Aware Proxy), Model Armor, 기타 커스텀 서비스에 위임하는 승인 정책을 구성하는 방법을 보여줍니다.

IAP에 승인 위임

승인 정책에 대한 액세스 결정을 IAP에 위임하도록 요청 승인 확장 프로그램을 구성할 수 있습니다.

다음 단계에서는 Agent Gateway 인스턴스의 승인 정책으로 승인 확장 프로그램을 구성하는 방법을 보여줍니다.

  1. 시작하기 전에: 리소스에 액세스 정책 바인드 중지(constraints/iam.managed.disableAccessPolicyBindings) 관리형 조직 정책 제약조건의 시행을 사용 중지합니다. 기본적으로 이 불리언 제약 조건은 새 조직에 사용 설정되며 IAM 통합 액세스 정책을 리소스에 바인딩할 수 없습니다. 자세한 내용은 불리언 규칙으로 정책 업데이트를 참조하세요.

  2. 에이전트 및 도구에 필요한 IAM 이그레스 정책을 만듭니다. 자세한 내용은 IAM 에이전트 정책 만들기를 참조하세요.

  3. 에이전트 게이트웨이를 만들 때 IAP를 사용 설정하려면(액세스 승인 매개변수 사용) Agent-to-Anywhere(이그레스) 모드에서 Agent Gateway 구성을 참조하세요.

  4. IAP를 가리키도록 승인 확장 프로그램을 구성합니다.

    1. YAML 파일에 확장 프로그램을 정의합니다. 제공된 샘플 값을 사용합니다. 승인 정책을 시행하지 않고 테스트하기 위해 드라이 런 감사 전용 모드로 확장 프로그램을 배포하려면 metadata 블록 내에 iamEnforcementMode 필드를 지정하면 됩니다.

      cat >iap-request-authz-extension.yaml <<EOF
      name: my-iap-request-authz-ext
      service: iap.googleapis.com
      failOpen: false
      timeout: 1s
      metadata:
        iapPolicyVersion: "V2"
      EOF
      

      승인 정책을 시행하지 않고 테스트하기 위해 드라이 런 감사 전용 모드로 확장 프로그램을 배포하려면 metadata 블록 내에 iamEnforcementMode 필드를 지정하면 됩니다. 이렇게 하면 정책을 확인하고 구성 오류로 인해 트래픽이 중단될 위험을 최소화할 수 있습니다.

      cat >iap-request-authz-extension.yaml <<EOF
      name: my-iap-request-authz-ext
      service: iap.googleapis.com
      failOpen: false
      timeout: 1s
      metadata:
        iapPolicyVersion: "V2"
        iamEnforcementMode: "DRY_RUN"
      EOF
      

      정책 시행을 시작할 준비가 되면 metadata 블록에서 iamEnforcementMode: "DRY_RUN" 필드를 삭제하거나 Google Cloud 콘솔에서 정책 시행을 선택합니다. 시행을 사용 설정하기 전에 테스트 실행 위반을 감사하는 방법은 제어 전반에서 테스트 실행 정책 위반 감사를 참조하세요.

    2. 승인 확장 프로그램을 가져옵니다. 다음 샘플 값과 함께 gcloud service-extensions authz-extensions import 명령어를 사용합니다.

      gcloud service-extensions authz-extensions import my-iap-request-authz-ext \
          --source=iap-request-authz-extension.yaml \
          --location=LOCATION
      
  5. 동일한 프로젝트에서 결정을 확장 프로그램에 위임하는 승인 정책을 구성합니다.

    1. my-iap-request-authz-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로 바꿉니다.

    2. 승인 정책을 프로젝트로 가져옵니다. 다음 샘플 값과 함께 gcloud network-security authz-policies import 명령어를 사용합니다.

      gcloud network-security authz-policies import my-iap-request-authz-policy \
          --source=iap-request-authz-policy.yaml \
          --location=LOCATION
      

Model Armor에 승인 위임

승인 정책의 콘텐츠 보안 결정을 Model Armor에 위임하도록 승인 확장 프로그램을 구성할 수 있습니다. Model Armor 템플릿은 Agent Gateway 및 에이전트와 동일한 프로젝트에 있거나 중앙 보안 또는 거버넌스 프로젝트와 같은 별도의 프로젝트에 있을 수 있습니다.

다음 예시에서는 Agent Gateway의 승인 정책을 사용하여 이러한 승인 확장 프로그램을 구성하는 방법을 보여줍니다.

콘솔

Google Cloud 콘솔을 사용하여 Agent Gateway에 Model Armor를 사용 설정하려면 다음 단계를 수행합니다.

  1. 필수 Model Armor 템플릿을 만듭니다.

  2. 에이전트 게이트웨이 구성을 참조하여 Agent Gateway를 만드는 동안 Model Armor를 사용 설정합니다(Model Armor 사용 설정 체크박스 사용). Model Armor 템플릿은 클라이언트-에이전트 및 에이전트-외부 위치 모드 모두에서 지원됩니다.

  3. Model Armor를 사용하는 경우 Agent Gateway 서비스 계정에 Model Armor 템플릿을 사용하는 데 필요한 권한을 부여해야 합니다. 서비스 계정의 형식은 service-PROJECT_NUMBER@gcp-sa-dep.입니다. 여기서 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. \
        --role=roles/modelarmor.calloutUser
    gcloud projects add-iam-policy-binding GATEWAY_PROJECT_ID \
        --member=serviceAccount:service-GATEWAY_PROJECT_NUMBER@gcp-sa-dep. \
        --role=roles/serviceusage.serviceUsageConsumer
    gcloud projects add-iam-policy-binding MODEL_ARMOR_PROJECT_ID \
        --member=serviceAccount:service-GATEWAY_PROJECT_NUMBER@gcp-sa-dep. \
        --role=roles/modelarmor.user
    

    다음을 바꿉니다.

    • GATEWAY_PROJECT_ID: 게이트웨이를 만든 프로젝트의 프로젝트 ID입니다.
    • GATEWAY_PROJECT_NUMBER: 게이트웨이를 만든 프로젝트의 프로젝트 번호입니다.
    • MODEL_ARMOR_PROJECT_ID: Model Armor 템플릿이 포함된 프로젝트의 프로젝트 ID입니다.

    Agent Runtime에 게이트웨이를 사용하는 경우 Agent Runtime 서비스 에이전트에도 Agent Gateway를 통해 Agent Runtime 트래픽 라우팅에 설명된 대로 이러한 권한이 필요합니다.

gcloud

  1. 필수 Model Armor 템플릿을 만듭니다.

  2. Model Armor를 사용하는 경우 Agent Gateway 서비스 계정에 Model Armor 템플릿을 사용하는 데 필요한 권한을 부여해야 합니다. 서비스 계정의 형식은 service-PROJECT_NUMBER@gcp-sa-dep.입니다. 여기서 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. \
        --role=roles/modelarmor.calloutUser
    gcloud projects add-iam-policy-binding GATEWAY_PROJECT_ID \
        --member=serviceAccount:service-GATEWAY_PROJECT_NUMBER@gcp-sa-dep. \
        --role=roles/serviceusage.serviceUsageConsumer
    gcloud projects add-iam-policy-binding MODEL_ARMOR_PROJECT_ID \
        --member=serviceAccount:service-GATEWAY_PROJECT_NUMBER@gcp-sa-dep. \
        --role=roles/modelarmor.user
    

    다음을 바꿉니다.

    • GATEWAY_PROJECT_ID: 게이트웨이를 만든 프로젝트의 프로젝트 ID입니다.
    • GATEWAY_PROJECT_NUMBER: 게이트웨이를 만든 프로젝트의 프로젝트 번호입니다.
    • MODEL_ARMOR_PROJECT_ID: Model Armor 템플릿이 포함된 프로젝트의 프로젝트 ID입니다.
  3. Model Armor를 가리키도록 승인 확장 프로그램을 구성합니다.

    1. 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: false
      timeout: 1s
      EOF
      
    2. 승인 확장 프로그램을 가져옵니다. 다음 샘플 값과 함께 gcloud service-extensions authz-extensions import 명령어를 사용합니다.

      gcloud service-extensions authz-extensions import my-ma-content-authz-ext \
         --source=ma-content-authz-extension.yaml \
         --location=LOCATION
      
  4. 확장 프로그램으로 승인 정책을 구성합니다.

    1. my-ma-content-authz-ext 확장 프로그램을 Agent Gateway와 연결하는 승인 정책을 정의합니다.

      에이전트에서 모든 위치로

      cat >ma-content-authz-policy.yaml <<EOF
      name: my-ma-content-authz-policy
      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/my-ma-content-authz-ext"
      httpRules:
        - to:
            operations: [ { "paths": [ { "prefix": "/" } ] } ]
          when: >
            request.headers['content-type'] == 'application/json' ||
            request.headers['content-type'].startsWith('text/')
      EOF
      

      다음에 유의하세요.

      • policyProfile 값은 CONTENT_AUTHZ로 설정됩니다. 이는 커스텀 정책 제공업체가 요청 본문을 포함한 요청 및 응답 트래픽을 처리함을 나타냅니다.

      • httpRules 파라미터는 CEL 속성을 사용하여 평가를 위해 Model Armor로 전달할 특정 트래픽과 일치하는 조건을 만드는 방법을 보여줍니다. 이 예시에서 규칙은 application/json 또는 text/ 콘텐츠 유형이 있는 모든 트래픽과 일치합니다. 이러한 규칙을 사용하여 Model Armor 평가를 관련 트래픽으로 제한하는 것이 좋습니다. 이렇게 하면 지원되는 LLM API, MCP, A2A 트래픽을 Model Armor로 라우팅하는 동시에 에이전트 gRPC 호출과 같은 내부 트래픽은 제외할 수 있습니다.

      클라이언트에서 에이전트로

      cat >ma-content-authz-policy.yaml <<EOF
      name: my-ma-content-authz-policy
      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/my-ma-content-authz-ext"
      EOF
      

      policyProfile 값은 CONTENT_AUTHZ로 설정됩니다. 이는 커스텀 정책 제공업체가 요청 본문을 포함한 요청 및 응답 트래픽을 처리함을 나타냅니다.

    2. 승인 정책을 프로젝트로 가져옵니다. 다음 샘플 값과 함께 gcloud network-security authz-policies import 명령어를 사용합니다.

      gcloud network-security authz-policies import my-ma-content-authz-policy \
        --source=ma-content-authz-policy.yaml \
        --location=LOCATION
      

Terraform

google 제공업체를 사용하여 Model Armor 승인 확장 프로그램과 CONTENT_AUTHZ 정책을 선언적으로 구성하려면 필요한 서비스 에이전트 IAM 바인딩, 승인 확장 프로그램, 승인 정책을 정의합니다. 이 구성은 Model Armor 템플릿이 Agent Gateway 및 에이전트와 동일한 프로젝트에 있는지 또는 별도의 프로젝트에 있는지에 관계없이 적용됩니다. Model Armor 템플릿이 에이전트 또는 Agent Gateway가 포함된 프로젝트와 다른 프로젝트에 있고 VPC 서비스 제어를 사용하는 경우 두 프로젝트가 동일한 VPC 서비스 제어 서비스 경계에 있어야 합니다.

  1. Agent Gateway가 포함된 프로젝트와 Model Armor 템플릿이 포함된 프로젝트에서 Service Extensions 서비스 에이전트에 필요한 역할을 부여합니다. 게이트웨이와 템플릿이 모두 동일한 프로젝트에 있더라도 이 단계를 완료해야 합니다.

    resource "google_project_iam_member" "dep_ma_callout_user" {
      project = "PROJECT_ID"
      role    = "roles/modelarmor.calloutUser"
      member  = "serviceAccount:service-PROJECT_NUMBER@gcp-sa-dep."
    }
    
    resource "google_project_iam_member" "dep_service_usage_consumer" {
      project = "PROJECT_ID"
      role    = "roles/serviceusage.serviceUsageConsumer"
      member  = "serviceAccount:service-PROJECT_NUMBER@gcp-sa-dep."
    }
    
    resource "google_project_iam_member" "dep_ma_template_user" {
      project = "MODEL_ARMOR_PROJECT_ID"
      role    = "roles/modelarmor.user"
      member  = "serviceAccount:service-PROJECT_NUMBER@gcp-sa-dep."
    }
    

    Agent Runtime에 게이트웨이를 사용하는 경우 Agent Runtime 서비스 에이전트에도 Agent Gateway를 통해 Agent Runtime 트래픽 라우팅에 설명된 권한이 필요합니다.

  2. Model Armor를 가리키는 google_network_services_authz_extension 리소스를 정의합니다.

    resource "google_network_services_authz_extension" "ma_content_authz_ext" {
      project   = "PROJECT_ID"
      location  = "LOCATION"
      name      = "my-ma-content-authz-ext"
      service   = "modelarmor.LOCATION.rep.googleapis.com"
      timeout   = "1s"
      fail_open = false
    
      metadata = {
        model_armor_settings = jsonencode([
          {
            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"
          }
        ])
      }
    
      depends_on = [
        google_project_iam_member.dep_ma_callout_user,
        google_project_iam_member.dep_service_usage_consumer,
        google_project_iam_member.dep_ma_template_user,
      ]
    }
    
  3. google_network_security_authz_policy 리소스를 사용하여 확장 프로그램을 Agent Gateway에 연결합니다.

    에이전트에서 모든 위치로

    resource "google_network_security_authz_policy" "ma_content_authz_policy" {
      project        = "PROJECT_ID"
      location       = "LOCATION"
      name           = "my-ma-content-authz-policy"
      policy_profile = "CONTENT_AUTHZ"
      action         = "CUSTOM"
    
      target {
        resources = [
          "projects/PROJECT_ID/locations/LOCATION/agentGateways/AGENT_GATEWAY_NAME"
        ]
      }
    
      custom_provider {
        authz_extension {
          resources = [
            google_network_services_authz_extension.ma_content_authz_ext.id
          ]
        }
      }
    
      http_rules {
        to {
          operations {
            paths {
              prefix = "/"
            }
          }
        }
        when = "request.headers['content-type'] == 'application/json' || request.headers['content-type'].startsWith('text/')"
      }
    }
    

    클라이언트에서 에이전트로

    resource "google_network_security_authz_policy" "ma_content_authz_policy" {
      project        = "PROJECT_ID"
      location       = "LOCATION"
      name           = "my-ma-content-authz-policy"
      policy_profile = "CONTENT_AUTHZ"
      action         = "CUSTOM"
    
      target {
        resources = [
          "projects/PROJECT_ID/locations/LOCATION/agentGateways/AGENT_GATEWAY_NAME"
        ]
      }
    
      custom_provider {
        authz_extension {
          resources = [
            google_network_services_authz_extension.ma_content_authz_ext.id
          ]
        }
      }
    }
    

다음을 바꿉니다.

  • PROJECT_ID: Agent Gateway를 만든 프로젝트의 프로젝트 ID입니다.

  • PROJECT_NUMBER: Agent Gateway를 만든 프로젝트의 프로젝트 번호입니다.

  • MODEL_ARMOR_PROJECT_ID: Model Armor 템플릿이 포함된 프로젝트의 프로젝트 ID입니다. PROJECT_ID과 동일한 프로젝트 또는 별도의 프로젝트일 수 있습니다. 템플릿이 에이전트 또는 Agent Gateway 프로젝트와 다른 프로젝트에 있고 VPC 서비스 제어를 사용하는 경우 두 프로젝트가 동일한 서비스 경계에 있어야 합니다.

  • LOCATION: Agent Gateway 및 Model Armor 템플릿이 있는 리전입니다.

  • TEMPLATE_ID: Model Armor 템플릿의 ID입니다.

  • AGENT_GATEWAY_NAME: Agent Gateway 리소스의 이름입니다.

커스텀 승인 확장 프로그램에 승인 위임

커스텀 승인 확장 프로그램을 구성하여 커스텀 서비스에 결정을 위임할 수 있습니다. 이러한 커스텀 확장 프로그램은 정규화된 도메인 이름(FQDN)만 타겟팅할 수 있습니다.

FQDN 대상을 사용하는 경우 확장 프로그램은 TLS 암호화와 함께 HTTP2 프로토콜을 사용하여 포트 443에서 엔드포인트와 통신합니다. 하지만 확장 프로그램은 서버 인증서를 검증하지 않습니다. 따라서 보안을 강화하려면 확인된 엔드포인트가 VPC 네트워크 내에 있어야 합니다. 또한 Agent Gateway 프로젝트와 VPC 네트워크 간에 DNS 피어링이 설정되어 있는지 확인합니다.

  1. 특정 FQDN(예: mycustomauthz.internal.net)에 대한 승인 정책으로 승인 확장 프로그램을 구성하려면 다음 예시와 같이 확장 프로그램 YAML 파일에서 service의 값으로 지정합니다. 이 예시에서는 FULL_DUPLEX_STREAMED 본문 처리 모드에서 ext_proc 프로토콜을 구현하는 VPC 네트워크에 서버를 배포했다고 가정합니다.

    cat >custom-authz-extension.yaml <<EOF
    name: my-custom-authz-ext
    service: mycustomauthz.internal.net
    failOpen: false
    timeout: 1s
    EOF
    
  2. 커스텀 서비스를 가리키는 승인 확장 프로그램을 만듭니다.

    gcloud beta service-extensions authz-extensions import custom-authz-extension \
      --source=custom-authz-extension.yaml \
      --location=LOCATION
    
  3. 확장 프로그램을 만든 후 승인 확장 프로그램에 결정을 위임하는 CUSTOM 승인 정책을 구성합니다.

      cat >authz-policy.yaml <<EOF
      name: authz-with-extension
      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/custom-authz-extension"
      EOF
    
  4. 승인 정책을 만듭니다.

    gcloud network-security authz-policies import authz-policy-with-extension \
    --source=authz-policy.yaml \
    --location=LOCATION
    

이 예시와 같이 CONTENT_AUTHZ 프로필을 사용하여 승인 확장 프로그램이 승인 정책과 연결되면 게이트웨이가 요청 및 응답 페이로드(헤더 및 본문)에 대한 확장 프로그램을 호출하여 에이전트 트래픽에 대한 심층 콘텐츠 검사, 프롬프트 가드레일, 데이터 삭제를 허용합니다. 기본적으로 CONTENT_AUTHZ 정책은 FULL_DUPLEX_STREAMED 모드에서 Envoy ext_proc 프로토콜을 사용하여 본문 이벤트를 처리합니다.

IAP 승인과 Model Armor 가드레일 결합

포괄적인 보안을 위해 REQUEST_AUTHZ 정책 프로필이 있는 커스텀 승인 정책과 CONTENT_AUTHZ 정책 프로필이 있는 다른 커스텀 승인 정책을 설정하는 것이 좋습니다.

다음 예시에서는 IAP를 중앙 집중식 요청 승인 시스템으로 사용하고 Model Armor를 AI 가드레일로 사용합니다. 이전 예시와 같이 서비스 확장 프로그램으로 각 솔루션을 교체하여 자체 커스텀 솔루션을 사용할 수 있습니다.

  1. IAP에 위임하는 REQUEST_AUTHZ 승인 확장 프로그램과 확장 프로그램을 가리키는 승인 정책을 구성합니다.

    1. 승인 확장 프로그램을 정의합니다. metadata의 iapPolicyVersion 필드는 필수입니다.

      cat >iap-extension.yaml <<EOF
      name: iap-extension
      service: iap.googleapis.com
      failOpen: false
      timeout: 1s
      metadata:
        iapPolicyVersion: "V2"
      EOF
      
    2. 승인 확장 프로그램을 만듭니다.

      gcloud service-extensions authz-extensions import iap-extension \
      --source=iap-extension.yaml \
      --location=LOCATION
      

      LOCATION을 확장 프로그램의 리전으로 바꿉니다.

    3. 확장 프로그램에 위임하는 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: Agent Gateway의 이름입니다.
    4. 승인 정책을 만듭니다.

      gcloud network-security authz-policies import authz-iap \
      --source=authz-policy-request-authz.yaml \
      --location=LOCATION
      
  2. Model Armor에 위임하는 CONTENT_AUTHZ 승인 확장 프로그램과 확장 프로그램을 가리키는 승인 정책을 구성합니다.

    1. 확장 프로그램을 정의합니다.

      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: false
      timeout: 1s
      EOF
      

      다음을 바꿉니다.

      • LOCATION: Model Armor 템플릿이 있는 리전입니다.
      • MODEL_ARMOR_PROJECT_ID: Model Armor 템플릿이 포함된 프로젝트 ID입니다.
      • RESPONSE_TEMPLATE_ID: 응답 템플릿의 ID입니다.
      • REQUEST_TEMPLATE_ID: 요청 템플릿의 ID입니다.
    2. 승인 확장 프로그램을 만듭니다.

      gcloud service-extensions authz-extensions import ma-extension \
      --source=ma-extension-file.yaml \
      --location=LOCATION
      
    3. 확장 프로그램에 위임하는 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
      
    4. 승인 정책을 만듭니다.

      gcloud 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 연결을 통해 두 가지 유형의 승인을 모두 사용 설정하므로 지연 시간 프로필을 개선할 수 있습니다.

시맨틱 거버넌스 정책에 승인 위임

승인 정책의 의도 제어 및 자연어 제약 조건 결정을 시맨틱 거버넌스 정책 엔진(semanticGovernancePolicyEngine)에 위임하도록 승인 확장 프로그램을 구성할 수 있습니다.

정책 엔진을 프로비저닝하고 게이트웨이에 필요한 CONTENT_AUTHZ 승인 정책 및 승인 확장 프로그램 바인딩을 만드는 방법은 정책 엔진을 Agent Gateway에 연결을 참조하세요.

MCP 프로토콜 속성을 기반으로 한 승인

Agent Gateway는 요청의 MCP 프로토콜 페이로드를 파싱하고 추출된 속성을 승인 정책에 사용할 수 있도록 합니다.

특정 도구의 이름과 같은 MCP 메서드 매개변수를 기반으로 액세스를 제한할 수 있습니다. 이 섹션에서는 ALLOW 정책과 DENY에 대한 두 가지 예시를 보여줍니다.

  1. 승인 정책을 구성합니다.

    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
    EOF
    

    DENY 정책 예시

    이 예시에서는 Agent Gateway 뒤에 있는 MCP 서버에 대한 모든 prompts/ 메서드 액세스를 허용하지 않습니다.

    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
    
  2. 승인 정책을 만듭니다.

    gcloud 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: 리소스 위치입니다.

제한사항

승인 정책을 사용할 때는 다음 제한사항이 적용됩니다.

  • 게이트웨이당 최대 승인 정책 수는 게이트웨이 모드에 따라 다릅니다.

    • Agent-to-Anywhere(이그레스) 게이트웨이의 경우 정책 프로필(REQUEST_AUTHZ 또는 CONTENT_AUTHZ)에 관계없이 게이트웨이당 최대 4개의 승인 정책을 구성할 수 있습니다.
    • 클라이언트-에이전트(인그레스) 게이트웨이의 경우 최대 1개의 CONTENT_AUTHZ 정책을 구성할 수 있습니다.

    자세한 내용은 권장 인그레스 및 이그레스 구성을 참조하세요.

  • CONTENT_AUTHZ 프로필과 함께 커스텀 승인 확장 프로그램을 사용하는 경우 본문 이벤트에 대해 ext_proc 프로토콜과 FULL_DUPLEX_STREAMED 모드를 지원해야 합니다.

  • 동일한 프로필을 사용하는 커스텀 승인 정책을 여러 개 구성하는 경우 실행 순서가 보장되지 않습니다.

또한 승인 확장 프로그램의 제한사항에 대한 자세한 내용은 다음 섹션을 참조하세요.

다음 단계

Codelab

Gemini Enterprise Agent Platform에서 Agent Gateway를 사용하여 에이전트형 워크로드를 제어하는 방법을 알아봅니다.

가이드

Agent Gateway 리소스를 확인, 업데이트, 연결 해제, 삭제하는 방법을 알아봅니다.

가이드

Agent Gateway를 모니터링하는 방법을 알아봅니다.

문제 해결

에이전트 게이트웨이 연결 문제를 해결하는 방법을 알아봅니다.