llm-wiki/raw/official-docs/google-oidc-discovery-spec.md

---
title: Google OpenID Connect Discovery 문서 (공식)
source_type: official-doc
url: https://accounts.google.com/.well-known/openid-configuration
archive_url:
status: raw
confidence: high
tags: [keycloak-patterns, p2b-spa-google-federation, google-oidc, discovery, jwks, claim-mapping]
related_projects: [keycloak-patterns]
related_branches: [feature-keycloak-internal-spa-direct-google-federation, feature-keycloak-idp-brokering-google-client, feature-keycloak-google-claim-attribute-mapping, feature-keycloak-first-broker-login-flow]
created: 2026-05-25
last_reviewed: 2026-05-27
---

# Google OpenID Connect Discovery

> Layer: `raw/official-docs/` — Google OIDC discovery document + 공식 OpenID Connect 가이드 발췌. Keycloak이 Google을 IdP로 brokering할 때의 endpoint·scope·claim 표준.

## Parent / 활용 branch (필수)

| Branch | 이 자료가 정당화하는 결정 |
|---|---|
| [[raw/branch-notes/feature-keycloak-internal-spa-direct-google-federation]] | SPA Direct + Google federation에서 Keycloak이 Google discovery URL을 fetch하여 IdP 구성하는 근거 |
| [[raw/branch-notes/feature-keycloak-idp-brokering-google-client]] | Keycloak Google IdP client 등록 시 `authorization_endpoint`/`token_endpoint`/`jwks_uri` 채워야 하는 값의 근거 |
| [[raw/branch-notes/feature-keycloak-google-claim-attribute-mapping]] | `sub` / `email` / `email_verified` / `picture` / `name` / `hd` claim을 Keycloak user attribute로 매핑하는 근거 |
| [[raw/branch-notes/feature-keycloak-first-broker-login-flow]] | first broker login flow에서 `email_verified`·`sub` 기반 user linking 결정 근거 |

## 컨텍스트

Keycloak이 Google을 외부 IdP로 등록하면 discovery URL (`https://accounts.google.com/.well-known/openid-configuration`) 을 fetch하여 endpoint와 JWKS를 자동 구성한다. 본 raw는 그 discovery document와 OIDC 통합 시 사용하는 scope/claim 표준의 발췌 기록.

## 출처 / Source

- 원본 URL (discovery): https://accounts.google.com/.well-known/openid-configuration
- 보조 URL (가이드): https://developers.google.com/identity/openid-connect/openid-connect
- 아카이브 URL: (미수집)
- 저자 / 조직: Google — Identity Platform Documentation
- 발행일: rolling docs (discovery document는 live JSON)
- 마지막 확인일: 2026-05-27 (WebFetch 재검증 완료 — discovery JSON 6필드 verbatim MATCH; 가이드 5개 quote 중 3개 verbatim MATCH, 2개 (nonce, hd) 는 라이브 본문이 다른 표현, 2026-05-27 verified 본 추가)

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

### Discovery Document 필드 (verbatim JSON, 2026-05-27 verified MATCH 6개 모두)

> [discovery JSON, 2026-05-27 verified] `"issuer": "https://accounts.google.com"`

> [discovery JSON, 2026-05-27 verified] `"authorization_endpoint": "https://accounts.google.com/o/oauth2/v2/auth"`

> [discovery JSON, 2026-05-27 verified] `"token_endpoint": "https://oauth2.googleapis.com/token"`

> [discovery JSON, 2026-05-27 verified] `"userinfo_endpoint": "https://openidconnect.googleapis.com/v1/userinfo"`

> [discovery JSON, 2026-05-27 verified] `"jwks_uri": "https://www.googleapis.com/oauth2/v3/certs"`

> [discovery JSON, 2026-05-27 verified] `"id_token_signing_alg_values_supported": ["RS256"]`

### Scope / Claim / Validation 설명 (보조 가이드)

> [OpenID Connect guide — scope, 2026-05-27 verified MATCH] "The scope parameter must begin with the `openid` value and then include the `profile` value, the `email` value, or both."

> [OpenID Connect guide — nonce, 2026-05-25 capture — paraphrase] "The nonce parameter is required ... enables replay protection when present."

> [OpenID Connect guide — nonce, 2026-05-27 verified verbatim] "`nonce` (Required) A random value generated by your app that enables replay protection."

> [OpenID Connect guide — sub claim, 2026-05-27 verified MATCH] "`sub`: An identifier for the user, unique among all Google Accounts and never reused."

> [OpenID Connect guide — hd claim, 2026-05-25 capture — paraphrase] "hd: Domain claim for Google Workspace users."

