auth0-ionic-vue

Auth0 Ionic Vue（Capacitor）統合

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

前提条件

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

使用しない場合

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

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

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

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

手動で設定する場合は、Auth0 Dashboard で Native アプリケーションを設定し、Domain と Client ID を控えてください。

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

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

ステップ 3：Auth0 プラグインを設定する

エージェントへの指示： ステップ 1 ですでに .env が作成され、src/main.ts が更新されている場合は、設定が正しいことを確認してステップ 4 に進んでください。以下のテンプレートは手動で設定する場合にのみ使用してください。

アプリのエントリーポイント（src/main.ts）で Auth0 Vue プラグインを登録し、Capacitor 用に設定します。認証情報は import.meta.env を介して .env から読み込まれます。

import { createApp } from 'vue';
import { createAuth0 } from '@auth0/auth0-vue';
import { IonicVue } from '@ionic/vue';
import App from './App.vue';
import router from './router';

// Agent: read appId from capacitor.config.ts and replace this value
const packageId = "YOUR_PACKAGE_ID";

const app = createApp(App);

app.use(IonicVue);
app.use(router);
app.use(
  createAuth0({
    domain: import.meta.env.VITE_AUTH0_DOMAIN,
    clientId: import.meta.env.VITE_AUTH0_CLIENT_ID,
    useRefreshTokens: true,
    useRefreshTokensFallback: false,
    authorizationParams: {
      redirect_uri: `${packageId}://${import.meta.env.VITE_AUTH0_DOMAIN}/capacitor/${packageId}/callback`
    }
  })
);

router.isReady().then(() => {
  app.mount('#app');
});

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

<script setup lang="ts">
import { useAuth0 } from '@auth0/auth0-vue';
import { Browser } from '@capacitor/browser';
import { IonButton } from '@ionic/vue';

const { loginWithRedirect } = useAuth0();

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

<template>
  <ion-button @click="login">Log in</ion-button>
</template>

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

App.vue コンポーネントでディープリンクのコールバックを処理します。これはアプリの初期化時に実行する必要があります。

<script setup lang="ts">
import { onMounted, onUnmounted } from 'vue';
import { useAuth0 } from '@auth0/auth0-vue';
import { App as CapApp } from '@capacitor/app';
import { Browser } from '@capacitor/browser';
import { IonApp, IonRouterOutlet } from '@ionic/vue';

const { handleRedirectCallback } = useAuth0();

let urlOpenListener: any;

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

onUnmounted(() => {
  urlOpenListener?.remove();
});
</script>

<template>
  <ion-app>
    <ion-router-outlet />
  </ion-app>
</template>

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

<script setup lang="ts">
import { useAuth0 } from '@auth0/auth0-vue';
import { Browser } from '@capacitor/browser';
import { IonButton } from '@ionic/vue';

const domain = import.meta.env.VITE_AUTH0_DOMAIN;
// Agent: read appId from capacitor.config.ts and replace this value
const packageId = "YOUR_PACKAGE_ID";
const logoutUri = `${packageId}://${domain}/capacitor/${packageId}/callback`;

const { logout } = useAuth0();

const doLogout = async () => {
  await logout({
    logoutParams: {
      returnTo: logoutUri
    },
    async openUrl(url: string) {
      await Browser.open({ url, windowName: "_self" });
    }
  });
};
</script>

<template>
  <ion-button @click="doLogout">Log out</ion-button>
</template>

ステップ 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 によるログイン／ログアウト、ディープリンクのコールバック処理、ユーザープロフィール、保護されたルート、トークンへのアクセス、エラー処理
• テストとリファレンス — createAuth0 のオプション、useAuth0 コンポーザブル、Capacitor プラグインの設定、テストチェックリスト、よくある問題に関する API リファレンス一式

よくある間違い

間違い	修正方法
Auth0 Dashboard でアプリの種類が Native に設定されていない	Dashboard の設定でアプリケーションの種類を「Native」に変更します
コールバック URL の形式が正しくない、または設定されていない	YOUR_PACKAGE_ID://YOUR_DOMAIN/capacitor/YOUR_PACKAGE_ID/callback を使用します。完全に一致している必要があります
リフレッシュトークンが有効になっていない	createAuth0() で 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 を追加します
マウント前に app.use(createAuth0(...)) を呼び出していない	app.mount('#app') を呼び出す前に Auth0 プラグインを登録します
auth の ref で .value に正しくアクセスしていない	useAuth0() は Vue の ref を返します。<script> 内では .value を使用し、テンプレートでは自動的にアンラップされます
モバイルで localStorage が永続化されるものとして扱っている	トークンを確実に永続化するには、リフレッシュトークン（useRefreshTokens: true）を使用します

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

クイックリファレンス

API	説明
createAuth0(options)	Vue プラグインファクトリー — app.use() で Auth0 を登録します
useAuth0()	コンポーザブル — { isLoading, isAuthenticated, user, loginWithRedirect, logout, getAccessTokenSilently, handleRedirectCallback, error } を返します
loginWithRedirect({ openUrl })	Universal Login によるログイン — openUrl コールバックで Browser.open() を使用します
logout({ logoutParams, openUrl })	ログアウト — openUrl コールバックで Browser.open() を使用します
handleRedirectCallback(url)	ディープリンクから受け取った Auth0 のコールバック URL を処理します
getAccessTokenSilently()	アクセストークンを取得します（モバイルではリフレッシュトークンを使用します）
createAuthGuard(app)	保護されたルート用の Vue Router ナビゲーションガードファクトリー
Browser.open({ url })	Capacitor — システムブラウザーで URL を開きます（SFSafariViewController／Chrome Custom Tabs）
CapApp.addListener('appUrlOpen', cb)	Capacitor — ディープリンクイベントをリッスンします
Browser.close()	Capacitor — コールバック後にアプリ内ブラウザーを閉じます

参考資料

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