auth0-react

Auth0 React 統合

@auth0/auth0-react を使用して、React のシングルページアプリケーションに認証を追加します。

---

前提条件

• React 16.11 以降のアプリケーション（Vite または Create React App）— React 16、17、18、19 に対応
• Auth0 アカウントと設定済みのアプリケーション
• Auth0 の設定がまだ済んでいない場合は、まず auth0-quickstart スキルを使用してください

使用しないケース

• Next.js アプリケーション — App Router と Pages Router の両方で auth0-nextjs スキルを使用してください
• React Native モバイルアプリ — iOS／Android では auth0-react-native スキルを使用してください
• サーバーサイドレンダリングを行う React — フレームワーク固有の SDK（Next.js、Remix など）を使用してください
• 埋め込み型ログイン — この SDK は Auth0 Universal Login（リダイレクト方式）を使用します
• バックエンド API の認証 — 代わりに express-openid-connect または JWT 検証を使用してください

---

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

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

npm install @auth0/auth0-react

2. 環境を設定する

**Auth0 CLI を使用した自動セットアップについては、**完全なスクリプトを記載したセットアップガイドを参照してください。

手動でセットアップする場合：

.env ファイルを作成します：

Vite：

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

Create React App：

REACT_APP_AUTH0_DOMAIN=your-tenant.auth0.com
REACT_APP_AUTH0_CLIENT_ID=your-client-id

3. Auth0Provider でアプリをラップする

src/main.tsx（Vite）または src/index.tsx（CRA）を更新します：

import React from 'react';
import ReactDOM from 'react-dom/client';
import { Auth0Provider } from '@auth0/auth0-react';
import App from './App';

ReactDOM.createRoot(document.getElementById('root')!).render(
  <React.StrictMode>
    <Auth0Provider
      domain={import.meta.env.VITE_AUTH0_DOMAIN} // or process.env.REACT_APP_AUTH0_DOMAIN
      clientId={import.meta.env.VITE_AUTH0_CLIENT_ID}
      authorizationParams={{
        redirect_uri: window.location.origin
      }}
    >
      <App />
    </Auth0Provider>
  </React.StrictMode>
);

4. 認証 UI を追加する

import { useAuth0 } from '@auth0/auth0-react';

export function LoginButton() {
  const { loginWithRedirect, logout, isAuthenticated, user, isLoading } = useAuth0();

  if (isLoading) return <div>Loading...</div>;

  if (isAuthenticated) {
    return (
      <div>
        <span>Welcome, {user?.name}</span>
        <button onClick={() => logout({ logoutParams: { returnTo: window.location.origin } })}>
          Logout
        </button>
      </div>
    );
  }

  return <button onClick={() => loginWithRedirect()}>Login</button>;
}

5. 認証をテストする

開発サーバーを起動し、ログインフローをテストします：

npm run dev  # Vite
# or
npm start    # CRA

---

詳細ドキュメント

• セットアップガイド — 自動セットアップスクリプト（Bash／PowerShell）、CLI コマンド、手動設定
• 統合ガイド — 保護されたルート、API 呼び出し、エラー処理、高度なパターン
• API リファレンス — SDK API の全容、設定オプション、フックのリファレンス、テスト戦略

---

よくある間違い

間違い	修正方法
Auth0 Dashboard にリダイレクト URI を追加し忘れる	アプリケーションの URL（例：http://localhost:3000、https://app.example.com）を Auth0 Dashboard の Allowed Callback URLs に追加します
環境変数のプレフィックスを間違える	Vite では VITE_、Create React App では REACT_APP_ のプレフィックスを使用します
読み込み状態を処理していない	認証に依存する UI をレンダリングする前に、必ず isLoading を確認します
トークンを localStorage に保存する	トークンを手動で保存しないでください。SDK が安全なストレージを自動的に処理します
Auth0Provider でラップしていない	アプリ全体を <Auth0Provider> でラップする必要があります
Provider がルートレベルにない	認証フックを使用するすべてのコンポーネントを Auth0Provider でラップする必要があります
環境変数のインポートパスが間違っている	Vite では import.meta.env.VITE_*、CRA では process.env.REACT_APP_* を使用します
アプリ内 MFA に acr_values リダイレクトを使用する	アプリ内の登録／チャレンジ／検証フローには useAuth0().mfa API を使用します
MfaRequiredError を捕捉していない	getAccessTokenSilently を try/catch で囲み、instanceof MfaRequiredError を確認します
MFA エンドポイントに直接 HTTP リクエストを送信する	useAuth0() の mfa プロパティを使用してください。トークン管理は自動的に処理されます
ステップアップ MFA 用のリフレッシュトークンを忘れる	interactiveErrorHandler="popup" を使用する場合は、Auth0Provider に useRefreshTokens={true} を設定します

---

関連スキル

• auth0-quickstart — Auth0 の基本セットアップ
• auth0-migration — 別の認証プロバイダーから移行する
• auth0-mfa — 多要素認証を追加する
• auth0-cli — ターミナルから Auth0 リソースを管理する

---

クイックリファレンス

主要なフック：

• useAuth0() - メインの認証フック
• isAuthenticated - ユーザーがログインしているか確認します
• user - ユーザープロフィール情報
• loginWithRedirect() - ログインを開始します
• logout() - ユーザーをログアウトさせます
• getAccessTokenSilently() - API 呼び出し用のアクセストークンを取得します
• mfa - 登録、チャレンジ、検証に使用する MFA API クライアント
  • mfa.getAuthenticators(mfaToken) - 登録済みの認証器を一覧表示します
  • mfa.getEnrollmentFactors(mfaToken) - 利用可能な登録要素を取得します
  • mfa.enroll(params) - 新しい認証器を登録します（OTP、SMS、メール、音声、プッシュ通知）
  • mfa.challenge(params) - MFA チャレンジを開始します
  • mfa.verify(params) - MFA チャレンジを検証し、認証を完了します

MFA エラーの種類（@auth0/auth0-react からインポート）：

• MfaRequiredError - MFA が必要な場合に getAccessTokenSilently がスローします（mfa_token と mfa_requirements を含みます）
• MfaEnrollmentError、MfaChallengeError、MfaVerifyError - それぞれ対応する mfa.* メソッドがスローします

一般的なユースケース：

• ログイン／ログアウトボタン → 上記のステップ 4 を参照してください
• 保護されたルート → インテグレーションガイド
• トークンを使用した API 呼び出し → インテグレーションガイド
• エラー処理 → インテグレーションガイド
• MFA の処理 → インテグレーションガイド

---

参考資料

• Auth0 React SDK ドキュメント
• Auth0 React クイックスタート
• SDK GitHub リポジトリ