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

특정 최종 사용자를 대신하여 에이전트가 외부 도구 및 서비스 (예: Jira 작업 또는 GitHub 저장소)에 액세스할 수 있도록 하려면 에이전트 ID 인증 관리자에서 3-legged OAuth 인증 제공업체를 구성합니다.

3-legged OAuth 인증 제공업체는 사용자 리디렉션 및 토큰을 관리합니다. 이렇게 하면 복잡한 OAuth 2.0 흐름을 처리하기 위해 커스텀 코드를 작성할 필요가 없습니다.

3-legged OAuth 워크플로

3-legged OAuth 인증 제공업체는 에이전트가 사용자를 대신하여 리소스에 액세스하므로 사용자 동의가 필요합니다.

  1. 프롬프트 및 리디렉션: 채팅 인터페이스에서 사용자에게 로그인하라는 메시지를 표시한 후 사용자를 서드 파티 애플리케이션의 동의 페이지로 리디렉션합니다.
  2. 동의 및 저장: 사용자가 권한을 부여하면 에이전트 ID 인증 관리자가 결과 OAuth 토큰을 Google에서 관리하는 사용자 인증 정보 보관소에 저장합니다.
  3. 삽입: 에이전트 개발 키트 (ADK)를 사용하면 에이전트가 인증 제공업체에서 토큰을 자동으로 가져와 도구 호출 헤더에 삽입합니다.

시작하기 전에

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

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

    API 사용 설정에 필요한 역할

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

    API 사용 설정하기

  3. 에이전트를 만들고 배포합니다.
  4. 사용자 로그인 프롬프트를 처리하고 서드 파티 동의 페이지로 리디렉션하는 프런트엔드 애플리케이션이 있는지 확인합니다.
  5. 이 작업을 완료하는 데 필요한 역할이 있는지 확인합니다.

필요한 역할

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

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

이러한 사전 정의된 역할에는 3-legged 인증 제공업체를 만들고 사용하는 데 필요한 권한이 포함되어 있습니다. 필요한 정확한 권한을 보려면 필수 권한 섹션을 펼치세요.

필수 권한

3-legged 인증 프로바이더를 만들고 사용하려면 다음 권한이 필요합니다.

  • 인증 제공업체를 만들려면: iamconnectors.connectors.create
  • 인증 제공업체를 사용하려면 다음 안내를 따르세요.
    • iamconnectors.connectors.retrieveCredentials
    • aiplatform.endpoints.predict
    • aiplatform.sessions.create

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

3-legged 인증 제공업체 만들기

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

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

콘솔

  1. 콘솔에서 에이전트 레지스트리 페이지로 이동합니다. Google Cloud

    에이전트 레지스트리로 이동

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

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

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

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

    이렇게 하면 인증 제공업체 리소스의 에이전트 ID에 커넥터 사용자 (roles/iamconnectors.user) 역할이 자동으로 할당됩니다.

  9. 콜백 URL을 복사합니다.
  10. 별도의 탭에서 서드 파티 OAuth 클라이언트 애플리케이션에 콜백 URL을 등록합니다.
  11. 인증 제공업체 사용자 인증 정보 섹션에서 다음 정보를 입력합니다.
    • 클라이언트 ID
    • 클라이언트 보안 비밀번호
    • 토큰 URL
    • 승인 URL
  12. 제공업체 구성 추가 를 클릭합니다.

새로 만든 인증 제공업체가 인증 제공업체 목록에 표시됩니다.

gcloud CLI

  1. 클라이언트를 등록하고 클라이언트 ID와 클라이언트 보안 비밀번호를 가져오도록 OAuth 클라이언트 애플리케이션을 구성합니다. 해당 섹션의 템플릿을 사용하여 리디렉션 URI를 지정합니다.

  2. 클라이언트 사용자 인증 정보를 사용하여 인증 제공업체를 만듭니다.

    gcloud alpha agent-identity connectors create AUTH_PROVIDER_NAME \
    --project="PROJECT_ID" \
    --location="LOCATION" \
    --three-legged-oauth-client-id="CLIENT_ID" \
    --three-legged-oauth-client-secret="CLIENT_SECRET" \
    --three-legged-oauth-authorization-url="AUTHORIZATION_URL" \
    --three-legged-oauth-token-url="TOKEN_URL"
  3. 인증 제공업체가 목록에 표시되고 상태가 ENABLED인지 확인합니다. 
    gcloud alpha agent-identity connectors list \
   --project="PROJECT_ID" \
   --location="LOCATION"

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

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

      gcloud alpha agent-identity connectors add-iam-policy-binding AUTH_PROVIDER_NAME \
    --project="PROJECT_ID" \
    --location="LOCATION" \
    --role="roles/iamconnectors.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 alpha agent-identity connectors add-iam-policy-binding AUTH_PROVIDER_NAME \
    --project="PROJECT_ID" \
    --location="LOCATION" \
    --role="roles/iamconnectors.user" \
    --member="user:USER_EMAIL"

