donghyeon.kang/llm-wiki
1
0
Fork 0
Code Issues Pull Requests Projects Releases Wiki Activity
Files
58515ab0f3c9b94ed48e9efe7a11bb52c169ce83
llm-wiki/raw/official-docs/oidc-client-ts-library.md
T

10 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
oidc-client-ts — Browser-based OIDC/OAuth2 client library (authts/oidc-client-ts) official-doc https://github.com/authts/oidc-client-ts
keycloak-patterns
feature-keycloak-patterns
feature-keycloak-single-ec2-no-google
feature-keycloak-vanilla-js-spa-pkce
feature-keycloak-pkce-flow-stages
feature-keycloak-refresh-token-rotation
oidc
oauth2
pkce
keycloak-patterns
p3a-single-ec2
vanilla-js
library
typescript
official-doc
raw high 2026-05-25 2026-05-27

oidc-client-ts — OIDC client for browsers

Layer: raw/official-docs/ — authts/oidc-client-ts README + 공식 docs 의 핵심 발췌. P3A SPA 학습에서 "수동 PKCE 구현 (crypto.subtle + fetch)" → "라이브러리 사용 (UserManager)" 비교 학습의 라이브러리 측 근거.

Parent / 활용 branch (필수)

Branch 이 자료가 정당화하는 결정
raw/branch-notes/feature-keycloak-patterns keycloak-patterns root — SPA 측 OIDC client 의 1st-class browser library 선택지
raw/branch-notes/feature-keycloak-single-ec2-no-google P3A SPA (http://localhost/callback) 의 PKCE 구현 시 oidc-client-ts 채택 결정 근거
raw/branch-notes/feature-keycloak-vanilla-js-spa-pkce vanilla JS SPA 의 PKCE 흐름을 manual 구현 vs library 로 비교 학습하는 단계의 library 측 baseline
raw/branch-notes/feature-keycloak-pkce-flow-stages "Authorization Code Grant with PKCE" 공식 지원 + implicit grant 미지원 (OAuth 2.1 deprecation 준수) 사실 근거
raw/branch-notes/feature-keycloak-refresh-token-rotation Refresh Token Grant + Silent Refresh in iframe 의 라이브러리 측 default 동작 근거

컨텍스트

P3A 학습 전략의 2단계 (라이브러리 비교) 에서 채택할 후보. 1단계는 manual crypto.subtle + fetch('/token', ...) 직접 구현으로 OIDC 내부 동작 학습, 2단계는 oidc-client-ts 로 교체해 보일러플레이트 감소 비교. OAuth 2.1 deprecation 정책 (implicit grant 제외) 을 라이브러리가 강제한다는 점이 학습 가치.

출처 / Source

핵심 인용 / Key quotes (verbatim)

[§README opening paragraph] "This project is a fork of IdentityModel/oidc-client-js which halted its development in June 2021."

[§README opening paragraph] "Going forward, this library will focus only on protocols that continue to have support in OAuth 2.1."

[§Implements the following OAuth 2.0 protocols] "Authorization Code Grant with Proof Key for Code Exchange (PKCE)"

[§Implements the following OAuth 2.0 protocols] "Refresh Token Grant"

[§Implements the following OAuth 2.0 protocols] "Silent Refresh Token in iframe Flow"

Claims Extracted / 추출된 주장

Claim ID Claim (이 자료가 직접 말하는 것) Evidence quote Strength Applies to Does not prove
OIDCTS-C1 oidc-client-ts 는 IdentityModel/oidc-client-js 의 fork; 원본 프로젝트는 2021년 6월 개발 중단 [§README opening paragraph] "This project is a fork of IdentityModel/oidc-client-js which halted its development in June 2021." official-vendor-doc oidc-client-ts 의 origin/governance 이해 원본 프로젝트가 deprecate 되었거나 보안 패치를 받지 않는다는 뜻은 아님 (단지 active development 중단)
OIDCTS-C2 라이브러리는 OAuth 2.1 에 지속 지원되는 프로토콜만 다룸 (= OAuth 2.0 의 deprecated flow 미지원 방침) [§README opening paragraph] "Going forward, this library will focus only on protocols that continue to have support in OAuth 2.1." official-vendor-doc 라이브러리 design 방침 implicit grant 가 명시적으로 제거되었다고 본 인용에서 직접 단언 안 함 — OAuth 2.1 deprecation 항목 별도 확인 필요
OIDCTS-C3 "Authorization Code Grant with PKCE" 가 명시적으로 지원되는 protocol [§Implements the following OAuth 2.0 protocols] "Authorization Code Grant with Proof Key for Code Exchange (PKCE)" official-vendor-doc SPA / public client 의 OAuth2 code flow code_verifier 길이 / code_challenge_method default 의 정확한 값은 본 인용 범위 밖
OIDCTS-C4 "Refresh Token Grant" 가 명시적으로 지원되는 protocol [§Implements the following OAuth 2.0 protocols] "Refresh Token Grant" official-vendor-doc refresh token 으로 access token 갱신 refresh token rotation 의 default 활성화 여부는 본 인용 범위 밖 (Keycloak server-side 설정과 결합)
OIDCTS-C5 "Silent Refresh Token in iframe Flow" 가 명시적으로 지원되는 protocol [§Implements the following OAuth 2.0 protocols] "Silent Refresh Token in iframe Flow" official-vendor-doc hidden iframe 으로 session refresh 시도 3rd-party cookie 차단 환경 (Safari ITP / Chrome Privacy Sandbox) 에서 동작한다는 뜻 아님 — 별도 SameSite 정책 확인 필요

Usage Boundaries / 적용 경계

  • 이 자료가 직접 증명하는 것:
    • OIDCTS-C1: fork 의 origin + 원본 중단 시점 (2021-06)
    • OIDCTS-C2: OAuth 2.1 정책 지향성
    • OIDCTS-C3/C4/C5: 지원되는 3가지 OAuth 2.0 protocol 의 정확한 명칭
  • 이 자료가 증명하지 않는 것:
    • 브라우저 전용 (Node 미지원) 이라는 명시적 진술 — 본 WebFetch 결과에는 직접 인용 없음. 별도 docs 페이지 / package.json browser 필드 확인 필요. (기존 메모는 미검증 — needs-confirmation 으로 처리)
    • openid-client 가 Node 권장 대안이라는 명시적 진술 — 본 WebFetch 결과에 직접 인용 없음. (기존 메모는 미검증 — needs-confirmation)
    • UserManager / WebStorageStateStore 등 구체 API 의 method signature — README opening + protocols 목록만 인용. API docs (authts.github.io/oidc-client-ts/) 별도 fetch 필요
    • implicit grant 의 미지원 여부 — OIDCTS-C2 의 "OAuth 2.1 지원 protocol" 정책에서 추론 가능하지만 직접 인용 없음
  • 내 프로젝트에 적용하려면 추가 확인이 필요한 것:
    • UserManager 의 정확한 constructor option (authority, client_id, redirect_uri, response_type, scope, post_logout_redirect_uri) 의 default 값
    • signinRedirectCallback() 이 PKCE code_verifier 를 어떤 storage 에 보관하는지 (sessionStorage default 여부)
    • startSilentRenew() 의 기본 갱신 타이밍 (access token expiry 전 몇 초)

라이브러리 특성 (해석 — 내 프로젝트 메모)

본 섹션은 README 직접 인용 아님. 기존 정리 + 미검증 항목 표시.

  • 브라우저용. Node 미지원 — 대신 openid-client 권장 (UNSUPPORTED_CLAIM — 본 WebFetch 결과 미포함, 별도 docs 확인 필요).
  • TypeScript 작성, vanilla JS / Angular / React 등에서 사용 가능 (UNSUPPORTED_CLAIM — README opening 인용에 미포함).
  • 지원 흐름 (OIDCTS-C3/C4/C5 직접 인용):
    • Authorization Code Grant with PKCE ← P3A 에서 사용
    • Refresh Token Grant
    • Silent Refresh Token in iframe Flow
  • (기타 흐름 — Authorization Code without PKCE, Resource Owner Password Credentials — 는 본 WebFetch 결과에 미포함. 별도 README 절 확인 필요)
  • implicit grant 미지원 (OAuth 2.1 deprecation 준수) — OIDCTS-C2 정책으로 강한 추론, 직접 인용은 없음.

핵심 API (요약 — UNSUPPORTED, 별도 확인 필요)

본 섹션은 README/공식 docs 의 직접 인용에 기반하지 않음. 기존 정리 항목으로, 추후 API docs (authts.github.io/oidc-client-ts/) 별도 fetch 필요.

  • UserManager — 세션/토큰 lifecycle 관리.
    • signinRedirect() — /authorize redirect 시작 (PKCE 자동 처리).
    • signinRedirectCallback() — callback URL 에서 code → token 교환.
    • getUser() — 현재 user (access_token / id_token / profile claims).
    • signoutRedirect() — /logout redirect.
    • startSilentRenew() — refresh_token 자동 갱신.
  • WebStorageStateStore — sessionStorage/localStorage 추상화.

P3A 적용 메모 (내 프로젝트 해석)

본 섹션은 자료 직접 인용 아님. 예제 코드는 README 의 API 참조에 기반한 일반적 사용법 (별도 검증 필요).

import { UserManager } from 'oidc-client-ts';

const mgr = new UserManager({
  authority: 'http://localhost:8080/realms/keycloak-patterns',
  client_id: 'spa-client',
  redirect_uri: 'http://localhost/callback',
  response_type: 'code',           // PKCE 자동
  scope: 'openid profile',
  post_logout_redirect_uri: 'http://localhost/',
});

// login button
document.getElementById('login').onclick = () => mgr.signinRedirect();

// /callback page
mgr.signinRedirectCallback().then(user => {
  console.log(user.access_token);
});
  • authority 가 Keycloak realm URL → 자동으로 <authority>/.well-known/openid-configuration 조회 (UNSUPPORTED — 별도 docs 확인 필요).
  • authority 와 Keycloak KC_HOSTNAME 이 일치해야 함 → iss claim 검증 통과 (별도 raw/official-docs/spring-security-resource-server-jwt SSRS-JWT-C1 과 연결).

P3A 학습 전략

  • 1단계: manual crypto.subtle + fetch('/token', ...) 직접 구현 → OIDC 내부 동작 학습.
  • 2단계: oidc-client-ts 로 교체 → 라이브러리 사용 시 보일러플레이트가 얼마나 줄어드는지 비교.

한계 / 후속

  • 본 라이브러리는 브라우저 환경 한정 (UNSUPPORTED — README opening 인용에 미포함, docs 별도 확인). mobile/native 는 AppAuth 계열.
  • Node 서버사이드 BFF 는 openid-client 별도 사용 (UNSUPPORTED — 별도 확인).
  • API method signature 검증은 후속 페이지 fetch 후 보충 필요.

Related / 관련

Reference in New Issue View Git Blame Copy Permalink