コンテンツにスキップ
Authrim

JS Web SDK 概要

はじめに

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

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

できること

  • Passkey: WebAuthnを使ったサインアップ、サインイン、追加パスキー登録
  • Email Code: メールによるワンタイムコードの送信と検証
  • ソーシャルログイン: Google、GitHub、Apple等のプロバイダーによるポップアップまたはリダイレクトログイン
  • セッション管理: 認証状態の確認、ユーザー情報の取得、セッションの更新・無効化
  • OAuth / OIDC（オプション）: ポップアップログイン、リダイレクトフロー、サイレント認証、クロスドメインSSO

アーキテクチャ

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

flowchart TB
    app["Webアプリケーション"]
    web["@authrim/web
(ブラウザSDK)"]
    core["@authrim/core
(プロトコル層)"]
    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

@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メソッドは常に利用できます。

レスポンスパターン

すべての非同期メソッドは 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);

このパターンはすべてのSDKメソッド（passkey、emailCode、social、session、oauth）で一貫しているため、エラーハンドリングの構造はどこでも同じです。

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()


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


// イベント
auth.on('auth:login', (payload) => { ... })
auth.on('session:expired', (payload) => { ... })

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

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

ブラウザサポート

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

次のステップ