> [OpenID Connect guide — hd claim, 2026-05-27 verified verbatim] "The domain associated with the Google Workspace or Cloud organization of the user."

> [OpenID Connect guide — token validation, 2026-05-27 verified MATCH] "For production purposes, retrieve Google's public keys from the keys endpoint and perform the validation locally."

## Claims Extracted / 추출된 주장

| Claim ID | Claim (이 자료가 직접 말하는 것) | Evidence quote | Strength | Applies to | Does not prove |
|---|---|---|---|---|---|
| GOOGLE-OIDC-C1 | Google OIDC issuer는 `https://accounts.google.com` | [discovery JSON] `"issuer": "https://accounts.google.com"` | `official-vendor-doc` | Keycloak Google IdP의 issuer URL 검증 / ID token `iss` claim 비교 | `accounts.google.com` 외 alias가 사용된다는 뜻은 아님 — `iss` 비교는 정확히 이 문자열로 |
| GOOGLE-OIDC-C2 | Google OIDC endpoint URL: `authorization_endpoint = https://accounts.google.com/o/oauth2/v2/auth`, `token_endpoint = https://oauth2.googleapis.com/token`, `userinfo_endpoint = https://openidconnect.googleapis.com/v1/userinfo`, `jwks_uri = https://www.googleapis.com/oauth2/v3/certs` | [discovery JSON] 위 4개 필드 | `official-vendor-doc` | Keycloak Google IdP 수동 등록 / OAuth client 라이브러리 설정 | 각 endpoint의 SLA / rate limit / 응답 schema 디테일은 별도 페이지 |
| GOOGLE-OIDC-C3 | Google ID token 서명 알고리즘은 `RS256`만 지원 | [discovery JSON] `"id_token_signing_alg_values_supported": ["RS256"]` | `official-vendor-doc` | ID token signature verification 시 알고리즘 선택 | ES256 / EdDSA 같은 다른 알고리즘이 향후 추가될 가능성은 본 시점 인용에선 불확실 |
| GOOGLE-OIDC-C4 | OIDC scope는 `openid` 로 시작하고 `profile`, `email` 중 하나 이상 포함해야 함 | [OpenID Connect guide — scope] "The scope parameter must begin with the openid value and then include the profile value, the email value, or both." | `official-vendor-doc` | Google OIDC authorization request 의 scope 파라미터 | 기타 scope (`https://www.googleapis.com/auth/...`) 추가 가능성은 본 인용에 직접 없음 — OAuth scope spec에서 별도 |
| GOOGLE-OIDC-C5 | `nonce` 파라미터는 required, replay 보호 목적 | [OpenID Connect guide — nonce, 2026-05-27 verified] "`nonce` (Required) A random value generated by your app that enables replay protection." | `official-vendor-doc` | Authorization request 의 `nonce` 처리 | nonce 생성/검증의 길이/엔트로피 권고는 본 인용 직접 다루지 않음 — OIDC core spec 참조 |
| GOOGLE-OIDC-C6 | `sub` claim은 Google Account 전역에서 unique하고 재사용되지 않음 | [OpenID Connect guide — sub claim, 2026-05-27 verified] "`sub`: An identifier for the user, unique among all Google Accounts and never reused." | `official-vendor-doc` | Keycloak first broker login의 user linking 정책 / DB primary key 설계 | "use sub, not email" 권고 절은 라이브 본문에서 본 sub 정의문에 직접 따라붙지 않음 — 별도 단락. email 변경 가능성은 본 quote 직접 다루지 않음 |
| GOOGLE-OIDC-C7 | `hd` claim은 user 의 Google Workspace 또는 Cloud organization 과 연관된 도메인 | [OpenID Connect guide — hd claim, 2026-05-27 verified] "The domain associated with the Google Workspace or Cloud organization of the user." | `official-vendor-doc` | Workspace 도메인 제한 정책 (특정 회사 도메인만 허용) | personal Google account 의 `hd` 값 부재 처리는 본 인용에 명시 없음 — 누락 시 null/없음으로 추정 (검증 필요) |
| GOOGLE-OIDC-C8 | Production 환경에서 Google public key를 keys endpoint에서 받아 **로컬 검증** 권장 | [OpenID Connect guide — token validation] "For production purposes, retrieve Google's public keys from the keys endpoint and perform the validation locally." | `official-vendor-doc` | ID token 검증 deployment | Google의 `tokeninfo` endpoint 사용은 dev/디버깅용만 권장 — 본 인용 직접 다루지 않으나 "locally" 권고에서 유추 가능 |

## Usage Boundaries / 적용 경계

