인증 관리자를 사용하여 2-legged OAuth로 인증

상담사가 자체 권한을 사용하여 ServiceNow 또는 Salesforce와 같은 외부 도구에 인증할 수 있도록 하려면 상담사 ID 인증 관리자에서 2-legged OAuth (클라이언트 사용자 인증 정보) 인증 공급자를 사용하여 아웃바운드 인증을 구성하세요.

사용자 인증 정보와 토큰을 관리함으로써 2단계 OAuth 인증 제공업체는 인증 흐름을 처리하기 위한 맞춤 코드가 필요하지 않습니다.

중요: 이 문서에서는 상담사 ID API를 사용하여 인증하는 방법을 보여줍니다. IAM Connectors API (미리보기)는 일반적으로 제공되지 않으므로 Agent Identity API를 사용하는 것이 좋습니다. IAM Connectors API를 사용하는 경우 Agent Identity API로 마이그레이션하세요.

2-legged OAuth 워크플로

2-legged OAuth 인증 제공자는 에이전트의 ID를 사용하며 사용자 동의가 필요하지 않습니다. Google에서 클라이언트 사용자 인증 정보의 스토리지를 관리합니다. 에이전트 개발 키트 (ADK)를 사용하면 결과 액세스 토큰이 자동으로 검색되어 도구 호출 헤더에 삽입됩니다.

시작하기 전에

1. 올바른 인증 방법을 선택했는지 확인합니다.

2. Agent Identity API를 사용 설정합니다.

   API 사용 설정에 필요한 역할

   API를 사용 설정하려면 serviceusage.services.enable 권한이 필요합니다. 프로젝트를 만든 경우 소유자 역할 (roles/owner)을 통해 이 권한이 이미 있을 수 있습니다. 그렇지 않으면 서비스 사용량 관리자 역할 (roles/serviceusage.serviceUsageAdmin)을 통해 이 권한을 얻을 수 있습니다. 역할을 부여하는 방법 알아보기

   API 사용 설정하기

3. 에이전트 만들기 및 배포

4. 연결하려는 서드 파티 애플리케이션에서 클라이언트 ID와 클라이언트 보안 비밀번호를 가져옵니다.

5. 이 작업을 완료하는 데 필요한 역할이 있는지 확인합니다.

필요한 역할

2단계 에이전트 ID 인증 제공자를 만들고 사용하는 데 필요한 권한을 얻으려면 관리자에게 프로젝트에 대한 다음 IAM 역할을 부여해 달라고 요청하세요.

• 인증 제공업체를 만들려면 다음 단계를 따르세요.
  • 상담사 ID 관리자 (roles/agentidentity.admin)
  • 에이전트 ID 편집자 (roles/agentidentity.editor)
• 인증 제공업체를 사용하려면 다음 단계를 따르세요.
  • 에이전트 ID 사용자 (roles/agentidentity.user)
  • 에이전트 기본 액세스 (roles/aiplatform.agentDefaultAccess)
  • 에이전트 컨텍스트 편집자 (roles/aiplatform.agentContextEditor)
  • Vertex AI 사용자 (roles/aiplatform.user)
  • 서비스 사용량 소비자(roles/serviceusage.serviceUsageConsumer)

역할 부여에 대한 자세한 내용은 프로젝트, 폴더, 조직에 대한 액세스 관리를 참조하세요.

이러한 사전 정의된 역할에는 2레그 에이전트 아이덴티티 인증 프로바이더를 만들고 사용하는 데 필요한 권한이 포함되어 있습니다. 필요한 정확한 권한을 보려면 필수 권한 섹션을 펼치세요.

필수 권한

2레그 에이전트 아이덴티티 인증 프로바이더를 만들고 사용하려면 다음 권한이 필요합니다.

• 인증 제공업체를 만들려면 agentidentity.authProviders.create 권한이 필요합니다.
• 인증 제공업체를 사용하려면 다음 단계를 따르세요.
  • agentidentity.authProviders.retrieveCredentials
  • aiplatform.endpoints.predict
  • aiplatform.sessions.create

커스텀 역할이나 다른 사전 정의된 역할을 사용하여 이 권한을 부여받을 수도 있습니다.

2단계 인증 제공업체 만들기

인증 제공자를 만들어 서드 파티 애플리케이션의 구성과 사용자 인증 정보를 정의합니다.

2단계 인증 프로바이더를 만들려면 Google Cloud 콘솔 또는 Google Cloud CLI를 사용하세요.

콘솔

1. Google Cloud 콘솔에서 Agent Registry 페이지로 이동합니다.

   Agent Registry로 이동

