React Router アプリケーションにログインを追加する

@auth0/auth0-react-router は現在 Beta 版 (1.0.0-beta.2) です。安定版 1.0 のリリースまでに API が変更される可能性があります。

AI を使って Auth0 を統合する

Claude Code、Cursor、GitHub Copilot などの AI コーディングアシスタントをお使いの場合は、エージェントスキルを使えば、数分で Auth0 認証を自動的に追加できます。インストール：

npx skills add auth0/agent-skills --skill auth0

次に、AI アシスタントに次のように依頼します：

Add Auth0 authentication to my React Router app

AI アシスタントが、Auth0 アプリケーションの作成、資格情報の取得、@auth0/auth0-react-router のインストール、プロバイダーの構成、ルートのセットアップまでを自動で行います。エージェントスキルの詳細なドキュメント →

前提条件： 始める前に、以下がインストールされていることを確認してください。

Node.js 18 以降 (20 LTS 推奨)
npm 9 以降、yarn 1.22 以降、または pnpm 8 以降
jq - Auth0 CLI でのセットアップに必要
React Router のフレームワークモード (v7 以降、react-router.config.ts があること)

はじめに

このクイックスタートでは、React RouterアプリケーションにAuth0の認証を追加する方法を説明します。Auth0 React Router SDKを使用して、ログイン、ログアウト、ユーザープロファイルの機能を備えたセキュアなアプリを構築します。SDKはOIDCフローをサーバー側で処理し、セッションをJWEで暗号化されたクッキーに保存するため、トークンがブラウザーに渡ることは一切ありません。

新しい React Router プロジェクトを作成する

このクイックスタート用に、新しい React Router プロジェクトを作成します。

npx create-react-router@latest my-app

プロジェクトを開きます。

cd my-app && npm install

既存のReact RouterアプリにAuth0を追加する場合は、この手順を省略してください。

Auth0 React Router SDKをインストールする

npm install @auth0/auth0-react-router

Auth0を設定する

Auth0アプリケーションを作成し、コールバックURLとログアウトURLを設定します。

クイックセットアップ
CLI
Dashboard

プロジェクトのルートディレクトリで次のコマンドを実行し、Auth0アプリの作成と.envファイルの生成を行います。

# Auth0 CLIをインストールする（未インストールの場合）
brew tap auth0/auth0-cli && brew install auth0

# Auth0アプリをセットアップし、.envファイルを生成する
auth0 qs setup --app --type regular --framework react-router --port 5173 --name "My React Router App"

# Auth0 CLIをインストールする（未インストールの場合）
scoop bucket add auth0 https://github.com/auth0/scoop-auth0-cli.git
scoop install auth0

# Auth0アプリをセットアップし、.envファイルを生成する
auth0 qs setup --app --type regular --framework react-router --port 5173 --name "My React Router App"

このコマンドを実行すると、http://localhost:5173向けに構成されたAuth0のRegular Web Applicationが作成され、必要な資格情報をすべて含む.envファイルが生成されます。この方法を使用する場合、手順4は不要です。

Auth0 Dashboardで [Applications] > [Applications] に移動します
[Create Application] をクリックし、名前を入力して [Regular Web Application] を選択します
[Create] をクリックします
[Settings] タブ (アプリケーション設定) を開きます
次のフィールドを設定します。

フィールド	値
Allowed Callback URLs	`http://localhost:5173/auth/callback`
Allowed Logout URLs	`http://localhost:5173`

[Save Changes] をクリックします
アプリケーション設定の [Domain] と [Client ID] をコピーします。これらは次の手順で使用します

環境変数を設定する

プロジェクトのルートに .env ファイルを作成します。

変数	確認場所
`AUTH0_DOMAIN`	アプリケーションの設定 → ドメイン
`AUTH0_CLIENT_ID`	アプリケーションの設定 → クライアント ID
`AUTH0_CLIENT_SECRET`	アプリケーションの設定 → クライアントシークレット
`AUTH0_SESSION_SECRET`	32 文字以上のランダムな文字列 (上記のスニペットで自動生成されます)
`AUTH0_APP_BASE_URL`	アプリのベース URL (ローカル開発では `http://localhost:5173`)

.env は決してバージョン管理にコミットしないでください。最初のコミットを行う前に、必ず .gitignore に追加しておきましょう。

Auth0のサーバーインスタンスを作成する

app/auth0.server.ts を作成します。.server.ts という接尾辞が付いたファイルは React Router のバンドラーによってクライアントバンドルから除外されるため、シークレットをサーバー側だけに留めておけます。

app/auth0.server.ts

