Ionic Vue と Capacitor を使ったアプリケーションにログインを追加する

このガイドでは、Auth0 Vue SDK を使用して、Ionic Vue と Capacitor のアプリケーションに Auth0 を統合する方法を説明します。

AI を使って Auth0 を連携する

Claude Code、Cursor、GitHub Copilot などの AI コーディングアシスタントを使えば、agent skills を利用して、数分で Auth0 認証を自動的に追加できます。 まず、Auth0 agent skills をインストールします。

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

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

Add Auth0 authentication to my Ionic Vue app

AI アシスタントが、Auth0 アプリケーションの作成、資格情報の取得、Auth0 Vue SDK と Capacitor プラグインのインストール、ディープリンクの設定、さらにネイティブ ブラウザー連携によるログイン/ログアウト フローの実装まで、自動的に行います。Auth0 agent skills の詳細をご覧ください。

​

はじめに

このクイックスタートでは、Capacitor を使用して iOS と Android で動作する Ionic Vue アプリケーションに Auth0 認証を追加する方法を説明します。Auth0 Vue SDK と Capacitor のネイティブブラウザプラグインを使用して、ログイン、ログアウト、ユーザープロファイル機能を備えた安全なモバイルアプリを構築します。

1. 新規プロジェクトを作成する

   Capacitor で新しい Ionic Vue プロジェクトを作成する

   npx ionic start auth0-ionic-vue blank --type=vue --capacitor
   

   プロジェクトを開く

   cd auth0-ionic-vue
   

   @ionic/cli パッケージ (非推奨の ionic パッケージではなく) を使用していることを確認してください。プロジェクトの作成時に --npm-client に関するエラーが表示される場合は、CLI を更新してください。

   npm uninstall -g ionic
   npm i -g @ionic/cli
   
2. Auth0 Vue SDK と Capacitor プラグインのインストール

   npm install @auth0/auth0-vue @capacitor/browser @capacitor/app
   

   @capacitor/browser は、セキュアな認証のために、Auth0 Universal Login ページをデバイスのシステムブラウザー (iOS では SFSafariViewController、Android では Chrome Custom Tabs) で開きます。

   @capacitor/app はディープリンクイベントを監視し、ログイン後に Auth0 がリダイレクトした際の OAuth コールバックをアプリで処理できるようにします。

3. Auth0 App の設定

   次に、Auth0 テナントに新しいアプリを作成します。Ionic Capacitor アプリでは、カスタム URL スキームのコールバックを使用する Native アプリケーションタイプを使用します。

   Auth0 アプリの設定方法は 3 つあります。Quick Setup ツール (推奨) を使う方法、CLI コマンドを実行する方法、または Auth0 Dashboard で手動設定する方法です。

   Quick Setup (推奨)

   Auth0 の Native アプリケーションを作成し、資格情報を取得します。

   アプリを作成したら、次の手順で使用する Domain と Client ID の値を控えておきます。

   callback URL と logout URL も Auth0 Dashboard で設定する必要があります。詳しくは、以下の URL 設定を参照してください。

   CLI

   Auth0 アプリを作成するには、プロジェクトのルートディレクトリで次のコマンドを実行します。

   Mac

   # Auth0 CLI をインストールします（未インストールの場合）
   brew tap auth0/auth0-cli && brew install auth0
   
   # Auth0 アプリを設定し、.env ファイルを生成します
   auth0 qs setup --app --type native --framework ionic-vue --build-tool vite --name "My Ionic Vue App"
   

   このコマンドでは、次の処理が行われます。

   1. 認証済みかどうかを確認します (必要に応じてログインが求められます)
   2. Auth0 Native アプリケーションを作成します
   3. Auth0 ドメインとクライアント ID を含む .env ファイルを生成します

   Dashboard

   1. Auth0 Dashboard に移動します
   2. アプリケーション > アプリケーション > Create Application をクリックします
   3. アプリの名前 (例: Ionic Vue App) を入力し、アプリケーションタイプとして Native を選択して、Create をクリックします
   4. 設定 タブに切り替え、Domain と Client ID の値を控えます

   このガイドでは、YOUR_PACKAGE_ID はアプリケーションのパッケージ ID を指します。これは capacitor.config.ts ファイルの appId フィールドで確認および設定できます。詳しくは Capacitor の Config schema を参照してください。

   アプリケーション詳細ページの 設定 タブで、次の URL を設定します。

   Allowed Callback URLs:

   YOUR_PACKAGE_ID://{yourDomain}/capacitor/YOUR_PACKAGE_ID/callback
   

   Allowed Logout URLs:

   YOUR_PACKAGE_ID://{yourDomain}/capacitor/YOUR_PACKAGE_ID/callback
   

   Allowed Origins:

   capacitor://localhost, http://localhost
   

   Allowed Callback URLs は、authentication の完了後にユーザーを安全にアプリケーションへ戻すための重要なセキュリティ対策です。一致する URL がないと、ログインプロセスは失敗し、ユーザーはアプリにアクセスできず、代わりに Auth0 のエラーページが表示されます。

   Allowed Logout URLs は、サインアウト時にシームレスな user experience を提供するために重要です。一致する URL がない場合、ユーザーは logout の後にアプリケーションへリダイレクトされず、代わりに汎用的な Auth0 ページに残ります。

   Allowed Origins には、ネイティブアプリから Auth0 への request のために capacitor://localhost (iOS) と http://localhost (Android) を含める必要があります。

   Quick Setup または CLI を使用した場合は、Auth0 Dashboard でアプリの 設定 タブを開き、上記の Dashboard タブに記載されている callback URL と logout URL を設定してください。

