コンテンツにスキップ
Authrim

JS Web SDK 概要

はじめに

Section titled “はじめに”

@authrim/web はAuthrimのブラウザ向けSDKです。Passkeyログイン、Email Code認証、ソーシャルログイン、セッション管理、そしてオプションのOAuth/OIDCフローをシンプルで統一されたAPIで提供します。

SDKは @authrim/core をラップし、ブラウザ固有の実装（Web Crypto API、Fetch API、ブラウザストレージ）を内部で処理するため、プロトコルの詳細を意識せずにアプリケーション開発に集中できます。

できること

Section titled “できること”
  • Passkey: WebAuthnを使ったサインアップ、サインイン、追加パスキー登録
  • Email Code: メールによるワンタイムコードの送信と検証
  • ソーシャルログイン: Google、GitHub、Apple等のプロバイダーによるポップアップまたはリダイレクトログイン
  • セッション管理: 認証状態の確認、ユーザー情報の取得、セッションの更新・無効化
  • 認証付きFetch: DPoP-bound access tokenまたはsame-origin cookie profileでAPIを呼び出し
  • 高度なアカウントフロー: Handoff SSO検証、step-up、customer profile更新、device inventory
  • OAuth / OIDC（オプション）: ポップアップログイン、リダイレクトフロー、サイレント認証、クロスドメインSSO

アーキテクチャ

Section titled “アーキテクチャ”

@authrim/web はアプリケーションコードとAuthrimサーバーの間に位置します：

flowchart TB
    app["Webアプリケーション"]
    web["@authrim/web<br>(ブラウザSDK)"]
    core["@authrim/core<br>(プロトコル層)"]
    server["Authrimサーバー"]
    app --> web --> core --> server
  • @authrim/web — ブラウザ固有のAPI。createAuthrim() ファクトリ、名前空間ベースのメソッド、イベントシステムを提供。
  • @authrim/core — プラットフォーム非依存のプロトコル実装。OAuth 2.0、OIDC、PKCE、DPoP、トークン管理を内部で処理。

@authrim/core を直接インポートしたり設定したりする必要はありません — @authrim/web が内部で処理します。

Direct Auth と OAuth / OIDC

Section titled “Direct Auth と OAuth / OIDC”

@authrim/web は2つの認証モードをサポートしています：

モードユースケース設定
Direct AuthPasskey、Email Code、ソーシャルログイン — OAuthリダイレクト不要デフォルト（追加設定不要）
OAuth / OIDC標準OAuthフロー、ポップアップログイン、サイレント認証、クロスドメインSSOenableOAuth: true

Direct Auth は最もシンプルな方法です。SDKがAuthrimサーバーのDirect Authエンドポイントと直接通信し、WebAuthnセレモニー、メールコード交換、ソーシャルプロバイダーのポップアップフローを内部で処理します。

OAuth / OIDC モードを有効にすると oauth 名前空間が追加され、標準の認可コードフロー（PKCE付き）、ポップアップベースのログイン、iframeサイレント認証、トップレベルナビゲーションによるクロスドメインSSOが利用可能になります。

両モードは併用可能です — enableOAuth の設定に関わらず、Direct Authメソッドは常に利用できます。

レスポンスパターン

Section titled “レスポンスパターン”

Direct AuthとOAuthメソッドは AuthResponse<T> オブジェクト — { data, error } の判別共用体を返します：

const { data, error } = await auth.passkey.login();


if (error) {
  // error: { code, error, message, retryable, severity }
  console.error(error.message);
  return;
}


// ここでは data が non-null であることが保証されます
console.log('ユーザー:', data.user);
console.log('セッション:', data.session);

このパターンは passkey、emailCode、social、session、oauth に適用されます。auth.stepUp、auth.customerProfiles、auth.devices、auth.fetch() などのprotected resourceヘルパーはAPI結果を直接返すため、失敗を扱う場合は try/catch で囲んでください。

API名前空間

Section titled “API名前空間”

SDKはメソッドを名前空間で整理しています：

const auth = await createAuthrim({
  issuer: 'https://auth.example.com',
  clientId: 'my-app',
});


// Passkey
auth.passkey.login()
auth.passkey.signUp({ email })
auth.passkey.register()
auth.passkey.isSupported()


// Email Code
auth.emailCode.send(email)
auth.emailCode.verify(email, code)


// ソーシャルログイン
auth.social.loginWithPopup('google')
auth.social.loginWithRedirect('github')
auth.social.handleCallback()


// セッション
auth.session.get()
auth.session.isAuthenticated()
auth.session.refresh()


// Protected resource calls と高度なフロー
auth.fetch('/api/me')
auth.handoff.verifyAndSave(handoffToken, state)
auth.stepUp.start({ step_up_token })
auth.customerProfiles.getWithElevationGrant(userId, { accessToken })
auth.customerProfiles.updateDelegated(userId, input, { accessToken, stepUpReceipt })
auth.devices.list()


// ショートカット
auth.signIn.passkey()
auth.signIn.social('google')
auth.signUp.passkey({ email })
auth.signOut()
auth.signOutApplicationGroup()
auth.signOutAll()


// イベント
auth.on('auth:login', (payload) => { ... })
auth.on('auth:logout', (payload) => { ... })
auth.on('token:refreshed', (payload) => { ... })

enableOAuth: true を設定すると、oauth 名前空間も利用可能になります：

auth.oauth.popup.login()
auth.oauth.silentAuth.check({ redirectUri })
auth.oauth.trySilentLogin()
auth.oauth.handleSilentCallback()

ブラウザサポート

Section titled “ブラウザサポート”
ブラウザバージョン備考
Chrome67+WebAuthn含むフルサポート
Firefox60+フルサポート
Safari14+フルサポート（WebAuthnは14以降）
Edge79+Chromiumベース、フルサポート

次のステップ

Section titled “次のステップ”