llm-wiki/raw/official-docs/keycloak-idp-hint-client-suggested-official.md

---
title: Keycloak — Client-suggested Identity Provider (kc_idp_hint, official)
source_type: official-doc
url: https://github.com/keycloak/keycloak/blob/main/docs/documentation/server_admin/topics/identity-broker/suggested.adoc
archive_url:
related_branches: [feature-keycloak-federation-spa-zero-change]
related_projects: [keycloak-patterns]
tags: [official-doc, keycloak-patterns, auth, keycloak, oidc, idp-hint]
status: raw
confidence: high
created: 2026-07-16
last_reviewed: 2026-07-16
---

# 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 })` 를 공식 근거처럼 쓰지 않을 것.

## Related / 관련

- 같은 주제 다른 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 요약: (미작성)