---
title: oidc-client-ts — Browser-based OIDC/OAuth2 client library (authts/oidc-client-ts)
source_type: official-doc
url: https://github.com/authts/oidc-client-ts
archive_url:
related_projects: [keycloak-patterns]
related_branches: [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]
tags: [oidc, oauth2, pkce, keycloak-patterns, p3a-single-ec2, vanilla-js, library, typescript, official-doc]
status: raw
confidence: high
created: 2026-05-25
last_reviewed: 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

- 원본 URL (GitHub): https://github.com/authts/oidc-client-ts
- 공식 docs: https://authts.github.io/oidc-client-ts/
- 아카이브 URL: (미수집)
- 저자 / 조직: authts (커뮤니티 fork)
- 발행일: 활성 maintenance (fork 시점 = 2021-06+)
- 마지막 확인일: 2026-05-27

## 핵심 인용 / 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 참조에 기반한 일반적 사용법 (별도 검증 필요).

```js
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 / 관련

- 같은 주제 다른 official-doc:
  - [[raw/official-docs/oauth2-pkce-rfc-7636]] (PKCE RFC — `OIDCTS-C3` 의 protocol spec)
  - [[raw/official-docs/security-oauth2-pkce-rfc-8252]] (native app + browser SPA OAuth 2.0)
  - [[raw/official-docs/keycloak-getting-started-docker]] (Keycloak 측 client 등록)
- 인용하는 branch:
  - [[raw/branch-notes/feature-keycloak-patterns]]
  - [[raw/branch-notes/feature-keycloak-single-ec2-no-google]]
  - [[raw/branch-notes/feature-keycloak-vanilla-js-spa-pkce]]
- 인용하는 wiki: (미작성)