이 가이드에서는 연결된 앱 플랫폼이 서비스에 액세스하도록 안전하게 승인하는 방법을 설명합니다. 연결된 앱 MCP 통합의 경우, 위임된 승인의 업계 표준인 OAuth 2.1과 Proof Key for Code Exchange(PKCE)를 함께 사용하여 사용자 데이터의 최고 수준의 보안과 '에이전트' 흐름의 안정성을 보장하는 것이 좋습니다. 연결된 앱 플랫폼은 PKCE(Proof Key for Code Exchange) 매개변수를 사용하여 승인 코드 부여 유형을 지원합니다.
PKCE는 모든 OAuth 2.1에서 필수이며 OAuth 2.0에서는 선택사항입니다.
자동 검색을 사용 설정하고 온보딩 프로세스를 간소화하려면 승인 서버가 OAuth 검색이라고도 하는 승인 서버 메타데이터 확장 프로그램을 지원해야 합니다.
Gemini MCP가 구성 JSON을 가져오는 방법
Gemini MCP 콘솔은 이 섹션에 표시된 순서대로 다음 URL에서 구성 JSON을 가져오려고 시도합니다.
승인 서버 URL이 도메인의 최상위 수준(예: https://auth.example.com)에 있는 경우 Gemini는 도메인에 표준 'well-known' 디렉터리를 추가하고 다음 순서로 서버를 찾습니다.
https://auth.example.com/.well-known/oauth-authorization-serverhttps://auth.example.com/.well-known/openid-configuration
승인 서버 URL이 도메인의 특정 하위 디렉터리 또는 경로(예: https://auth.example.com/realms/master) 내에 있는 경우 Gemini는 동일한 'well-known' 경로를 해당 하위 디렉터리에 직접 추가합니다.
.../realms/master/.well-known/oauth-authorization-server.../realms/master/.well-known/openid-configuration.../realms/master/.well-known/openid-configuration(중첩 경로 지원)
필수 JSON 기능
메타데이터 응답에는 다음 필드가 포함되어야 합니다. 필수 입력란이 누락되었거나 유효한 유형을 찾을 수 없으면 통합이 실패합니다.
authorization_endpoint- 유효한 문자열 URL이어야 합니다.
token_endpoint- 유효한 문자열 URL이어야 합니다.
response_types_supportedcode문자열을 포함해야 합니다.registration_endpoint현재 Play Console은 동적 클라이언트를 사용합니다.
등록(RFC 7591)을 지원합니다. 메타데이터에 등록 엔드포인트를 제공하거나 Play Console UI에 클라이언트 ID/비밀번호를 직접 입력해야 합니다.
승인 서버가 동적 클라이언트 등록(DCR)을 지원하지 않는 경우 Play Console UI 내에서 클라이언트 ID 및 클라이언트 보안 비밀번호 필드를 수동으로 구현하고 채워 통합을 완료해야 합니다.
구현에서 코드 교환용 증명 키(PKCE) 또는 영구 세션을 지원하는 경우 검색 JSON에 관련 기능 필드(예: Challenge Methods 및 Grant Types)를 포함해야 합니다. 이렇게 하면 Gemini의 보안 및 연결 표준과의 호환성을 보장할 수 있습니다. 범위를 지원하는 경우 scopes_supported 필드를 포함해야 합니다.
구성 예
다음은 고객의 요구사항을 충족하는 유효한 JSON 응답입니다.
{
"issuer": "https://auth.example.com",
"authorization_endpoint": "https://auth.example.com/oauth/authorize",
"token_endpoint": "https://auth.example.com/oauth/token",
"registration_endpoint": "https://auth.example.com/oauth/register",
"response_types_supported": [
"code",
"token",
"id_token"
],
"grant_types_supported": [
"authorization_code",
"refresh_token"
]
}
PKCE를 포함하는 경우 다음 스니펫은 JSON 블록에 포함될 수 있는 항목의 예를 보여줍니다.
"grant_types_supported": ["authorization_code", "refresh_token"],
"code_challenge_methods_supported": ["S256"]
scopes_supported 필드를 포함하는 경우 다음 스니펫은 JSON 블록에 포함될 수 있는 항목의 예를 보여줍니다.
"scopes_supported": ["mcp", "cart.order"],
승인 코드 플로우(간소화된 버전)
다음 단계에서는 표준 승인 코드 플로우를 간략하게 설명합니다. 이 시퀀스는 연결된 앱 플랫폼이 사용자를 대신하여 서버에서 필요한 액세스 토큰을 안전하게 가져오는 방법을 정확하게 보여줍니다.
승인 요청: Google 표시 경로에서 함수를 호출해야 한다고 판단하지만 사용자가 아직 승인되지 않았습니다. 챗봇은 사용자의 브라우저를 승인 엔드포인트로 리디렉션하거나 링크를 표시하여 흐름을 시작합니다.
이 요청에는 클라이언트 ID(또는 DCR로 자동 생성됨), Gemini 리디렉션 URI, 중요한 PKCE 매개변수(
code_challenge및code_challenge_method)가 포함됩니다.OAuth 설정을 위해 다음 URL을 허용 목록에 추가합니다.
https://oauth-redirect.googleusercontent.com/r/*https://oauth-redirect-sandbox.googleusercontent.com/r/*https://oauth-redirect-test.googleusercontent.com/r/*https://oauth-redirect.googleusercontent.com/a/*https://oauth-redirect-sandbox.googleusercontent.com/a/*https://oauth-redirect-test.googleusercontent.com/a/*
사용자 동의: 승인 서버가 요청을 검증하고, 사용자를 인증(로그인)하고, Google 표시 경로가 데이터 또는 서비스에 액세스할 수 있는 권한을 부여하도록 사용자에게 요청합니다.
코드 부여: 사용자가 동의하면 서버는 사용자의 브라우저를 Gemini RedirectURI로 다시 리디렉션하여 URL에 임시 승인 코드를 추가합니다.
토큰 교환: Gemini의 백엔드가 토큰 엔드포인트에
POST요청을 전송하여 승인 코드를 액세스 토큰으로 교환합니다.액세스 권한 부여됨: 토큰 엔드포인트가 코드와 PKCE 매개변수를 확인하고 액세스 토큰과 갱신 토큰(선택사항)을 발급하여 Gemini에 반환합니다.
주요 PKCE 요구사항
PKCE는 승인 코드의 무단 가로채기를 방지하는 보안 레이어를 추가합니다.
code_verifier: 흐름 시작 시 Gemini에서 생성한 암호화된 무작위 문자열입니다. 이 정보는 비공개로 유지됩니다.code_challenge:code_verifier의 변환으로, 일반적으로 SHA256 해싱입니다. 이는 승인 코드 플로우의 1단계에 설명된 대로 공개적으로 전송됩니다.- 검증: 토큰 엔드포인트(승인 코드 플로우의 4단계에 설명됨)는 수신된
code_verifier가 변환될 때 원래code_challenge와 일치하는지 검증해야 합니다.
디버깅
로그 탐색기에서 자세한 연결 오류 정보를 확인할 수 있습니다. 오류를 사용 설정하고 보려면 Google Console 프로젝트에서 계정 연결 오류 모니터링의 안내를 따르세요.
Google 계정 연결 구성 요구사항
Google 계정 연결 구성에 관한 자세한 내용은 다음 API 가이드를 참고하세요.
OAuth 통합을 성공적으로 등록하려면 승인 서버에 대한 특정 세부정보를 구성해야 합니다. 다음 엔드포인트, 사용자 인증 정보, 애셋이 준비되어 있는지 확인합니다.
구성 필드 |
설명 |
개발자 책임 |
클라이언트 ID 및 보안 비밀번호 |
승인 서버에서 연결된 앱 플랫폼 전용으로 생성하는 고유한 사용자 인증 정보입니다. 클라이언트 보안 비밀번호는 클라이언트 ID와 연결된 보안 사용자 인증 정보(비밀번호)입니다. 참고: 개발자가 클라이언트 ID를 발급한 경우 이를 제공해야 합니다. Google에서 클라이언트 ID를 발급한 경우 개발자는 보안 비밀을 등록하거나 확인해야 할 수 있습니다. |
모든 승인 요청에 플랫폼에서 제공한 ID를 사용합니다. |
승인 엔드포인트 |
사용자를 리디렉션하여 인증하고 동의를 부여하는 URL |
엔드포인트를 호스팅합니다(예: |
토큰 엔드포인트 |
승인 코드를 액세스/갱신 토큰으로 교환하고 만료된 토큰을 갱신하는 백엔드 엔드포인트입니다. |
이 엔드포인트를 호스팅합니다(예: https://yourdomain.com/oauth/token). |
취소 엔드포인트 |
사용자가 연결을 해제할 때 토큰을 무효화하도록 시스템에 알리는 URL입니다. 사용자가 연결된 앱 플랫폼 내에서 통합을 연결 해제하거나 연결을 끊으면 액세스 또는 갱신 토큰이 포함된 /revoke 엔드포인트에 POST 요청이 전송됩니다. |
엔드포인트를 호스팅합니다(예: 서버는 제공된 토큰을 영구적으로 무효화하여 이 요청을 처리해야 합니다. 이렇게 하면 연결된 앱 플랫폼에서 해당 토큰을 사용하려는 후속 시도가 실패하여 연결 해제 후에도 사용자의 데이터가 안전하게 보호됩니다. |
리디렉션 URI |
동의 후 승인 서버가 코드를 다시 전송하는 플랫폼에서 제공하는 특정 콜백 URL입니다. |
플랫폼에서 공식적으로 등록된 리디렉션 URI만 허용하도록 승인 서버를 구성합니다. |
새로고침하기 |
현재 액세스 토큰이 만료되면 연결된 앱 플랫폼에서 새 액세스 토큰을 가져올 수 있도록 하는 메커니즘으로, 사용자가 반복적으로 로그인하지 않아도 통합이 원활하게 연결된 상태를 유지합니다. 기존 액세스 토큰이 만료되면 연결된 앱 플랫폼에서 자동으로 |
서버는 제공된 갱신 토큰을 검증하고 JSON 응답에 새 액세스 토큰을 반환해야 합니다. 또한 영구 연결을 구현하려면 이 교환 중에 갱신 토큰을 순환하지 않아야 합니다. 새 갱신 토큰을 발급하는 대신 JSON 응답에서 정확히 동일한 갱신 토큰을 반환하고 백엔드에서 만료일을 연장합니다. |
응답 유형 |
승인 코드 플로우를 지원하려면 CODE로 구성해야 합니다. |
|
범위 |
토큰이 수행할 수 있는 작업을 정의하는 특정 권한 및 액세스 수준의 집합입니다. 초기 승인 핸드셰이크 중에 Google에서 요청할 수 있도록 구성에서 미리 정의해야 합니다. |
연결된 앱 플랫폼에서 흐름을 시작할 때 요청해야 하는 기본 범위 목록(예: 요청된 범위는 가능한 한 축소되어야 하지만(최소 권한의 원칙) MCP 통합에서 지원하는 중요 사용자 여정(CUJ)에 충분해야 합니다. |
UI 애셋: 로고 |
계정 연결 및 동의 화면에 표시할 개발자 로고입니다. |
원형 모양의 정사각형 벡터 이미지(SVG)여야 하며 500x500픽셀 이상이어야 합니다. 예를 들어 |
네이티브 앱 연결(앱 전환) |
네이티브 Android 또는 iOS 애플리케이션에서 직접 계정 연결을 지원하려면 표준 웹뷰를 사용하지 않는 것이 좋습니다. 대신 원활한 사용자 환경을 위해 앱 전환을 구현하는 것이 좋습니다. |
Play 스토어 및 App Store 인증을 완료하고 Google의 리디렉션 URI를 네이티브 애플리케이션에 직접 삽입하여 안전한 앱 간 승인 전환을 보장합니다. |
토큰 수명 |
(선택사항) 새로고침이 필요하기 전에 액세스 토큰이 유효한 기간입니다. GAL에서 제한 시간 정책을 구성하는 데 유용합니다. |
일반적인 만료 시간은 보안 요구사항에 따라 몇 분, 몇 시간, 며칠까지 다양합니다(예: |
일반적인 통합 오류
다음은 통합 프로세스에 적용되는 일반적인 오류와 가능한 해결 방법 목록입니다.
- 'code' 권한 부여 누락: Gemini 플랫폼의 자동화 시스템은 response_types_supported에서 'code' 값을 명시적으로 확인합니다.
- 등록 엔드포인트 누락: 서버가 클라이언트 ID 메타데이터 문서를 지원하더라도 Gemini 앱(서버에 연결하는 OAuth 클라이언트 역할)은 현재 탐색 JSON에 전용 registration_endpoint가 있어야 합니다.
- 200 이외의 오류: Gemini의 자동 메타데이터 검색 메커니즘이 well-known URL에 도달하여 404 또는 500을 수신하면 다른 URL을 추측하려고 시도하지 않습니다. Discovery URL이 공개적으로 액세스 가능한지 확인하세요.