4. Auth0プラグインを設定する

   src/main.ts

   import { createApp } from 'vue'
   import App from './App.vue'
   import router from './router'
   import { IonicVue } from '@ionic/vue'
   import { createAuth0 } from '@auth0/auth0-vue'
   import config from '../capacitor.config'
   
   // アプリのパッケージIDを使ってコールバックURLを構築する
   const redirect_uri = `${config.appId}://{yourDomain}/capacitor/${config.appId}/callback`
   
   const app = createApp(App)
     .use(IonicVue)
     .use(router)
   
   app.use(
     createAuth0({
       domain: '{yourDomain}',
       clientId: '{yourClientId}',
       useRefreshTokens: true,
       useRefreshTokensFallback: false,
       authorizationParams: {
         redirect_uri,
       },
     })
   )
   
   router.isReady().then(() => {
     app.mount('#app')
   })
   

   • useRefreshTokens: true — モバイルブラウザーではサードパーティ Cookie がブロックされるため、iframe ベースのサイレント認証は動作しません。リフレッシュトークンは /oauth/token エンドポイントを直接呼び出します。
   • useRefreshTokensFallback: false — モバイルでは利用できない iframe ベースのフォールバックを SDK が試行しないようにします。
   • router.isReady().then(...) — SDK が OAuth コールバックを処理する前に Vue Router が完全に初期化されるようにし、競合状態を防ぎます。

   アプリケーションを閉じて再度開いた後も認証状態を維持するには、cacheLocation を localstorage に設定するとよい場合がありますが、localstorage にトークンを保存することのリスクに注意してください。また、Capacitor アプリではデータが予期せず復元される可能性があるため、localstorage は 一時的 なものとして扱う必要があります。あわせて、Capacitor ドキュメントのストレージに関するガイダンスもご確認ください。

5. 認証コンポーネントを作成する

   コンポーネントファイルを作成する

   Mac/Linux

   mkdir -p src/components && touch src/components/LoginButton.vue && touch src/components/LogoutButton.vue && touch src/components/UserProfile.vue
   

   以下のコードを新しいコンポーネントに追加し、既存のApp.vueとHomePage.vueを更新してください。

6. アプリを起動する

   まずはブラウザでテストしましょう：

   ionic serve
   

   ionic serve を使用してブラウザーで実行する場合、ブラウザーはカスタム URL スキームを処理できないため、カスタム URL スキームのリダイレクトは機能しません。ブラウザーでテストするには、src/main.ts の redirect_uri を一時的に http://localhost:8100 に変更し、Auth0 Dashboard の Auth0 アプリにある Allowed Callback URLs と Allowed Logout URLs に http://localhost:8100 を追加してください。Native 向けにビルドする前に、この変更を元に戻すことを忘れないでください。

   デバイスまたはシミュレーターで実行するには、まず Native プラットフォームを追加します。

   npx cap add ios
   npx cap add android
   

   次に、ビルド、同期、実行を行います。

   iOS

   ionic build && npx cap sync && npx cap run ios
   

   実行する前に、npx cap add を使って Native プラットフォームを追加する必要があります。これは各プラットフォームにつき一度だけ行えば十分です。事前に、そのプラットフォーム用のカスタム URL スキームを登録しておいてください。

Checkpoint

これで、Ionic Vueアプリケーションで、ログイン、ログアウト、ユーザープロファイル情報を備えた、Auth0によるログイン機能がひととおり利用できるようになりました。

---

​

高度な使い方

カスタムURLスキームの設定

認証後に OAuth コールバックをアプリに戻せるように、OS がルーティングできるようアプリのカスタム URL スキームを登録します。

​

iOS

ios/App/App/Info.plist でカスタム URL スキームを登録します。

<key>CFBundleURLTypes</key>
<array>
  <dict>
    <key>CFBundleURLSchemes</key>
    <array>
      <string>YOUR_PACKAGE_ID</string>
    </array>
  </dict>
</array>

YOUR_PACKAGE_ID は、capacitor.config.ts の appId に置き換えてください。詳しくは、Defining a Custom URL Scheme を参照してください。

​

Android

android/app/src/main/AndroidManifest.xml のメイン <activity> タグ内にインテントフィルタを追加します。

<intent-filter>
  <action android:name="android.intent.action.VIEW" />
  <category android:name="android.intent.category.DEFAULT" />
  <category android:name="android.intent.category.BROWSABLE" />
  <data android:scheme="YOUR_PACKAGE_ID" />
