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

title, source_type, url, archive_url, status, confidence, tags, related_projects, related_branches, created, last_reviewed

title	source_type	url	archive_url	status	confidence	tags	related_projects	related_branches	created	last_reviewed
Google OpenID Connect Discovery 문서 (공식)	official-doc	https://accounts.google.com/.well-known/openid-configuration		raw	high	keycloak-patterns p2b-spa-google-federation google-oidc discovery jwks claim-mapping	keycloak-patterns	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	2026-05-25	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 요약: (미작성)