llm-wiki/raw/official-docs/google-openid-connect-oidc.md

---
title: Google Identity — OpenID Connect (OIDC) 공식 문서
source_type: official-doc
url: https://developers.google.com/identity/openid-connect/openid-connect
archive_url:
related_projects: [keycloak-patterns]
related_branches: [feature-keycloak-patterns, feature-keycloak-edge-forwardauth-google-federation, feature-keycloak-idp-brokering-google-client, feature-keycloak-google-claim-attribute-mapping, feature-keycloak-account-linking-sub-vs-email]
tags: [keycloak-patterns, p1b-edge-google-federation, idp-brokering, google-oidc, oidc, official-doc]
status: raw
confidence: high
created: 2026-05-25
last_reviewed: 2026-05-27
---

# Google Identity — OpenID Connect (OIDC) 공식 문서

> Layer: `raw/official-docs/` — Google Identity Platform "OpenID Connect" 페이지 verbatim.
> P1B 토큰 교환 8단계 sequence 의 5–7번 단계 (Keycloak ↔ Google `authorize`/`token` endpoint) + ID token claim (`sub`, `email`) 매핑 정책의 1차 근거.

## Parent / 활용 branch (필수)

| Branch | 이 자료가 정당화하는 결정 |
|---|---|
| [[raw/branch-notes/feature-keycloak-patterns]] | keycloak-patterns root — Google 이 외부 IdP 로 federation 될 때 OIDC 가 사용된다는 사실 |
| [[raw/branch-notes/feature-keycloak-edge-forwardauth-google-federation]] | P1B Edge + Google federation sequence 의 step 5–7 (Keycloak → Google `authorize` → callback `code` → `/token` 교환) 의 정확한 endpoint URL 근거 |
| [[raw/branch-notes/feature-keycloak-idp-brokering-google-client]] | Keycloak 의 Google IdP client 등록 시 Discovery document (`https://accounts.google.com/.well-known/openid-configuration`) 사용 결정 근거 |
| [[raw/branch-notes/feature-keycloak-google-claim-attribute-mapping]] | Google ID token claim → Keycloak user attribute 매핑 시 `sub` 가 영구 식별자 + `email` 은 unique identifier 로 사용 금지의 1차 근거 |
| [[raw/branch-notes/feature-keycloak-account-linking-sub-vs-email]] | "email = primary identifier 로 사용 금지" 공식 경고 → Keycloak mapper 가 `sub` 기반 매칭으로 전환하는 결정 근거 |

## 컨텍스트

P1B 에서 Keycloak 이 외부 IdP 로 등록하는 대상이 Google. Keycloak 이 redirect 하는 Google `authorize` endpoint, code → token 교환에 쓰는 `/token` endpoint, 그리고 Keycloak 이 받아 매핑할 ID token claim (`sub`, `email`) 을 **공식 기준**으로 확보. 토큰 교환 sequence 의 5–7번 단계의 1차 근거. `sub` 가 영구 식별자라는 명시적 공식 경고가 `feature-keycloak-account-linking-sub-vs-email` 의 결정 근거.

## 출처 / Source

- 원본 URL: https://developers.google.com/identity/openid-connect/openid-connect
- 아카이브 URL: (미수집)
- 저자 / 조직: Google Identity Platform
- 발행일: rolling docs
- 마지막 확인일: 2026-05-27

## 핵심 인용 / Key quotes (verbatim)

> [§Send an authentication request to Google] "The following discussion assumes the base URI is `https://accounts.google.com/o/oauth2/v2/auth`."

> [§Exchange `code` for access token and ID token] "The `POST` request is sent to the token endpoint, which you should retrieve from the Discovery document using the `token_endpoint` metadata value. The following discussion assumes the endpoint is `https://oauth2.googleapis.com/token`."