다음을 바꿉니다.

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

OAuth 클라이언트 애플리케이션 구성

OAuth 클라이언트 사용자 인증 정보를 등록하기 전에 서드 파티 인증 서버 (예: Google, GitHub 또는 Jira)에서 클라이언트 ID와 클라이언트 보안 비밀번호를 가져옵니다.

외부의 서드 파티 서비스에 연결하는 경우 해당 서비스의 개발자 포털에서 OAuth 클라이언트 사용자 인증 정보를 가져오고 이 섹션의 단계를 건너뜁니다.Google Cloud

리디렉션 URI 등록

OAuth 클라이언트 사용자 인증 정보를 구성할 때는 인증 제공업체의 전용 콜백 리디렉션 URI를 등록해야 합니다.

  1. 다음 템플릿을 사용하여 리디렉션 URI를 구성합니다.

    https://iamconnectorcredentials.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/connectors/CONNECTOR_NAME/oauthcallback

    다음을 바꿉니다.

    • PROJECT_ID: 프로젝트 ID입니다. Google Cloud
    • LOCATION: The region where your auth provider will be deployed (for example,us-west1`).
    • CONNECTOR_NAME: 인증 제공업체의 이름입니다.

    예: https://iamconnectorcredentials.googleapis.com/v1/projects/my-project/locations/us-west1/connectors/bigquery-mcp-3lo-authprovider/oauthcallback

  2. 서비스 (예: BigQuery)에 연결하는 경우 콘솔에서 동의 화면을 구성하고 OAuth 클라이언트 사용자 인증 정보를 만들 수 있습니다. Google Cloud Google Cloud

    1. OAuth 동의 화면을 구성합니다.

      1. 콘솔에서 API 및 서비스>OAuth 동의 화면 페이지로 이동합니다. Google Cloud

        API 및 서비스>OAuth 동의 화면으로 이동

      2. 앱 정보 섹션에서 애플리케이션 이름(예: BigQuery 관리자 애플리케이션)과 지원 이메일을 입력합니다.
      3. 대상 섹션에서 내부 또는 외부를 선택합니다.
      4. 알림을 받을 연락처 정보를 입력합니다.
      5. Google API 서비스 사용자 데이터 정책을 읽고 동의합니다.
      6. 마침 을 클릭합니다.

    2. OAuth 클라이언트 사용자 인증 정보를 만듭니다.

      1. 콘솔에서 API 및 서비스>OAuth 동의 화면>클라이언트 페이지로 이동합니다. Google Cloud

        API 및 서비스>OAuth 동의 화면 >클라이언트로 이동

      2. 사용자 인증 정보 만들기 >OAuth 클라이언트 ID를 클릭합니다.
      3. 목록에서 웹 애플리케이션 옵션을 선택합니다.
      4. OAuth 클라이언트의 인식 가능한 이름을 입력합니다.
      5. 승인된 리디렉션 URI 섹션에서 URI 추가를 클릭하고 구성된 리디렉션 URI를 입력합니다.
      6. 만들기 를 클릭합니다. OAuth 클라이언트 생성됨 대화상자에서 생성된 클라이언트 ID 및 클라이언트 보안 비밀번호 값을 복사합니다.

에이전트 코드에서 인증

에이전트를 인증하려면 ADK를 사용하거나 Agent Identity API를 직접 호출하면 됩니다.

ADK

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

from google.adk.agents.llm_agent import LlmAgent
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())

# The URI to redirect the user to after consent is granted and the
# callback is received by the auth provider.
CONTINUE_URI = "https://YOUR_FRONTEND_URL/validateUserId"

# Create the Auth Provider scheme using the auth provider's full resource name.
auth_scheme = GcpAuthProviderScheme(
    name="projects/PROJECT_ID/locations/LOCATION/connectors/AUTH_PROVIDER_NAME",
    continue_uri=CONTINUE_URI
)

# 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 = LlmAgent(
    name