Package Exports
- @authway/client
Readme
@authway/client
Framework-agnostic authentication client for Authway OAuth 2.0 / OpenID Connect.
버전: 0.1.0
설치
npm install @authway/client
# or
pnpm add @authway/client
# or
yarn add @authway/client주요 기능
- ✅ Config 자동 검색 - Auth Backend URL만 지정, 나머지 자동 검색
- ✅ OAuth 2.0 / OIDC - Authorization Code Flow with PKCE
- ✅ 자동 토큰 갱신 - Refresh token 기반 자동 갱신
- ✅ 동적 클레임 관리 - 실시간 사용자 클레임 업데이트
- ✅ 팝업 로그인 - 페이지 이동 없이 팝업으로 인증
- ✅ 멀티 테넌시 - 완전히 격리된 테넌트 지원
- ✅ TypeScript - 완전한 타입 정의 제공
- ✅ 제로 의존성 - 외부 라이브러리 없음
- ✅ 경량 - ~15KB gzipped
빠른 시작
기본 설정 (간소화)
import { AuthwayClient } from '@authway/client'
// Auth Backend URL만 지정!
// OAuth URL, API URL 등은 자동으로 검색됩니다
const client = new AuthwayClient({
domain: 'http://localhost:8081', // Auth Backend URL ()
clientId: 'your-client-id'
})
// Config 로드 완료 대기 (중요!)
await client.waitForReady()
// 이제 사용 가능
await client.loginWithRedirect()Config 자동 검색
클라이언트는 초기화 시 Auth Backend의 /.well-known/authway-config 엔드포인트에서 자동으로 설정을 가져옵니다:
// 내부적으로 다음 요청이 자동 실행됨:
// GET http://localhost:8081/.well-known/authway-config
//
// 응답:
// {
// "oauth_url": "http://localhost:4444", // Hydra OAuth 서버
// "api_url": "http://localhost:8081", // Auth Backend API
// "issuer": "http://localhost:4444",
// "version": "0.1.0"
// }중요: Config 로드는 비동기이므로 OAuth 요청 전에 반드시 waitForReady()를 호출해야 합니다.
로그인
리다이렉트 방식
// 로그인 페이지로 리다이렉트
await client.loginWithRedirect()
// 콜백 URL에서 처리
const result = await client.handleRedirectCallback()
if (result) {
console.log('로그인 성공:', result.user)
}팝업 방식
try {
const result = await client.loginWithPopup()
console.log('로그인 성공:', result.user)
} catch (error) {
console.error('로그인 실패:', error)
}참고: SDK가 팝업 콜백을 자동으로 처리합니다. 별도의 callback.html 파일이 필요 없습니다.
팝업 콜백 자동 처리
React를 사용하지 않는 경우, 앱 초기화 시 다음을 호출하세요:
// 앱 시작 시 (main.ts 등)
if (AuthwayClient.handlePopupCallback()) {
// 팝업 컨텍스트에서 실행됨 - 창이 자동으로 닫힘
return
}
// 일반 앱 초기화 계속
const client = new AuthwayClient(config)사용자 정보
// 인증 상태 확인
const isAuthenticated = await client.isAuthenticated()
// 사용자 정보 조회
const user = await client.getUser()
console.log(user)
// {
// sub: 'user-id',
// email: 'user@example.com',
// name: 'User Name',
// ...
// }토큰 관리
// Access Token 가져오기 (자동 갱신)
const token = await client.getAccessToken()
// 토큰으로 API 호출
const response = await fetch('http://localhost:8081/api/v1/profile/me', {
headers: {
'Authorization': `Bearer ${token}`
}
})동적 클레임 관리
// 클레임 조회
const claims = await client.getClaims(token)
// 클레임 업데이트
await client.updateClaims(token, {
role: 'admin',
department: 'engineering'
})
// 사용자별 클레임 조회
const userClaims = await client.getUserClaims(token, 'user-id')로그아웃
// 로그아웃 (로컬 세션만 삭제)
client.logout()
// 로그아웃 (OAuth 서버에서도 세션 삭제)
client.logout({ federated: true })고급 설정
const client = new AuthwayClient({
domain: 'http://localhost:8081',
clientId: 'your-client-id',
// 선택적 설정
redirectUri: window.location.origin,
scope: 'openid profile email',
audience: 'https://api.example.com',
cacheLocation: 'localstorage', // 'localstorage' | 'memory'
useDPoP: false, // DPoP (RFC 9449) 사용 여부
// OAuth URL 직접 지정 (자동 검색 대신)
// authwayUrl: 'http://localhost:8081',
// oauthUrl: 'http://localhost:4444'
})API 레퍼런스
인증
loginWithRedirect(options?)- 리다이렉트 방식 로그인loginWithPopup(options?)- 팝업 방식 로그인handleRedirectCallback(url?)- OAuth 콜백 처리logout(options?)- 로그아웃
사용자
isAuthenticated()- 인증 상태 확인getUser()- 사용자 정보 조회getAccessToken()- Access Token 가져오기 (자동 갱신)
클레임
getClaims(token)- 클레임 조회updateClaims(token, claims)- 클레임 업데이트getUserClaims(token, userId)- 사용자별 클레임 조회updateUserClaims(token, userId, claims)- 사용자별 클레임 업데이트
유틸리티
waitForReady()- Config 로드 완료 대기 (중요!)
관련 문서
라이선스
MIT