2. 인증 제공자를 만들려는 에이전트의 이름을 클릭합니다.
3. ID를 클릭합니다.
4. 인증 제공업체 섹션에서 인증 제공업체 추가를 클릭합니다.

5. 인증 제공업체 추가 창에서 이름과 설명을 입력합니다.

   이름에는 소문자, 숫자 또는 하이픈만 포함할 수 있으며 하이픈으로 끝나면 안 되고 소문자로 시작해야 합니다.

6. OAuth 유형 목록에서 OAuth (2 legged)를 선택합니다.
7. 만들고 계속하기를 클릭합니다.
8. 인증 제공자를 사용할 수 있는 권한을 에이전트 ID에 부여하려면 액세스 권한 부여를 클릭합니다.

   이 프로세스는 인증 제공업체 리소스의 에이전트 ID에 에이전트 ID 사용자(roles/agentidentity.user) 역할을 자동으로 할당합니다.

9. 인증 제공업체 사용자 인증 정보 섹션에서 다음 정보를 입력합니다.
   • 클라이언트 ID
   • 클라이언트 보안 비밀번호
   • 토큰 URL
10. 공급업체 구성 추가를 클릭합니다.

새로 생성된 인증 제공자가 인증 제공자 목록에 표시됩니다.

gcloud CLI

1. 인증 제공업체를 만듭니다.

   gcloud agent-identity auth-providers create AUTH_PROVIDER_NAME \
       --location="LOCATION" \
       --two-legged-oauth-client-id="CLIENT_ID" \
       --two-legged-oauth-client-secret="CLIENT_SECRET" \
       --two-legged-oauth-token-url="TOKEN_URL"

2. 인증 제공업체가 목록에 표시되고 상태가 ENABLED인지 확인합니다.

   gcloud agent-identity auth-providers list \
      --project="PROJECT_ID" \
      --location="LOCATION"

3. 에이전트와 로컬 개발 환경이 인증 제공자에서 사용자 인증 정보를 가져올 수 있도록 액세스 권한을 부여합니다. 배포된 에이전트와 개인 사용자 계정이 인증 제공업체에 액세스하도록 허용하려면 인증 제공업체 리소스에 에이전트 ID 사용자(roles/agentidentity.user) 역할을 부여합니다.

   1. 배포된 에이전트의 SPIFFE ID (에이전트 ID)에 대한 액세스 권한을 부여합니다.

      gcloud agent-identity auth-providers add-iam-policy-binding AUTH_PROVIDER_NAME \
          --project="PROJECT_ID" \
          --location="LOCATION" \
          --role="roles/agentidentity.user" \
          --member="principal://agents.global.org-ORGANIZATION_ID.system.id.goog/resources/aiplatform/projects/PROJECT_NUMBER/locations/LOCATION/reasoningEngines/ENGINE_ID"

   2. 로컬 개발 및 테스트를 위해 개인 사용자 계정에 액세스 권한을 부여합니다(adk web).

      gcloud agent-identity auth-providers add-iam-policy-binding AUTH_PROVIDER_NAME \
          --project="PROJECT_ID" \
          --location="LOCATION" \
          --role="roles/agentidentity.user" \
          --member="user:USER_EMAIL"

다음을 바꿉니다.

