Files

T

DongHyeonka d71669eb59 fix: 하네스 제거 및 keycloak 문서 보강

2026-07-25 12:53:13 +09:00

10 KiB

Raw Permalink Blame History

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

title

source_type

url

archive_url

related_branches

related_projects

Keycloak — Client-suggested Identity Provider (kc_idp_hint, official)

Layer: raw/official-docs/ — Keycloak 공식 Server Administration Guide 의 "Client-suggested Identity Provider" 섹션(identity-broker/suggested.adoc) 원문 발췌. kc_idp_hint 쿼리 파라미터로 Keycloak 로그인 화면을 bypass 하는 메커니즘의 공식 정의.

Parent / 활용 branch (필수, 최소 1개+)

Branch	이 자료가 정당화하는 결정
raw/branch-notes/feature-keycloak-federation-spa-zero-change	D1의 비교 대안 — SPA(OIDC client)가 Keycloak 로그인 화면을 건너뛰고 특정 IdP를 강제하려면 `kc_idp_hint` 쿼리 파라미터(= SPA 코드 변경)가 필요함을 확정. 이는 이 branch가 채택하지 않은 대안(zero-change 위반)이며, D1의 "선택 조건"(언제 기본 화면 vs 언제 idpHint)의 근거.

출처 / Source

원본 URL: https://github.com/keycloak/keycloak/blob/main/docs/documentation/server_admin/topics/identity-broker/suggested.adoc
실제 발췌 소스(raw): https://raw.githubusercontent.com/keycloak/keycloak/main/docs/documentation/server_admin/topics/identity-broker/suggested.adoc (blob 뷰의 원문과 동일 — 저장소 main 브랜치 소스 파일)
아카이브 URL: (미수집)
저자 / 조직: Keycloak (Red Hat) — Server Administration Guide, Identity Brokering 챕터
발행일: rolling docs (git 히스토리 기반, 특정 릴리즈 날짜 미표기)
마지막 확인일: 2026-07-16

왜 저장했는지 / Why archived

feature-keycloak-federation-spa-zero-change branch 의 D1(SPA는 idpHint 미사용, Keycloak 기본 로그인 화면에 위임)은 "SPA가 특정 IdP를 강제하려면 어떤 코드 변경이 필요한가"를 비교 대안으로 명시해야 완전하다. 이 자료는 그 대안 — kc_idp_hint 쿼리 파라미터 — 의 공식 정의·JS adapter 사용법·기본 동작(빈 값 시 자동 redirect 비활성화)을 제공한다.

핵심 인용 / Key quotes (verbatim, 5문장)

[§Client-suggested Identity Provider, line 5] "OIDC applications can bypass the {project_name} login page by hinting at the identity provider they want to use. You can enable this by setting the kc_idp_hint query parameter in the Authorization Code Flow authorization endpoint."

[§Client-suggested Identity Provider, line 13 (예제 요청)] "GET /myapplication.com?kc_idp_hint=facebook HTTP/1.1"

[§Client-suggested Identity Provider, line 17] "In this case, your realm must have an identity provider with a facebook alias. If this provider does not exist, the login form is displayed."

[§Client-suggested Identity Provider, line 19 + code block lines 29–30 (JavaScript adapter 예제)] "If you are using the JavaScript adapter, you can also achieve the same behavior as follows:" ... await keycloak.createLoginUrl({ / idpHint: 'facebook' / });

[§Client-suggested Identity Provider, line 34] "With the kc_idp_hint query parameter, the client can override the default identity provider if you configure one for the Identity Provider Redirector authenticator. The client can disable the automatic redirecting by setting the kc_idp_hint query parameter to an empty value."

Claims Extracted / 추출된 주장