> [§An ID token's payload] "When implementing your account management system, you **shouldn't** use the `email` field in the ID token as a unique identifier for a user. Always use the `sub` field as it is unique to a Google Account even if the user changes their email address."

> [§Google ID Tokens — Claims Table] "The user's email address. Provided only if you included the `email` scope in your request."

> [§The Discovery document] "The Discovery document for Google's OpenID Connect service may be retrieved from: `https://accounts.google.com/.well-known/openid-configuration`"

## Claims Extracted / 추출된 주장

| Claim ID | Claim (이 자료가 직접 말하는 것) | Evidence quote | Strength | Applies to | Does not prove |
|---|---|---|---|---|---|
| GOIDC-C1 | Google 의 OIDC authorization endpoint 의 base URI 는 `https://accounts.google.com/o/oauth2/v2/auth` | [§Send an authentication request to Google] "The following discussion assumes the base URI is `https://accounts.google.com/o/oauth2/v2/auth`." | `official-vendor-doc` | Google Identity Platform OIDC integration | 이 URL 이 항상 고정이라는 뜻 아님 — 공식 권장은 Discovery document 의 `authorization_endpoint` 값 사용 |
| GOIDC-C2 | Google 의 OIDC token endpoint 는 `https://oauth2.googleapis.com/token`; POST 요청으로 code 교환 수행 | [§Exchange `code` for access token and ID token] "The `POST` request is sent to the token endpoint, which you should retrieve from the Discovery document using the `token_endpoint` metadata value. The following discussion assumes the endpoint is `https://oauth2.googleapis.com/token`." | `official-vendor-doc` | Google OIDC code flow | refresh token 의 정확한 lifetime / rotation 정책은 본 인용 범위 밖 |
| GOIDC-C3 | ID token 의 `sub` 가 영구 식별자; `email` 을 unique identifier 로 사용 금지 (**공식 권고**) — 이유: 사용자가 email 변경해도 `sub` 는 동일 | [§An ID token's payload] "When implementing your account management system, you **shouldn't** use the `email` field in the ID token as a unique identifier for a user. Always use the `sub` field as it is unique to a Google Account even if the user changes their email address." | `official-vendor-doc` | Google ID token 사용자 매핑 정책 | `sub` 가 cross-IdP 에서도 unique 라는 뜻 아님 — Google 계정 내에서만 unique |
| GOIDC-C4 | `email` claim 은 `email` scope 를 request 에 포함했을 때에만 제공 | [§Google ID Tokens — Claims Table] "The user's email address. Provided only if you included the `email` scope in your request." | `official-vendor-doc` | Google OIDC scope 요청 정책 | `email_verified` claim 의 의미/제공 조건은 본 인용 범위 밖 (claims table 의 별도 행) |
| GOIDC-C5 | Google OIDC Discovery document 의 정확한 URL 은 `https://accounts.google.com/.well-known/openid-configuration` | [§The Discovery document] "The Discovery document for Google's OpenID Connect service may be retrieved from: `https://accounts.google.com/.well-known/openid-configuration`" | `official-vendor-doc` | Google OIDC discovery 사용 (Keycloak IdP "Use discovery endpoint" 설정 포함) | Discovery document 의 모든 metadata 키의 완전한 목록은 본 인용 범위 밖 |

## Usage Boundaries / 적용 경계

- **이 자료가 직접 증명하는 것**:
  - `GOIDC-C1`/`C2`: Google authorize/token endpoint 의 정확한 URL (P1B 8단계 sequence 의 step 5/7 endpoint 확정)
  - `GOIDC-C3`: `sub` 가 영구 식별자 + `email` 을 unique identifier 로 쓰지 말라는 **공식 경고** (P1B account linking 결정 근거)
  - `GOIDC-C4`: `email` claim 은 `email` scope 가 있어야 받음 (Keycloak Google IdP scope 설정의 근거)
  - `GOIDC-C5`: Discovery document URL (Keycloak "Use discovery endpoint" 한 줄 설정 근거)
- **이 자료가 증명하지 않는 것**:
  - `email_verified=false` 인 Google 계정의 처리 방침 (별도 claims table 항목 / IdP 측 verification 정책)
  - Google refresh token rotation / TTL 의 정확한 값
  - Keycloak 의 First Login Flow 가 `sub` 매칭을 자동 수행한다는 뜻 — Keycloak side 의 별도 mapper 설정 필요 (`keycloak-identity-provider-mappers` 참조)
  - PKCE 강제 여부 (Google OAuth 2.0 별도 페이지)
- **내 프로젝트에 적용하려면 추가 확인이 필요한 것**:
  - Keycloak Google IdP 설정에서 Discovery URL 입력 위치 (Admin Console > Identity Providers > Google > Use discovery endpoint)
  - Keycloak mapper: Google `sub` claim → Keycloak `username` 또는 `federated identity` 매핑의 정확한 mapper type (Attribute Importer / Username Template Importer)
  - Authorized redirect URI 등록 시 Keycloak callback 경로 (`/realms/<realm>/broker/google/endpoint`) 의 정확한 형태

## 메모 / Notes (내 프로젝트 해석)

> 본 섹션은 자료 직접 인용 아님. P1B 결정 컨텍스트 해석.

- **P1B 토큰 흐름 5-7 단계 근거**:
  - 5: Keycloak → Google `authorize` (`https://accounts.google.com/o/oauth2/v2/auth`) — `GOIDC-C1`.
  - 6: 사용자 Google 로그인 → Google → Keycloak callback (`code` 전달).
  - 7: Keycloak → Google `/token` (`https://oauth2.googleapis.com/token`), Google ID token + access token 수신 — `GOIDC-C2`.
- **사용자 매핑 시 주의**: 공식 문서가 명시한 대로 (`GOIDC-C3`) **`email` 을 primary identifier 로 사용 금지**. `sub` 가 영구 식별자. Keycloak 의 First Login Flow 에서 email match 로 기존 계정에 자동 연결하는 것은 보안 위험 (Keycloak 공식 문서도 동일 경고 → `keycloak-first-login-flow.md` 의 `KC-FLF-C2`).
- **Discovery 활용**: Keycloak Google IdP 설정은 보통 Discovery URL 한 줄로 endpoint 일괄 가져옴 (`GOIDC-C5`). 수동 URL 입력 시에는 `C1`/`C2` 의 두 endpoint 사용.
- **scope**: Keycloak default = `openid profile email`. ID token 의 `email` claim 받으려면 `email` scope 필수 (`GOIDC-C4`).

## Related / 관련

- 같은 주제 다른 official-doc:
  - [[raw/official-docs/google-oidc-discovery-spec]]
  - [[raw/official-docs/google-oauth2-redirect-uri-validation-official]]
  - [[raw/official-docs/keycloak-first-login-flow]] (security warning 동일 주제 — email 자동 link 의 위험)
- 인용하는 branch:
  - [[raw/branch-notes/feature-keycloak-patterns]] (root)
  - [[raw/branch-notes/feature-keycloak-edge-forwardauth-google-federation]] (P1B)
  - [[raw/branch-notes/feature-keycloak-account-linking-sub-vs-email]]
- 인용하는 wiki: (미작성)