• PROJECT_ID: Google Cloud 프로젝트 ID입니다.
• LOCATION: 인증 제공업체와 에이전트가 배포된 위치입니다 (예: us-west1).
• AUTH_PROVIDER_NAME: 인증 제공업체의 이름입니다 (예: jira-mcp-2lo-authprovider).
• CLIENT_ID: 서드 파티 서비스에서 생성한 OAuth 클라이언트 ID
• CLIENT_SECRET: 서드 파티 서비스에서 생성한 OAuth 클라이언트 보안 비밀번호입니다.
• TOKEN_URL: 토큰 서버 URL (예: https://oauth2.googleapis.com/token)입니다.
• ORGANIZATION_ID: Google Cloud 조직 ID입니다.
• PROJECT_NUMBER: Google Cloud 프로젝트 번호.
• ENGINE_ID: 배포된 추론 엔진 에이전트의 ID입니다.
• USER_EMAIL: 개인 사용자 계정 이메일 주소입니다.

에이전트 코드에서 인증

에이전트를 인증하려면 ADK를 사용하면 됩니다.

참고: 다음 샘플은 모듈 수준에서 인증 제공자를 등록하며, 이는 에이전트를 로컬에서 실행하거나 에이전트 CLI로 배포할 때 작동합니다. Vertex AI Python SDK로 배포하는 경우 배포된 컨테이너에서 실행되도록 set_up()에 인증 제공업체를 등록하세요. 자세한 내용은 에이전트 배포를 참고하세요.

ADK

ADK의 MCP 도구 세트를 사용하여 에이전트의 코드에서 인증 제공업체를 참조합니다.

from google.adk.agents import Agent
from google.adk.auth.credential_manager import CredentialManager
from google.adk.integrations.agent_identity import GcpAuthProvider, GcpAuthProviderScheme
from google.adk.tools.mcp_tool.mcp_session_manager import StreamableHTTPConnectionParams
from google.adk.tools.mcp_tool.mcp_toolset import McpToolset
from google.adk.auth.auth_tool import AuthConfig

# Register the Google Cloud Auth Provider so the CredentialManager can use it.
CredentialManager.register_auth_provider(GcpAuthProvider())

# Create the Google Cloud Auth Provider scheme
# Note: If using the legacy V1 API, the resource name uses 'connectors'
# instead of 'authProviders': projects/.../connectors/...
auth_scheme = GcpAuthProviderScheme(
    name="projects/PROJECT_ID/locations/LOCATION/authProviders/AUTH_PROVIDER_NAME"
)

# Configure an MCP tool with the authentication scheme.
toolset = McpToolset(
    connection_params=StreamableHTTPConnectionParams(url="https://YOUR_MCP_SERVER_URL"),
    auth_scheme=auth_scheme,
)

# Initialize the agent with the authenticated tools.
agent = Agent(
    name="AGENT_NAME",
    model="gemini-2.5-flash",
    instruction="AGENT_INSTRUCTIONS",
    tools=[toolset],
)

ADK

ADK에서 인증된 함수 도구를 사용하여 에이전트의 코드에서 인증 제공업체를 참조합니다.

import httpx
from google.adk.agents import Agent
from google.adk.auth.credential_manager import CredentialManager
from google.adk.integrations.agent_identity import GcpAuthProvider
from google.adk.integrations.agent_identity import GcpAuthProviderScheme
from google.adk.apps import App
from google.adk.auth.auth_credential import AuthCredential
from google.adk.auth.auth_tool import AuthConfig
from google.adk.tools.authenticated_function_tool import AuthenticatedFunctionTool
from vertexai import agent_engines

# First, register Google Cloud auth provider
CredentialManager.register_auth_provider(GcpAuthProvider())

# Create Auth Config
# Note: If using the legacy V1 API, the resource name uses 'connectors'
# instead of 'authProviders': projects/.../connectors/...
spotify_auth_config = AuthConfig(
    auth_scheme=GcpAuthProviderScheme(
        name=(
            "projects/PROJECT_ID/locations/"
            "LOCATION/authProviders/"
            "AUTH_PROVIDER_NAME"
        )
    )
)

# Use the Auth Config in Authenticated Function Tool
spotify_search_track_tool = AuthenticatedFunctionTool(
    func=spotify_search_track, auth_config=spotify_auth_config
)

# Sample function tool
async def spotify_search_track(credential: AuthCredential, query: str) -> str | list:
    token = None
    if credential.http and credential.http.credentials:
        token = credential.http.credentials.token

    if not token:
        return "Error: No authentication token available."

    async with httpx.AsyncClient() as client:
        response = await client.get(
            "https://api.spotify.com/v1/search",
            headers={"Authorization": f"Bearer {token}"},
            params={"q": query, "type": "track", "limit": 1},
        )
        # Add your own logic here

agent = Agent(
    name="AGENT_NAME",
    model="MODEL_NAME",
    instruction="AGENT_INSTRUCTIONS",
    tools=[spotify_search_track_tool],
)

app = App(
    name="APP_NAME",
    root_agent=agent,
)

vertex_app = agent_engines.AdkApp(app_name=app)

ADK

ADK의 에이전트 레지스트리 MCP 도구 세트를 사용하여 에이전트의 코드에서 인증 제공업체를 참조합니다.

이 흐름의 인증 스키마를 구성하지 않습니다. MCP 서버의 아웃바운드 바인딩은 사용할 인증 제공업체를 이미 기록합니다.

주의: 인증 제공업체, MCP 서버, 에이전트 레지스트리 클라이언트에 동일한 리전을 사용하세요. 인증 제공자는 global 위치에서 사용할 수 없으므로 location="global"을 설정하면 아웃바운드 바인딩을 만들 때 Location of auth provider does not match location of binding 오류가 발생하여 실패합니다.

from google.adk.agents import Agent
from google.adk.auth.credential_manager import CredentialManager
from google.adk.integrations.agent_identity import GcpAuthProvider
from google.adk.integrations.agent_registry import AgentRegistry

# First, register Google Cloud auth provider
CredentialManager.register_auth_provider(GcpAuthProvider())

# Set Agent Registry. LOCATION must be the same region as the auth provider.
registry = AgentRegistry(project_id="PROJECT_ID", location="LOCATION")

# The auth provider is resolved from the MCP server's outbound binding.
toolset = registry.get_mcp_toolset(
    mcp_server_name=(
        "projects/PROJECT_ID/locations/"
        "LOCATION/mcpServers/"
        "agentregistry-00000000-0000-0000-0000-000000000000"
    ),
)

agent = Agent(
    name="AGENT_NAME",
    model="MODEL_NAME",
    instruction="AGENT_INSTRUCTIONS",
    tools=[toolset],
)

  

로컬 테스트를 위한 종속 항목 설치

가상 환경에서 로컬로 에이전트를 테스트하려면 다음 필수 종속 항목을 설치하세요.

1. 가상 환경 만들기 및 활성화

   python3 -m venv env
   source env/bin/activate

2. 필요한 패키지를 설치합니다.

   pip install google-cloud-aiplatform[agent_engines,adk] google-adk[agent-identity]

에이전트 배포

에이전트를 Google Cloud에 배포할 때는 에이전트 ID가 사용 설정되어 있어야 합니다.

에이전트 CLI

에이전트 개발 키트 (ADK) 및 에이전트 CLI를 사용하는 경우 다음 단계에 따라 에이전트 ID가 사용 설정된 상태로 에이전트를 배포하세요.

1. 에이전트 애플리케이션 폴더에서 .agent_engine_config.json이라는 구성 파일을 만들어 에이전트 ID를 사용 설정합니다.

   echo '{ "identity_type": "AGENT_IDENTITY" }' > AGENT_NAME/.agent_engine_config.json

2. Gemini Enterprise Agent Platform의 에이전트 런타임에 에이전트를 배포합니다.

   uv run adk deploy agent_engine AGENT_NAME \
       --project="PROJECT_ID" \
       --region="LOCATION"

   다음을 바꿉니다.

   • AGENT_NAME: 에이전트 애플리케이션 폴더의 이름입니다 (예: maps_agent).
   • PROJECT_ID: Google Cloud프로젝트 ID입니다.
   • LOCATION: 에이전트를 배포할 지원되는 지역입니다 (예: us-west1).

Python SDK

Vertex AI Python SDK를 사용하여 프로그래매틱 방식으로 배포하는 경우 identity_type=AGENT_IDENTITY 플래그를 사용하세요.

주의: SDK는 앱 객체를 직렬화하므로 가져오기 시간에 로컬 스크립트가 실행하는 CredentialManager.register_auth_provider() 호출은 배포된 컨테이너에서 실행되지 않습니다. 대신 컨테이너가 시작될 때 런타임에서 호출하는 앱의 set_up() 메서드에 인증 제공자를 등록하세요. 그렇지 않으면 에이전트가 쿼리 시간에 No auth provider registered for custom auth scheme 'gcpAuthProviderScheme'로 실패합니다. 자세한 내용은 배포 고려사항을 참고하세요.

import vertexai
from vertexai import types
from vertexai.agent_engines import AdkApp
from google.adk.auth.credential_manager import CredentialManager
from google.adk.integrations.agent_identity import GcpAuthProvider

# Initialize the Vertex AI client with v1beta1 API for Agent Identity support
client = vertexai.Client(
    project="PROJECT_ID",
    location="LOCATION",
    http_options=dict(api_version="v1beta1")
)

# Register the auth provider in set_up() so that it runs in the deployed
# container. Use the proper wrapper class for your Agent Framework (for example, AdkApp).
class AuthenticatedAdkApp(AdkApp):
    def set_up(self):
        CredentialManager.register_auth_provider(GcpAuthProvider())
        super().set_up()

app = AuthenticatedAdkApp(agent=agent)

# Deploy the agent with Agent Identity enabled
remote_app = client.agent_engines.create(
    agent=app,
    config={
        "identity_type": types.IdentityType.AGENT_IDENTITY,
        "requirements": [
            "google-cloud-aiplatform[agent_engines,adk]",
            "google-adk[agent-identity,mcp]>=2.7.1",
        ],
    },
)

다음을 바꿉니다.

• PROJECT_ID: Google Cloud 프로젝트 ID입니다.
• LOCATION: 에이전트를 배포할 지원되는 지역입니다 (예: us-west1).

다음 단계

• 에이전트 ID 개요
• 인증 관리자로 3-legged OAuth를 사용하여 인증
• 인증 관리자로 API 키를 사용하여 인증
• 에이전트 ID 인증 제공업체 관리
• 에이전트 ID 인증 관리자 문제 해결