Claim ID	Claim (이 자료가 직접 말하는 것)	Evidence quote	Strength	Applies to	Does not prove
KC-IDPHINT-C1	OIDC 클라이언트는 Authorization Code Flow authorization endpoint 에 `kc_idp_hint` 쿼리 파라미터를 설정해 Keycloak 로그인 화면을 bypass 하고 특정 identity provider 로 직행할 수 있다	[line 5] "OIDC applications can bypass the {project_name} login page by hinting at the identity provider they want to use. You can enable this by setting the `kc_idp_hint` query parameter in the Authorization Code Flow authorization endpoint."	`official-vendor-doc`	Authorization Code Flow 로 Keycloak 과 통신하는 OIDC 클라이언트(브라우저 기반 로그인) 전반	Implicit/Direct-grant 등 다른 flow 나 SAML brokering 에서도 동일하게 동작하는지는 이 인용만으로 증명 안 됨
KC-IDPHINT-C2	`kc_idp_hint` 값에 해당하는 alias 의 identity provider 가 realm 에 없으면 Keycloak 은 기본 로그인 폼을 표시한다 (fallback)	[line 17] "In this case, your realm must have an identity provider with a `facebook` alias. If this provider does not exist, the login form is displayed."	`official-vendor-doc`	`kc_idp_hint` 로 넘긴 alias 가 realm 에 미등록인 경우의 fallback 동작	다른 이유(예: IdP 가 `Display on login page` off 이거나 realm 자체가 IdP 를 disable 한 경우)의 fallback 동작이 동일한지는 이 인용 범위 밖
KC-IDPHINT-C3	`keycloak-js` (JavaScript adapter) 로 동일한 bypass 동작을 구현하려면 `keycloak.createLoginUrl({ idpHint: 'facebook' })` 을 호출한다 — 문서 예제는 `keycloak.login()` 이 아니라 `createLoginUrl()` 을 사용	[line 19, 29–30] "If you are using the JavaScript adapter, you can also achieve the same behavior as follows:" / `await keycloak.createLoginUrl({ idpHint: 'facebook' });`	`official-vendor-doc`	`keycloak-js` adapter 로 `kc_idp_hint` 를 프로그래밍적으로 설정하는 공식 API 형태	`keycloak.login({ idpHint: 'google' })` 형태(다른 branch/문서가 종종 가정하는 축약형)가 동일하게 지원되는지는 이 인용이 증명하지 않는다. 본 페이지는 `createLoginUrl()` 만 명시하며 `login()` 옵션 객체가 `idpHint` 를 동일하게 받는지는 별도 확인 필요 (`needs-confirmation`) — keycloak-js 타입 정의/버전별 API 문서 대조 필요
KC-IDPHINT-C4	`kc_idp_hint` 쿼리 파라미터는 `Identity Provider Redirector` authenticator 에 설정된 기본 identity provider 를 클라이언트가 override 할 수 있게 한다	[line 34] "With the `kc_idp_hint` query parameter, the client can override the default identity provider if you configure one for the `Identity Provider Redirector` authenticator."	`official-vendor-doc`	`Identity Provider Redirector` authenticator 로 기본 IdP 를 설정한 browser flow 환경	override 우선순위의 세부 해석(예: 여러 client 가 동시에 다른 hint 를 보낼 때 등)은 인용 범위 밖
KC-IDPHINT-C5	`kc_idp_hint` 쿼리 파라미터를 빈 값으로 설정하면 (Identity Provider Redirector 의) 자동 redirect 동작을 비활성화할 수 있다	[line 34] "The client can disable the automatic redirecting by setting the `kc_idp_hint` query parameter to an empty value."	`official-vendor-doc`	`Identity Provider Redirector` authenticator 가 구성된 상태에서 클라이언트가 자동 IdP redirect 를 opt-out 하려는 경우	Redirector authenticator 가 아예 구성되지 않은 환경에서 빈 값 파라미터의 동작까지 보장하지 않음

Usage Boundaries / 적용 경계

이 자료가 직접 증명하는 것:
- KC-IDPHINT-C1: kc_idp_hint 쿼리 파라미터로 Keycloak 로그인 화면을 bypass 할 수 있다는 공식 메커니즘
- KC-IDPHINT-C3: 공식 JS adapter 예제가 keycloak.login() 이 아니라 keycloak.createLoginUrl({ idpHint }) 를 사용한다는 사실
- KC-IDPHINT-C5: 빈 값 설정으로 자동 redirect 를 끌 수 있다는 사실
이 자료가 증명하지 않는 것:
- keycloak.login({ idpHint: ... }) 형태의 지원 여부 (KC-IDPHINT-C3 Does not prove 참조) — 별도 확인 없이 이 형태를 공식 API 로 인용하면 안 됨
- Implicit/Direct-grant flow, 또는 SAML brokering 에서의 동일 동작 여부
- Identity Provider Redirector authenticator 가 구성되지 않은 환경에서의 kc_idp_hint 동작
내 프로젝트에 적용하려면 추가 확인이 필요한 것:
- 사용 중인 keycloak-js 버전의 실제 타입 정의(KeycloakLoginOptions)에 idpHint 필드가 존재하는지, 그리고 login() 도 동일하게 지원하는지 (버전별 API 문서 또는 소스 대조)
- feature-keycloak-federation-spa-zero-change branch 진행 중 메모의 keycloak.login({ idpHint: 'google' }) 표현은 이 공식 문서로 직접 뒷받침되지 않음 — 수정 또는 별도 검증 필요

메모 / Notes

대안 경로 요약: (a) zero-change — SPA 는 keycloak.login() 만 호출, IdP 선택은 Keycloak 로그인 화면(브라우저)에 위임 vs (b) idpHint 강제 — SPA 가 kc_idp_hint 쿼리 파라미터(또는 JS adapter 의 createLoginUrl({ idpHint }))를 명시적으로 설정 = SPA 코드 변경. feature-keycloak-federation-spa-zero-change 의 D1 은 (a) 를 채택했고, 이 문서는 (b) 가 실제로 코드 변경을 요구한다는 근거.
keycloak-js 의 login() 옵션과 createLoginUrl() 옵션이 내부적으로 동일한 옵션 인터페이스를 공유할 가능성은 있으나(둘 다 로그인 URL 생성 로직을 재사용하는 adapter 설계가 흔함), 이 페이지의 verbatim 만으로는 확정 불가 — 검증 전까지 branch-note 에서 keycloak.login({ idpHint }) 를 공식 근거처럼 쓰지 않을 것.

같은 주제 다른 official-doc:
- raw/official-docs/keycloak-identity-brokering-overview-official — Identity Brokering 개요, Identity Provider Redirector authenticator 참조 지점
- raw/official-docs/keycloak-google-idp-setup — Google IdP 등록 절차 (kc_idp_hint 의 대상이 되는 alias 등록)
- raw/official-docs/keycloak-securing-apps-overview-official — SPA/adapter 표준 flow 컨텍스트
이 자료를 인용한 wiki 요약: (미작성)

10 KiB Raw Permalink Blame History Unescape Escape