auth0-ionic-react

Auth0 Ionic React（Capacitor）統合

Capacitor を使用して、Ionic React アプリケーションに Auth0 認証を追加します。このスキルでは、iOS と Android でのディープリンク処理に @capacitor/browser プラグインと @capacitor/app プラグインを組み合わせた、@auth0/auth0-react SDK によるネイティブモバイル認証を扱います。

前提条件

• Node.js 18+
• Ionic CLI（npm install -g @ionic/cli）
• Capacitor が設定済みの既存の Ionic React アプリケーション
• Auth0 アカウントとテナント
• iOS の場合：Xcode 14+ と CocoaPods
• Android の場合：API レベル 21+ に対応した Android Studio
• Auth0 CLI — brew install auth0/auth0-cli/auth0

使用しないケース

ユースケース	推奨スキル
React SPA（Capacitor/Ionic なし）	auth0-react
React Native（bare CLI）	auth0-react-native
Expo（React Native）	auth0-expo
Ionic + Angular + Capacitor	auth0-ionic-angular
Ionic + Vue + Capacitor	auth0-ionic-vue
Next.js（サーバーサイド）	auth0-nextjs
iOS ネイティブ（Swift）	auth0-swift
Android ネイティブ（Kotlin）	auth0-android

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

ステップ 1：Auth0 を設定する

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

手動で設定する場合は、Auth0 Dashboard でネイティブアプリケーションを設定し、ドメインとクライアント ID を控えてください。

ステップ 2：依存関係をインストールする

npm install @auth0/auth0-react @capacitor/browser @capacitor/app
npx cap sync

ステップ 3：Auth0Provider を設定する

アプリのルートを Auth0Provider でラップし、Capacitor 用に設定します。src/main.tsx で次のようにします。

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

const domain = import.meta.env.VITE_AUTH0_DOMAIN;
const clientId = import.meta.env.VITE_AUTH0_CLIENT_ID;
const packageId = import.meta.env.VITE_AUTH0_PACKAGE_ID; // e.g., com.example.myapp

const redirectUri = `${packageId}://${domain}/capacitor/${packageId}/callback`;

createRoot(document.getElementById('root')!).render(
  <React.StrictMode>
    <Auth0Provider
      domain={domain}
      clientId={clientId}
      useRefreshTokens={true}
      useRefreshTokensFallback={false}
      authorizationParams={{
        redirect_uri: redirectUri
      }}
    >
      <App />
    </Auth0Provider>
  </React.StrictMode>
);

ステップ 4：Capacitor Browser を使ってログインを実装する

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

const { loginWithRedirect } = useAuth0();

const login = async () => {
  await loginWithRedirect({
    async openUrl(url) {
      await Browser.open({ url, windowName: "_self" });
    }
  });
};

ステップ 5：ディープリンク経由でコールバックを処理する

import { useEffect } from 'react';
import { App as CapApp } from '@capacitor/app';
import { Browser } from '@capacitor/browser';
import { useAuth0 } from '@auth0/auth0-react';

const { handleRedirectCallback } = useAuth0();

useEffect(() => {
  const listener = CapApp.addListener('appUrlOpen', async ({ url }) => {
    if (url.includes('state') && (url.includes('code') || url.includes('error'))) {
      await handleRedirectCallback(url);
    }
    await Browser.close();
  });

  return () => {
    listener.then(l => l.remove());
  };
}, [handleRedirectCallback]);

ステップ 6：ログアウトを実装する

const doLogout = async () => {
  await logout({
    logoutParams: {
      returnTo: `${packageId}://${domain}/capacitor/${packageId}/callback`
    },
    async openUrl(url) {
      await Browser.open({ url, windowName: "_self" });
    }
  });
};

ステップ 7：ビルドしてテストする

エージェントへの指示： 統合後、ビルドを確認してください。

ionic build
npx cap sync

iOS の場合：npx cap open ios を実行し、Xcode でビルドします。 Android の場合：npx cap open android を実行し、Android Studio でビルドします。 ビルドに失敗した場合は、問題を解決するために最大 5～6 回繰り返してください。それでも失敗する場合は、AskUserQuestion を使用してサポートを求めてください。

詳細ドキュメント

• セットアップガイド — Auth0 CLI の設定、Capacitor URL スキームの登録、シークレットの管理
• 統合パターン — Capacitor Browser を使ったログイン／ログアウト、ディープリンクのコールバック処理、ユーザープロフィール、保護されたルート、トークンへのアクセス、エラー処理
• テストとリファレンス — Auth0Provider の props、useAuth0 フック、Capacitor プラグインの設定、テストチェックリスト、よくある問題の完全な API リファレンス

