donghyeon.kang/llm-wiki
1
0
Fork 0
Code Issues Pull Requests Projects Releases Wiki Activity
Files
d71669eb596d920964bf3ec3d77ad07278b30d96
llm-wiki/raw/official-docs/google-openid-connect-oidc.md
T

9.7 KiB
Raw Blame History

title, source_type, url, archive_url, related_projects, related_branches, tags, status, confidence, created, last_reviewed
title source_type url archive_url related_projects related_branches tags status confidence created last_reviewed
Google Identity — OpenID Connect (OIDC) 공식 문서 official-doc https://developers.google.com/identity/openid-connect/openid-connect
keycloak-patterns
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
keycloak-patterns
p1b-edge-google-federation
idp-brokering
google-oidc
oidc
official-doc
raw high 2026-05-25 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

핵심 인용 / 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 / 관련

Reference in New Issue View Git Blame Copy Permalink