</intent-filter>

詳しくは、Create Deep Links to App Content を参照してください。

ネイティブプロジェクトのファイルを変更したら、変更を反映するために npx cap sync を実行してください。

Vue Router でルートを保護する

authentication が必要なルートを保護するには、Auth0 Vue SDK に組み込まれている authGuard を使用します。

src/router/index.ts

import { createRouter, createWebHistory } from '@ionic/vue-router'
import { authGuard } from '@auth0/auth0-vue'
import HomePage from '../views/HomePage.vue'
import ProfilePage from '../views/ProfilePage.vue'

const routes = [
  {
    path: '/',
    name: 'Home',
    component: HomePage,
  },
  {
    path: '/profile',
    name: 'Profile',
    component: ProfilePage,
    beforeEnter: authGuard,
  },
]

const router = createRouter({
  history: createWebHistory(import.meta.env.BASE_URL),
  routes,
})

export default router

authGuard は、未認証のユーザーを自動的に Auth0 Universal Login ページへリダイレクトします。ログイン後は、最初にアクセスしようとしていたルートに戻ります。

保護された API を呼び出す

API 用のアクセストークンをリクエストするには、createAuth0 の設定で audience パラメータを設定します。

src/main.ts

app.use(
  createAuth0({
    domain: '{yourDomain}',
    clientId: '{yourClientId}',
    useRefreshTokens: true,
    useRefreshTokensFallback: false,
    authorizationParams: {
      redirect_uri,
      audience: 'YOUR_API_IDENTIFIER',
    },
  })
)

次に、コンポーネント内で getAccessTokenSilently を使ってトークンを取得し、認証付きの API 呼び出しを行います。

src/components/ApiCall.vue

<template>
  <ion-button @click="callApi" :disabled="loading">
    {{ loading ? 'Calling...' : 'Call Protected API' }}
  </ion-button>
  <pre v-if="response">{{ JSON.stringify(response, null, 2) }}</pre>
</template>

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

const { getAccessTokenSilently } = useAuth0()
const response = ref(null)
const loading = ref(false)

const callApi = async () => {
  try {
    loading.value = true
    const token = await getAccessTokenSilently()

    const res = await fetch('https://your-api.com/endpoint', {
      headers: {
        Authorization: `Bearer ${token}`,
      },
    })

    response.value = await res.json()
  } catch (error) {
    console.error('API call failed:', error)
  } finally {
    loading.value = false
  }
}
</script>

getAccessTokenSilently メソッドは、キャッシュからトークンを取得するか、必要に応じてリフレッシュトークンを使って自動的に更新します。

defineComponent パターンを使用する

<script setup> よりも明示的な defineComponent パターンを使いたい場合、LoginButton コンポーネントは次のようになります。

src/components/LoginButton.vue

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

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

export default defineComponent({
  components: { IonButton },
  setup() {
    const { loginWithRedirect } = useAuth0()

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

    return { login }
  },
})
</script>

defineComponent パターンでは、子コンポーネントを明示的に登録し、setup() 関数から値を返す必要があります。どちらのパターンも Auth0 Vue SDK で完全にサポートされています。

よくある問題と解決策

​

コールバック URL の不一致エラー

解決策: Auth0 Dashboard のコールバック URL が、アプリケーションで生成される URL と完全に一致していることを確認してください。YOUR_PACKAGE_ID が capacitor.config.ts の appId フィールドと一致していることも確認してください。

​

「PKCE not allowed」エラー

対処方法:

1. Auth0 Dashboard > アプリケーション > Your Application に移動します
2. Application Type を Native に変更します
3. Token Endpoint Authentication Method を None に設定します
4. 変更を保存して、もう一度試します

​

iOS で SSO が機能しない

Capacitor の Browser Plugin は SFSafariViewController を使用しており、iOS 11 以降では Safari と Cookie を共有しません。SSO が必要な場合は、ASWebAuthenticationSession を使用する互換性のあるプラグインを使ってください。

​

ログインは成功するが、アプリを再起動するとユーザーが未認証のままになる

アプリの再起動後もトークンを保持するには、createAuth0 の設定で cacheLocation: 'localstorage' を有効にしてください。セキュリティ上の影響がある点に注意してください。SDK は、より安全な保存のための custom cache implementations もサポートしています。

​

ログイン後にブラウザーが閉じない

App.vue コンポーネント内の appUrlOpen イベントリスナーで Browser.close() を呼び出していることを確認してください。Android では Browser.close() は no-op のため、ブラウザーは自動的に閉じます。

​

ログインページがデバイスの既定のブラウザーアプリで開く

ログインページがアプリ内ブラウザーのオーバーレイではなく Safari や Chrome で開く場合は、openUrl コールバックを loginWithRedirect と logout に渡していることを確認してください。これを渡さないと、SDK はデフォルトで window.location.href を使用し、アプリ全体が遷移してしまいます。