@plott/webkit-auth-provider-keycloak0.4.0

@plott/webkit-auth-oauth 용 Keycloak(OIDC SSO) 정의와 클레임 매퍼입니다. 사내 SSO 처럼 Keycloak 토큰을 그대로 세션 토큰으로 쓸 때는 providerIssuer("keycloak") 와 함께 씁니다.

import { oauth, providerIssuer } from "@plott/webkit-auth-oauth";import { keycloak } from "@plott/webkit-auth-provider-keycloak";
declare const clientId: string;declare const clientSecret: string;
export const backend = oauth({  issuer: providerIssuer("keycloak"),  providers: [keycloak({ issuer: "https://sso.example.com/realms/<realm>", clientId, clientSecret, kind: "staff" })],});

• 회사 Keycloak 에서는 서비스마다 클라이언트를 따로 씁니다. clientId 는 서비스의 저장소 이름(조직 이름 제외)이고, 다른 서비스의 클라이언트를 빌려 쓰지 않습니다. 새 클라이언트는 인증 서버 담당자만 만듭니다. 리다이렉트 <origin>/auth/callback/keycloak 은 등록된 https://<host>/* 안에 이미 들어 있습니다.
• 롤은 realm_access.roles, 그룹은 Keycloak 그룹 매퍼가 넣은 groups 클레임에서 읽습니다(keycloakClaims).
• 로그아웃은 Keycloak 세션까지 끊습니다(RP-initiated logout, id_token_hint).
• 그룹이 많으면 토큰이 커져 쿠키 조각 상한(약 11KB)을 넘을 수 있습니다. 그룹 매퍼 범위를 좁힙니다.

진입점

붙이기: 서버가 받은 토큰의 주체

import { createBearerVerifier } from "@plott/webkit-auth-oauth/bearer";import { keycloakPrincipal } from "@plott/webkit-auth-provider-keycloak";
declare const issuer: string;declare const clientId: string;
export const bearer = createBearerVerifier({  issuer,  authorizedParty: clientId,  mapPrincipal: (claims) => keycloakPrincipal(claims, { clientId }),});

위 예의 authorizedParty: clientId 는 «내 서비스의 로그인으로 받은 토큰만» 받습니다. 다른 서비스가 사람의 토큰을 들고 내 서버를 부르게 하려면 audience 에 내 서비스를 가리키는 값을 적고(호출하는 쪽 클라이언트에 내 서비스의 클라이언트 스코프가 붙어 있어야 토큰의 aud 에 들어갑니다), 호출을 허용할 클라이언트를 가려야 하면 authorizedParty 에 목록을 줍니다. match 를 aud 로 두면 azp 는 보지 않습니다(옵션 표).

keycloakPrincipal 은 { sub, email, name, roles, realmRoles, clientRoles } 를 돌려줍니다.

roles 는 realm_access.roles 와 resource_access[clientId].roles 를 합친 것이고, 출처가 필요하면 realmRoles(realm 롤)·clientRoles(이 클라이언트 롤)를 따로 읽습니다. name 은 keycloakClaims 와 같이 name → preferred_username 순서입니다.

붙이기: 브라우저 SPA

keycloak-js(^26.2.4)를 앱이 설치합니다. 서버 번들에는 들어가지 않습니다(동적 import).

lib/spa.ts 에서 모듈 하나가 한 번 만듭니다. init 은 처음 읽을 때 시작합니다.

import { createKeycloakSpa } from "@plott/webkit-auth-provider-keycloak/browser";
export const spa = createKeycloakSpa({ url: process.env.NEXT_PUBLIC_KC_URL!, realm: "r", clientId: "web" });

"use client" 파일(app/providers.tsx)에서 Provider 를 두르고, 컴포넌트에서 훅을 씁니다. KeycloakProvider 는 init 이 끝날 때까지 fallback 을 그리고, init 이 실패하면 error(노드 또는 ({ error, retry }) => 노드)를 그립니다. error 를 주지 않으면 fallback 이 남습니다.

import type { ReactNode } from "react";import { KeycloakProvider, useKeycloak } from "@plott/webkit-auth-provider-keycloak/react";import { createKeycloakSpa } from "@plott/webkit-auth-provider-keycloak/browser";
declare const spa: ReturnType<typeof createKeycloakSpa>;declare function Loading(): ReactNode;
export function Providers({ children }: { children: ReactNode }) {  return (    <KeycloakProvider spa={spa} fallback={<Loading />} error={({ retry }) => <button onClick={retry}>다시 시도</button>}>      {children}    </KeycloakProvider>  );}
export function Me() {  const { ready, authenticated, claims, error, retry, token, login, logout } = useKeycloak();  return <pre>{JSON.stringify({ ready, authenticated, claims, error, retry, token, login, logout })}</pre>;}

useKeycloak 은 KeycloakProvider 안에서만 쓸 수 있고, 밖에서 부르면 오류를 던집니다.

API 호출에는 토큰을 헤더로 붙입니다. authorizationHeader(spa) 는 필요하면 갱신한 Bearer <토큰> 이고, 로그인 전이면 undefined 입니다.

import { authorizationHeader, type createKeycloakSpa } from "@plott/webkit-auth-provider-keycloak/browser";
declare const spa: ReturnType<typeof createKeycloakSpa>;
const auth = await authorizationHeader(spa);await fetch("/api/me", { headers: auth ? { authorization: auth } : {} });

spa.onChange(cb) 는 로그인 상태나 토큰이 바뀔 때만 부릅니다. 토큰을 서버로 보내는 일이 있다면 이 콜백에서 하세요(갱신 주기마다 보내지 마세요).

기본으로 지키는 것

그 밖

• keycloak() 은 id: "keycloak", 스코프 openid profile email, embeddedWebView: "allowed", nativeToken: false 인 OIDC 제공자를 만듭니다. clientRoles: true 면 이 클라이언트의 클라이언트 롤(resource_access.<clientId>.roles)도 roles 에 더하고, 기본은 렐름 롤만입니다. id·extraAuthParams 도 받습니다.
• resource_access 에서는 클라이언트 ID 와 같은 자기 키만 읽습니다(__proto__·constructor 같은 상속 키는 믿지 않습니다).
• amr 클레임이 없으면 ["sso"] 입니다.
• KeycloakSpa 의 ready(init 결과 Promise), token(), claims(), login(), logout(), retry(), getState(), destroy() 도 쓸 수 있습니다. destroy() 는 같은 설정을 쓰는 핸들이 모두 놓였을 때 타이머·이벤트 등록을 풉니다.
• 서버(window 없음)에서 만든 핸들의 ready 는 false 로 바로 끝납니다. init 이 실패하면 retry() 전까지 ready 가 같은 거절을 돌려줍니다.

peer: @plott/webkit-auth, @plott/webkit-auth-oauth. 선택 peer: keycloak-js(/browser·/react), react(/react).