- **이 자료가 직접 증명하는 것**:
  - `GOOGLE-OIDC-C1`~`C3`: Google OIDC discovery document의 issuer, 4개 endpoint, RS256 서명 알고리즘
  - `GOOGLE-OIDC-C4`~`C5`: scope 필수 값과 nonce required 정책
  - `GOOGLE-OIDC-C6`~`C8`: `sub` claim primary key 권고, `hd` claim Workspace 의미, ID token 로컬 검증 권고
- **이 자료가 증명하지 않는 것**:
  - Keycloak이 5단계 검증 (signature / iss / aud / exp / hd) 을 정확히 어떤 단계로 수행하는지 (Keycloak vendor 문서 참조)
  - `email_verified` 가 false인 user 처리 정책 (first broker login flow 설정 결정)
  - `picture`, `name`, `family_name`, `given_name` claim의 인코딩/언어 규칙
  - Workspace user의 `hd` claim 부재 / 잘못된 값일 때 동작
  - Google이 향후 ES256 등 알고리즘을 추가할 가능성 / RS256 deprecation timeline
- **내 프로젝트에 적용하려면 추가 확인이 필요한 것**:
  - Keycloak Google IdP가 `.well-known` 을 자동 fetch하는지 vs 수동 endpoint 입력해야 하는지 (vendor 옵션)
  - Keycloak이 발급한 access token이 Google ID token claim을 어떻게 포함/변환하는지 (claim-to-claim mapper 설정)
  - first broker login flow에서 `email_verified=true` AND `sub=...` 기반 자동 link vs 수동 confirmation 선택

## P2B 패턴에서 의미 (내 프로젝트 해석)

> 본 섹션은 자료 직접 인용이 아닌 패턴 결정 컨텍스트 해석. wiki 추출 시 옮겨야 함.

- Keycloak의 Google IdP 설정 시 이 discovery URL 그대로 사용 가능 (Keycloak이 `.well-known` 자동 fetch 지원).
- Keycloak이 5단계 검증을 내부적으로 수행. 백엔드는 **Google ID token을 직접 검증하지 않음** — Keycloak이 발급한 access token만 검증.
- claim mapping에서 사용되는 주요 필드:
  - `sub` → Keycloak user의 `federated identity ID`
  - `email`, `email_verified` → Keycloak user `email` 속성 + first broker login flow의 link 기준
  - `picture`, `name` → Keycloak user attribute / custom claim
  - `hd` → 정책 게이트 (특정 도메인만 허용)

### ID Token 검증 5단계 (Google 공식 권고 — 발췌 요약)

1. signature를 Google certificates (JWKS)로 검증
2. `iss` == `https://accounts.google.com`
3. `aud` == client_id
4. `exp` 만료 확인
5. `hd` claim 확인 (Workspace 제한 시)

> 위 5단계는 user 기존 raw에 정리된 내용. Google 공식 가이드의 verbatim block 인용은 본 raw에 포함되지 않았으므로 (단계별 문장 발췌 없음), production 적용 시 `GOOGLE-OIDC-C8` 의 "perform the validation locally" 권고 + OpenID Connect Core §3.1.3.7 의 표준 5단계와 교차 확인 필요.

## 메모 / Notes

- 2026-05-27 re-verification: WebFetch 재확인 완료. Discovery JSON 6 필드 verbatim MATCH (issuer/4 endpoints/id_token_signing_alg_values_supported). 가이드 quote 중 scope, sub, token validation 은 verbatim MATCH. nonce 와 hd 는 2026-05-25 capture 가 paraphrase 였음 — 라이브 verbatim quote 를 추가 보존하고 Claims 표의 Evidence quote 도 라이브 표현으로 교체. 의미는 동일하므로 strength 유지.
- `scopes_supported`, `claims_supported`, `response_types_supported` 등 추가 필드는 user 기존 raw에 table로 정리되어 있으나 원문 verbatim 인용으로 보존하기 어려운 형식 — Claims 표에선 명시적 quote가 있는 3개 핵심 필드(`issuer`, 4개 endpoint, `id_token_signing_alg_values_supported`)만 채택.

## Related / 관련

- 같은 주제 다른 official-doc:
  - [[raw/official-docs/keycloak-identity-brokering-overview-official]]
- 인용하는 branch:
  - [[raw/branch-notes/feature-keycloak-internal-spa-direct-google-federation]]
  - [[raw/branch-notes/feature-keycloak-idp-brokering-google-client]]
  - [[raw/branch-notes/feature-keycloak-google-claim-attribute-mapping]]
  - [[raw/branch-notes/feature-keycloak-first-broker-login-flow]]
- 인용한 wiki 요약: (미작성)