104 lines
8.9 KiB
Markdown
104 lines
8.9 KiB
Markdown
---
|
|
title: Keycloak — Google 외부 IdP 등록 절차 (Server Administration Guide)
|
|
source_type: official-doc
|
|
url: https://wjw465150.gitbooks.io/keycloak-documentation/content/server_admin/topics/identity-broker/social/google.html
|
|
archive_url:
|
|
status: raw
|
|
confidence: high
|
|
tags: [keycloak-patterns, p1b-edge-google-federation, idp-brokering, keycloak, google-oidc, official-doc, setup]
|
|
related_projects: [keycloak-patterns]
|
|
related_branches: [feature-keycloak-patterns, feature-keycloak-edge-forwardauth-google-federation, feature-keycloak-idp-brokering-google-client, feature-keycloak-google-redirect-uri-policy, feature-keycloak-google-claim-attribute-mapping]
|
|
created: 2026-05-25
|
|
last_reviewed: 2026-05-27
|
|
---
|
|
|
|
# Keycloak — Google 외부 IdP 등록 절차
|
|
|
|
> Layer: `raw/official-docs/` — Keycloak Server Admin Guide / "Identity Brokering / Social / Google" 발췌 (gitbook 미러 verbatim).
|
|
> P1B (Edge ForwardAuth + Google federation) 구현 시 admin console 등록 절차의 1차 근거.
|
|
|
|
## Parent / 활용 branch (필수)
|
|
|
|
| Branch | 이 자료가 정당화하는 결정 |
|
|
|---|---|
|
|
| [[raw/branch-notes/feature-keycloak-patterns]] | keycloak-patterns root — Google federation 채택 시 IdP 등록 양방향 (Google ↔ Keycloak) 필수 사실 |
|
|
| [[raw/branch-notes/feature-keycloak-edge-forwardauth-google-federation]] | P1B Edge ForwardAuth + Google federation 의 admin console 절차 baseline |
|
|
| [[raw/branch-notes/feature-keycloak-idp-brokering-google-client]] | Google IdP client 등록 시 Client ID/Secret + Redirect URI 의 정확한 양방향 흐름 |
|
|
| [[raw/branch-notes/feature-keycloak-google-redirect-uri-policy]] | Keycloak `/realms/<realm>/broker/google/endpoint` ↔ Google Cloud Console `Authorized redirect URIs` 매칭 정책 |
|
|
| [[raw/branch-notes/feature-keycloak-google-claim-attribute-mapping]] | default scope (`openid profile email`) 기반 attribute mapper 의 기본 입력 사실 |
|
|
|
|
## 컨텍스트 / 왜 저장했는지
|
|
|
|
P1B 구현 시 "Keycloak Admin Console → Identity Providers → Google" 등록의 정확한 절차와 필수 입력값 (Client ID / Client Secret / Redirect URI) 을 공식 기준으로 확보. 다이어그램에서 "Google client secret 을 Keycloak 이 보관" 이라 표기한 부분의 근거.
|
|
|
|
## 출처 / Source
|
|
|
|
- 원본 URL (gitbook 미러): https://wjw465150.gitbooks.io/keycloak-documentation/content/server_admin/topics/identity-broker/social/google.html
|
|
- 원본 source: `keycloak/keycloak` 저장소 `docs/documentation/server_admin/topics/identity-broker/social/google.adoc`
|
|
- 아카이브 URL: (미수집)
|
|
- 저자 / 조직: Keycloak (Red Hat)
|
|
- 발행일: gitbook 미러 (legacy docs)
|
|
- 마지막 확인일: 2026-05-27
|
|
|
|
## 핵심 인용 / Key quotes (verbatim)
|
|
|
|
> [§Identity Providers menu] "go to the `Identity Providers` left menu item and select `Google` from the `Add provider` drop down list"
|
|
|
|
> [§Client credentials] "you'll need to obtain a `Client ID` and `Client Secret` from Google"
|
|
|
|
> [§Redirect URI from Keycloak] "One piece of data you'll need from this page is the `Redirect URI`. You'll have to provide that to Google when you register Keycloak as a client there"
|
|
|
|
> [§Register in Google Cloud Console] "You'll also need to copy and paste the `Redirect URI` from the Keycloak `Add Identity Provider` page into the `Authorized redirect URIs` field"
|
|
|
|
> [§Default scopes] "By default, Keycloak uses the following scopes: `openid` `profile` `email`"
|
|
|
|
## Claims Extracted / 추출된 주장
|
|
|
|
| Claim ID | Claim (이 자료가 직접 말하는 것) | Evidence quote | Strength | Applies to | Does not prove |
|
|
|---|---|---|---|---|---|
|
|
| KC-GIDP-C1 | Keycloak admin console 좌측 메뉴의 `Identity Providers` 에서 `Add provider` 드롭다운으로 `Google` 을 선택하여 등록 시작 | [§Identity Providers menu] "go to the `Identity Providers` left menu item and select `Google` from the `Add provider` drop down list" | `official-vendor-doc` | Keycloak admin console UI (legacy / current 공통 명명) | 신규 admin console UI (v2) 의 정확한 navigation 경로가 동일하다는 뜻은 아님 — 별도 UI 검증 필요 |
|
|
| KC-GIDP-C2 | Keycloak 측 등록 전에 Google 로부터 `Client ID` 와 `Client Secret` 을 발급받아야 함 | [§Client credentials] "you'll need to obtain a `Client ID` and `Client Secret` from Google" | `official-vendor-doc` | Google OAuth 2.0 Client 발급 후 Keycloak Google IdP 등록 시나리오 | Google Cloud Console 의 정확한 발급 절차 (OAuth consent screen 설정 등) 는 본 인용 범위 밖 — Google 측 공식 문서 참조 |
|
|
| KC-GIDP-C3 | Keycloak 의 Add Identity Provider 페이지에서 표시되는 `Redirect URI` 값을 Google 에 등록해야 함 | [§Redirect URI from Keycloak] "One piece of data you'll need from this page is the `Redirect URI`. You'll have to provide that to Google when you register Keycloak as a client there" | `official-vendor-doc` | 양방향 등록 (Keycloak ↔ Google) 의 redirect URI 일관성 | redirect URI 의 정확한 path 형식 (`/realms/<realm>/broker/google/endpoint`) 은 본 인용에 명시 없음 — admin console UI 가 자동 표시 |
|
|
| KC-GIDP-C4 | Keycloak 의 `Redirect URI` 를 Google Cloud Console 의 `Authorized redirect URIs` 필드에 정확히 복사/붙여넣기 해야 함 | [§Register in Google Cloud Console] "You'll also need to copy and paste the `Redirect URI` from the Keycloak `Add Identity Provider` page into the `Authorized redirect URIs` field" | `official-vendor-doc` | Google Cloud Console OAuth 2.0 Client 의 redirect URI 등록 | wildcard / 부분 매칭 허용 여부 — Google 측 정책 (별도 `google-oauth2-redirect-uri-validation-official.md` 참조) |
|
|
| KC-GIDP-C5 | Keycloak 의 default scope 는 `openid`, `profile`, `email` 세 가지 (Default Scopes 에서 변경 가능) | [§Default scopes] "By default, Keycloak uses the following scopes: `openid` `profile` `email`" | `official-vendor-doc` | Google IdP 등록 시 attribute mapper 의 기본 입력 | 각 scope 가 Google 에서 정확히 어떤 claim 을 반환하는지는 본 인용에 없음 — Google OIDC spec 참조 |
|
|
|
|
## Usage Boundaries / 적용 경계
|
|
|
|
- **이 자료가 직접 증명하는 것**:
|
|
- `KC-GIDP-C1` ~ `C5`: Keycloak admin console 의 Google IdP 등록 절차 + 양방향 redirect URI 등록 + default scope (`openid profile email`)
|
|
- **이 자료가 증명하지 않는 것**:
|
|
- Google `email_verified` claim 의 기본 신뢰 정책 (Keycloak 이 자동 검증 vs 별도 validator 필요)
|
|
- Google `hd` (hosted domain) claim 활용 (기업 도메인 제한) — 별도 mapper / validator 결정
|
|
- `sub` claim 기반 매칭 vs `email` 기반 매칭의 정확한 토글 위치
|
|
- Client Secret rotation 시 Keycloak 측 재등록 절차
|
|
- oauth2-proxy 와의 redirect URI 충돌 / 분리 정책 (P1B 에선 oauth2-proxy 의 `/oauth2/callback` 과 Keycloak 의 `/broker/google/endpoint` 가 별도)
|
|
- **내 프로젝트에 적용하려면 추가 확인이 필요한 것**:
|
|
- admin console v2 (Keycloak 19+) 의 동일 경로 navigation 검증
|
|
- `https://<keycloak-host>/realms/<realm>/broker/google/endpoint` 의 정확한 path 형식 (host header + `KC_HTTP_RELATIVE_PATH` 의 결합)
|
|
- dev/staging/prod 환경 분리 시 각 환경별 별도 Google OAuth client 발급 vs 단일 client 다중 redirect URI 정책 결정
|
|
|
|
## 메모 / Notes (내 프로젝트 해석)
|
|
|
|
> 본 섹션은 자료 직접 인용 아님. P1B 결정 컨텍스트 해석.
|
|
|
|
- **설정 양방향성**: Google ↔ Keycloak 양쪽 모두에 등록 필요. Google 에는 Keycloak 의 `/broker/google/endpoint` 같은 redirect URI 등록, Keycloak 에는 Google 이 발급한 client credential 등록.
|
|
- **Redirect URI 형태**: Keycloak 는 보통 `https://<keycloak-host>/realms/<realm>/broker/google/endpoint`. P1B 에서 oauth2-proxy 의 redirect URI (`/oauth2/callback`) 와는 **별개** — proxy 는 Keycloak 만 보고, Google redirect 는 Keycloak 이 자체 처리.
|
|
- **보안 surface 확장 사실**:
|
|
- Google client secret 이 Keycloak DB (또는 vault) 에 저장됨 → 운영 책임.
|
|
- Google 측 redirect URI mismatch 는 Google 콘솔에서만 수정 가능 → 환경 (dev/staging/prod) 분리 시 각각 별도 OAuth client 권장.
|
|
- **Default scope**: `openid profile email` — `email` 없으면 First Login Flow 에서 email match 불가, 강제 Review Profile.
|
|
|
|
## Related / 관련
|
|
|
|
- 같은 주제 다른 official-doc:
|
|
- [[raw/official-docs/keycloak-identity-brokering-overview-official]]
|
|
- [[raw/official-docs/keycloak-identity-provider-mappers]]
|
|
- [[raw/official-docs/keycloak-first-login-flow]]
|
|
- [[raw/official-docs/google-oauth2-redirect-uri-validation-official]]
|
|
- 인용하는 branch:
|
|
- [[raw/branch-notes/feature-keycloak-edge-forwardauth-google-federation]] (P1B)
|
|
- [[raw/branch-notes/feature-keycloak-idp-brokering-google-client]]
|
|
- [[raw/branch-notes/feature-keycloak-google-redirect-uri-policy]]
|
|
- [[raw/branch-notes/feature-keycloak-google-claim-attribute-mapping]]
|
|
- 인용하는 wiki: (미작성)
|