import { Auth0Server, registerAuth0Instance } from '@auth0/auth0-react-router/server';

export const auth0 = new Auth0Server();
registerAuth0Instance(auth0);

認証ルートを追加する

/auth/* 配下のすべてのパスを処理するスプラットルートを作成します。handleAuth は、URL のパスと HTTP メソッドに応じて、内部で handleLogin、handleCallback、handleLogout、handleBackchannelLogout に処理を振り分けます。

app/routes/auth.$.tsx

import { handleAuth } from '@auth0/auth0-react-router/server';
import { auth0 } from '../auth0.server';

export const loader = ({ request }: { request: Request }) =>
  handleAuth(auth0, request);

export const action = ({ request }: { request: Request }) =>
  handleAuth(auth0, request);

ルート設定にルートを登録します。

app/routes.ts

import { type RouteConfig, route } from '@react-router/dev/routes';

export default [
  route('auth/*', 'routes/auth.$.tsx'),
  // ... その他のルート
] satisfies RouteConfig;

ルートレイアウトを設定する

app/root.tsx に Auth0Provider と rootAuthLoader を追加します。rootAuthLoader はセッションクッキーを復号し、認証状態をプロバイダーに渡します。トークンがブラウザーに送信されることはありません。

app/root.tsx

import { Links, Meta, Outlet, Scripts, ScrollRestoration } from 'react-router';
import { Auth0Provider } from '@auth0/auth0-react-router';
import { rootAuthLoader } from '@auth0/auth0-react-router/server';
import type { Route } from './+types/root';

export const loader = ({ request }: Route.LoaderArgs) =>
  rootAuthLoader(request);

export default function Root() {
  return (
    <html lang="en">
      <head>
        <meta charSet="utf-8" />
        <meta name="viewport" content="width=device-width, initial-scale=1" />
        <Meta />
        <Links />
      </head>
      <body>
        <Auth0Provider>
          <Outlet />
        </Auth0Provider>
        <ScrollRestoration />
        <Scripts />
      </body>
    </html>
  );
}

Auth0Provider は useRouteLoaderData('root') からセッションデータを読み取るため、ルートのルート (root route) の id を root にする必要があります。ファイルベースのルーティングでは、React Router がファイル名をもとにこの id を自動で設定します。カスタムのルート設定を使用する場合は、layout() の呼び出しに { id: 'root' } を渡してください。

ログインとログアウトを追加

組み込みのコンポーネントを使用して、ログインボタンとログアウトボタンを表示します。LoginButton は /auth/login に、LogoutButton は /auth/logout にリダイレクトします。OIDC フローは Auth0 が処理し、サインイン後にユーザーをアプリへリダイレクトして戻します。

app/routes/_index.tsx

import {
  AuthLoading,
  LoginButton,
  LogoutButton,
  SignedIn,
  SignedOut,
} from '@auth0/auth0-react-router';

export default function Home() {
  return (
    <main>
      <h1>Welcome</h1>
      <AuthLoading>
        <p>Loading…</p>
      </AuthLoading>
      <SignedOut>
        <LoginButton>Log in</LoginButton>
      </SignedOut>
      <SignedIn>
        <LogoutButton>Log out</LogoutButton>
      </SignedIn>
    </main>
  );
}

ユーザープロファイルを表示

useUser Hooksを使うと、任意のクライアントコンポーネントから認証済みユーザーのプロフィールにアクセスできます。さらにローダーで requireSession と組み合わせれば、ページのレンダリング前に未認証のリクエストをサーバー側でブロックできます。

app/routes/profile.tsx

import { useUser } from '@auth0/auth0-react-router';
import { requireSession } from '@auth0/auth0-react-router/server';
import type { Route } from './+types/profile';

export const loader = async ({ request }: Route.LoaderArgs) => {
  await requireSession(request);
  return null;
};

export default function Profile() {
  const user = useUser();

  return (
    <main>
      <h1>Profile</h1>
      {user && (
        <div>
          <img src={user.picture} alt={user.name ?? ''} width={80} height={80} />
          <p><strong>{user.name}</strong></p>
          <p>{user.email}</p>
        </div>
      )}
    </main>
  );
}

アプリケーションを実行する

npm run dev

ブラウザーで http://localhost:5173 を開き、Log in をクリックします。Auth0のユニバーサルログインページにリダイレクトされます。サインインすると、アプリにリダイレクトされて戻ってきます。

これで、アプリのログインとログアウトが機能するようになりました。セッションはJWEで暗号化されたクッキーに保存され、アクセストークンはサーバー上に保持されるため、ブラウザーに送信されることはありません。

トラブルシューティング

JWEDecryptionFailed — セッションクッキーを復号できない

**原因：**セッションクッキーの発行後にAUTH0_SESSION_SECRETが変更されたか、値が32文字未満です。解決方法：localhostのブラウザークッキーを削除し、AUTH0_SESSION_SECRETが32文字以上であることを確認してから、開発サーバーを再起動してください。新しいシークレットはopenssl rand -hex 32で生成できます。

Callback URLの不一致 — ログイン後にAuth0がエラーを返す

**原因：**Auth0が受け取ったリダイレクトURLが、Allowed Callback URLsに登録されたどの値とも一致していません。解決方法：Auth0 Dashboardで [Applications] > [Applications] に移動してアプリを選択し、[Application Settings] で [Allowed Callback URLs] がhttp://localhost:5173/auth/callbackに設定されていることを確認します。末尾のスラッシュや余分な空白があれば削除し、[Save Changes] をクリックしてください。

原因：auth.$.tsxスプラットルートが存在しないか、routes.tsに登録されていません。解決方法：app/routes/auth.$.tsxが存在し、app/routes.tsにroute('auth/*', 'routes/auth.$.tsx')が含まれていることを確認してください。routes.tsを編集した後は、開発サーバーを再起動してください。

ログイン後にuseUserがnullを返す

原因：rootAuthLoaderがapp/root.tsxからエクスポートされていないか、ルートルートのidがrootになっていません。解決方法：app/root.tsxでexport const loader = ({ request }) => rootAuthLoader(request)がエクスポートされていることを確認してください。カスタムのルート構成を使用している場合は、ルートレイアウトをlayout('root.tsx', { id: 'root' }, [...routes])として登録してください。

context.getでTypeError — ミドルウェアが動作しない

原因：defineRouteAuthとauth0Middlewareを使用するには、ミドルウェアAPIが導入されたReact Router 7.9.0以降が必要です。解決方法：react-routerを>=7.9.0にアップグレードしてください。または、各ローダーでrequireSession / requireUserを使用して、ルートを個別に保護することもできます。

高度な使い方

アクセストークンでバックエンドAPIを呼び出す

.envにAUTH0_AUDIENCEを追加し、APIの識別子を設定します (識別子はAuth0 Dashboard → Applications > APIs → API Settings → Identifierで確認できます) 。次に、ローダー内でgetAccessTokenを使用します。この方法なら、トークンがブラウザーに渡ることはありません。

app/routes/data.tsx

import { getAccessToken } from '@auth0/auth0-react-router/server';
import { TokenError } from '@auth0/auth0-react-router/errors';

export const loader = async ({ request }) => {
  let token: string;
  try {
    token = await getAccessToken(request);
  } catch (err) {
    if (err instanceof TokenError) {
      return new Response(null, { status: 302, headers: { Location: '/auth/login' } });
    }
    throw err;
  }
  const data = await fetch('https://api.example.com/items', {
    headers: { Authorization: `Bearer ${token}` },
  }).then(r => r.json());
  return { data };
};

ロールベースのルート保護

defineRouteAuthミドルウェア (React Router 7.9.0以降) を使用すると、ルート単位でロールによるアクセス制御を適用できます。ロールはデフォルトでhttps://auth0.com/claims/rolesクレームから読み取られます。

app/routes/admin.tsx

import { defineRouteHandle } from '@auth0/auth0-react-router';
import { defineRouteAuth, auth0UserContext } from '@auth0/auth0-react-router/server';

export const handle = defineRouteHandle({ role: 'admin' });

export const middleware = defineRouteAuth({ role: 'admin' }).middleware;

export const loader = ({ context }) => {
  const user = context.get(auth0UserContext);
  return { user };
};

必要なロールを持たないリクエストには403が返されます。

SPAモード（クライアント側PKCE）

SDKは、@auth0/auth0-spa-jsをベースにした完全なクライアント側モードでも動作します。.envにVITE_AUTH0_DOMAINとVITE_AUTH0_CLIENT_IDを追加すると、Auth0Providerがこれらを自動的に検出してPKCEフローに切り替えます。ほかにコードを変更する必要はありません。

# SPAモード用に.envへ追加する項目
VITE_AUTH0_DOMAIN={yourDomain}
VITE_AUTH0_CLIENT_ID={yourClientId}

AUTH0_*変数とVITE_AUTH0_*変数を同時に設定しないでください。ハイブリッドモードはサポートされていないため、両方が設定されていると、SPAでログアウトしてもサーバー側のセッションクッキーが削除されません。

​はじめに

​トラブルシューティング

​高度な使い方

はじめに

トラブルシューティング

高度な使い方