よくある間違い

間違い	修正方法
Auth0 Dashboard でアプリの種類がネイティブに設定されていない	Dashboard の設定でアプリケーションの種類を「Native」に変更します
コールバック URL の形式がない、または正しくない	YOUR_PACKAGE_ID://YOUR_DOMAIN/capacitor/YOUR_PACKAGE_ID/callback を使用します。完全一致が必要です
リフレッシュトークンが有効になっていない	Auth0Provider で useRefreshTokens={true} と useRefreshTokensFallback={false} を設定します
@capacitor/browser または @capacitor/app がない	両方をインストールします：npm install @capacitor/browser @capacitor/app && npx cap sync
ディープリンクのコールバックを処理していない	Auth0 のリダイレクトを処理するため、CapApp.addListener('appUrlOpen', ...) を追加します
インストール後に npx cap sync を実行し忘れる	Capacitor プラグインのインストール後は、必ず npx cap sync を実行します
リダイレクト URI として window.location.origin を使用している	http://localhost ではなく、カスタム URL スキーム（packageId://domain/...）を使用します
Dashboard の Allowed Origins が設定されていない	Allowed Origins に capacitor://localhost, http://localhost を追加します
モバイルで localStorage が永続化されると想定している	トークンを確実に永続化するには、リフレッシュトークン（useRefreshTokens={true}）を使用します
iOS の SSO が動作しない	iOS 11 以降では SFSafariViewController は Safari と Cookie を共有しません。これは想定どおりの動作です
実機でテストしていない	認証フローは必ず実機でテストしてください。シミュレーターではディープリンクが正しく処理されない場合があります

WebAuth メソッド

この SDK は、Capacitor Browser プラグインを介して Auth0 の Universal Login（WebAuth）を使用します。loginWithRedirect() メソッドは、システムブラウザー（iOS では SFSafariViewController、Android では Chrome Custom Tabs）で Auth0 の認可エンドポイントを開きます。認証後、Auth0 はカスタムスキームを使用したネイティブコールバック URL でアプリにリダイレクトします。{packageId}://{domain}/capacitor/{packageId}/callback。@capacitor/app プラグインがこのディープリンクを受け取り、handleRedirectCallback(url) が認可コードの交換を処理します。

https://{domain}/android/{packageId}/callback や https://{domain}/ios/{bundleId}/callback を使用する標準的なネイティブ SDK とは異なり、Ionic Capacitor アプリは、URL スキームとしてパッケージ ID を使用する Capacitor 固有のコールバックパスを使用します。

関連スキル

• auth0-react — React SPA（ブラウザーのみ、Capacitor なし）
• auth0-ionic-angular — Angular と Capacitor を使用する Ionic
• auth0-ionic-vue — Vue と Capacitor を使用する Ionic
• auth0-react-native — React Native（ベア CLI、Ionic／Capacitor なし）
• auth0-expo — Auth0 を使用する Expo（React Native）

クイックリファレンス

API	説明
Auth0Provider	コンテキストプロバイダー — Auth0 の設定でアプリのルートをラップします
useAuth0()	フック — { isLoading, isAuthenticated, user, loginWithRedirect, logout, getAccessTokenSilently, handleRedirectCallback } を返します
loginWithRedirect({ openUrl })	Universal Login によるログイン — openUrl コールバックで Browser.open() を使用します
logout({ logoutParams, openUrl })	ログアウト — openUrl コールバックで Browser.open() を使用します
handleRedirectCallback(url)	ディープリンクからの Auth0 コールバック URL を処理します
getAccessTokenSilently()	アクセストークンを取得します（モバイルではリフレッシュトークンを使用します）
withAuthenticationRequired(Component)	ルートを保護する HOC
Browser.open({ url })	Capacitor — システムブラウザーで URL を開きます（SFSafariViewController／Chrome Custom Tabs）
CapApp.addListener('appUrlOpen', cb)	Capacitor — ディープリンクイベントをリッスンします
Browser.close()	Capacitor — コールバック後にアプリ内ブラウザーを閉じます

参考資料

• Auth0 Ionic React クイックスタート
• Auth0 React SDK GitHub
• Auth0 React SDK API リファレンス
• Ionic React Capacitor サンプルアプリ
• Capacitor Browser プラグイン
• Capacitor App プラグイン
• Auth0 ダッシュボード