auth0-spa-js

Auth0 SPA JS 統合

@auth0/auth0-spa-js を使用して、ブラウザーで動作するあらゆるシングルページアプリケーションに認証を追加できます。これは、Vanilla JS、Svelte、SolidJS、および React、Angular、Vue を使用しないあらゆる SPA 向けの低レベル Auth0 SDK です。

エージェントへの指示： SDK のセットアップ手順を提示する前に、次のコマンドを実行して最新のリリースバージョンを取得してください。

gh api repos/auth0/auth0-spa-js/releases/latest --jq '.tag_name'

以下の依存関係の記述では、ハードコードされたバージョンではなく、取得したバージョンを使用してください。コマンドが失敗した場合は、https://github.com/auth0/auth0-spa-js/releases を確認してください。

前提条件

• ES2017 以降に対応した最新のブラウザー
• npm または yarn（バンドラーを使わないアプリでは CDN も利用できます）
• シングルページアプリケーションが設定された Auth0 アカウント
• Auth0 をまだ設定していない場合は、auth0-quickstart を参照してください

使用しないケース

• React SPA（フック、Auth0Provider）：auth0-react を使用してください
• Angular SPA（AuthModule、AuthGuard）：auth0-angular を使用してください
• Vue 3 SPA（createAuth0、useAuth0）：auth0-vue を使用してください
• Next.js（サーバーサイドセッション、App Router）：auth0-nextjs を使用してください
• Nuxt（サーバーサイド SSR）：auth0-nuxt を使用してください
• Express サーバーサイドのウェブアプリ：auth0-express を使用してください
• React Native／Expo のモバイルアプリ：auth0-react-native を使用してください

クイックスタートのワークフロー

1. SDK をインストールする

npm install @auth0/auth0-spa-js

または CDN を使用します（バンドラー不要）。次のコマンドで最新バージョンを取得し、HTML で使用してください。

VERSION=$(npm view @auth0/auth0-spa-js version)

<script src="https://cdn.auth0.com/js/auth0-spa-js/$VERSION/auth0-spa-js.production.js"></script>

2. Auth0 を設定する

Auth0 CLI を使って自動セットアップする場合は、スクリプト一式についてセットアップガイドを参照してください。

手動で設定する場合は、.env を作成します（Vite）。

VITE_AUTH0_DOMAIN=your-tenant.auth0.com
VITE_AUTH0_CLIENT_ID=your-client-id

Auth0 Dashboard で、シングルページアプリケーションに次の値を設定します。

• 許可されたコールバック URL：http://localhost:5173
• 許可されたログアウト URL：http://localhost:5173
• 許可されたウェブオリジン：http://localhost:5173

3. Auth0 クライアントを初期化する

import { createAuth0Client } from '@auth0/auth0-spa-js';

const auth0 = await createAuth0Client({
  domain: import.meta.env.VITE_AUTH0_DOMAIN,
  clientId: import.meta.env.VITE_AUTH0_CLIENT_ID,
  authorizationParams: {
    redirect_uri: window.location.origin
  }
});

// Handle redirect callback after login
const query = new URLSearchParams(window.location.search);
if ((query.has('code') || query.has('error')) && query.has('state')) {
  await auth0.handleRedirectCallback();
  window.history.replaceState({}, document.title, window.location.pathname);
}

4. ログイン／ログアウトを追加する

エージェントへの指示： 新しい UI 要素を追加する前に、プロジェクト内でログイン、ログアウト、サインイン、サインアウトのボタンに既存のクリックハンドラーがないか検索してください。既存のハンドラーが見つかった場合は、既存の UI を変更せずに Auth0 のコードを組み込んでください。新しいボタンを作成するのは、既存のハンドラーが見つからない場合に限ります。

// Login
document.getElementById('login-btn').addEventListener('click', async () => {
  await auth0.loginWithRedirect();
});

// Logout
document.getElementById('logout-btn').addEventListener('click', () => {
  auth0.logout({
    logoutParams: { returnTo: window.location.origin }
  });
});

// Update UI based on auth state
const isAuthenticated = await auth0.isAuthenticated();
if (isAuthenticated) {
  const user = await auth0.getUser();
  console.log(user.name, user.email);
}

5. API 呼び出し用のアクセストークンを取得する

const accessToken = await auth0.getTokenSilently();

const response = await fetch('https://your-api.example.com/data', {
  headers: { Authorization: `Bearer ${accessToken}` }
});

6. ビルドして確認する

エージェントへの指示： 統合が完了したら、プロジェクトをビルドして正常にコンパイルできることを確認してください。

npm run build

ビルドに失敗した場合は、エラー出力を分析して問題を修正してください。統合時によくあるビルドエラーは次のとおりです。

• モジュールが見つからない：npm install @auth0/auth0-spa-js が不足しています。インストールコマンドを実行してください
• Cannot find name 'import.meta'：TypeScript のターゲットが低すぎます。tsconfig.json で "target": "ES2020" 以上を設定してください
• createAuth0Client is not a function：インポートパスが間違っているか、バンドル手順なしで CDN を使用しています
• 実行時に環境変数が未定義：Vite では VITE_ 接頭辞が必要です。webpack／CRA では REACT_APP_ 接頭辞が必要です

修正するたびにビルドを再実行してください。ビルドと修正を繰り返した回数を記録してください。

失敗時の確認： 5～6 回修正を試みてもビルドに失敗する場合は、作業を中断し、AskUserQuestion を使ってユーザーに確認してください。 「複数回修正を試みましたが、ビルドにまだ失敗しています。どのように進めますか？」

• スキルによる反復修正を続ける — ビルドと修正のループをさらに 5～6 回続ける
• 手動で修正する — 残りのエラーを表示し、ユーザーが解決できるようにする
• ビルド確認をスキップする — ビルドに成功しないまま続行する

詳細なドキュメント

• セットアップガイド — 自動セットアップスクリプト（Bash/PowerShell）、Auth0 CLI コマンド、.env の設定、コールバック URL の設定
• 統合パターン — トークン管理、API の呼び出し、リフレッシュトークン、組織、MFA、DPoP、エラー処理、高度なパターン
• テストとリファレンス — 設定オプション、クレームのリファレンス、テストチェックリスト、よくある問題、セキュリティに関する考慮事項

よくある間違い

間違い	修正方法
コールバック URL のポートが一致しない（例：localhost:3001 と localhost:5173）	Auth0 Dashboard で、許可するコールバック URL を開発サーバーのポートと完全に一致させます
SPA のコードに client_secret がある	SPA でクライアントシークレットを使用してはいけません。削除してください。Auth0 は SPA アプリの認証方法を None に設定します
トークンを localStorage に保存している	メモリー内ストレージ（デフォルト）または sessionStorage を使用します。XSS のリスクがあるため、localStorage は絶対に使用しないでください
ページ更新時に getTokenSilently() が login_required をスローする	Auth0 Dashboard の Allowed Web Origins にアプリのオリジンを追加します
リダイレクト後に handleRedirectCallback() を呼び出していない	ログインリダイレクト後、認証コードを交換するために呼び出す必要があります。呼び出さないと URL パラメーターが残り、再び処理が実行されます
ドメインに https:// のプレフィックスを含めている	Auth0 のドメインはホスト名のみです。https://your-tenant.auth0.com ではなく、your-tenant.auth0.com を指定します
非同期の初期化コードから loginWithPopup() を呼び出している	ポップアップはユーザーの操作（クリックハンドラー）から直接起動する必要があります。初期化やページ読み込みのコードから呼び出してはいけません
Vanilla JS で @auth0/auth0-react の Auth0Provider を使用している	Vanilla JS では createAuth0Client() を直接使用します。プロバイダーコンポーネントは必要ありません

関連スキル

• auth0-quickstart — Auth0 アカウントとアプリケーションをセットアップします
• auth0-react — フックを使用した React SPA 向け Auth0
• auth0-angular — Angular SPA 向け Auth0
• auth0-vue — Vue 3 SPA 向け Auth0
• auth0-mfa — 多要素認証を追加します
• auth0-cli — ターミナルから Auth0 リソースを管理します

クイックリファレンス

主要なメソッド

メソッド	説明
createAuth0Client(options)	クライアントを作成して初期化します（内部で checkSession を呼び出します）
new Auth0Client(options)	自動セッションチェックを行わずにインスタンス化します
auth0.loginWithRedirect(options?)	Auth0 Universal Login にリダイレクトします
auth0.loginWithPopup(options?)	ポップアップで Auth0 ログインを開きます
auth0.logout(options?)	セッションをクリアしてリダイレクトします
auth0.handleRedirectCallback(url?)	ログイン後のリダイレクト結果を処理します
auth0.isAuthenticated()	Promise<boolean>
auth0.getUser()	Promise<User | undefined>
auth0.getTokenSilently(options?)	Promise<string> — アクセストークン
auth0.checkSession()	サイレント再認証を試みます

よくあるユースケース

• ログイン／ログアウト → 上記のステップ 4 を参照
• コンテンツの保護 → 統合ガイド
• トークンを使った API 呼び出し → 統合ガイド
• リフレッシュトークン → 統合ガイド
• 組織 → 統合ガイド
• MFA の処理 → 統合ガイド
• エラー処理 → 統合ガイド

参考資料

• Auth0 SPA JS SDK ドキュメント
• Auth0 Vanilla JS クイックスタート
• SDK GitHub リポジトリ
• EXAMPLES.md — 高度なパターン
• API ドキュメント