auth0-ionic-angular

Auth0 Ionic Angular（Capacitor）連携

@auth0/auth0-angular SDK と Capacitor プラグインを使用して、Ionic Angular アプリケーションに認証機能を追加します。ログイン、ログアウト、ユーザープロフィールの表示、そして Capacitor の Browser プラグインを介したシステムブラウザー（iOS では SFSafariViewController、Android では Chrome Custom Tabs）による安全なトークン管理について説明します。

前提条件

• Node.js 20 以降、npm 10 以降
• Ionic CLI（npm install -g @ionic/cli）
• プロジェクトで Capacitor 5 以降が設定済みであること
• Auth0 CLI（自動セットアップ用）：brew install auth0/auth0-cli/auth0
• Auth0 アカウント（無料プランで利用できます）

使用しない場合

使用ケース	推奨スキル
Capacitor を使用する Ionic React アプリ	auth0-ionic-react
Capacitor を使用する Ionic Vue アプリ	auth0-ionic-vue
Angular SPA（ブラウザー専用、Capacitor なし）	auth0-angular または auth0-react
React Native（Ionic なし）	auth0-react-native
Expo（React Native）	auth0-expo
ネイティブ iOS（Swift）	auth0-swift
ネイティブ Android（Kotlin）	auth0-android

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

エージェントへの指示： 以下の手順を順番に実行してください。プロンプトに認証情報がすでに含まれている場合でも、先に進む前に必ず AskUserQuestion を使用して、開発者に自動セットアップと手動セットアップのどちらを選ぶか尋ねてください。

セキュリティ — 認証情報を表示しないでください： CLI またはファイルから Auth0 の認証情報（ドメイン、クライアント ID）を取得した後、それらをテキスト出力に表示、エコー、出力してはなりません。設定ファイル（src/environments/environment.ts）に直接、出力せずに書き込んでください。「Domain: xxx」や「Client ID: yyy」のような出力をしてはなりません。代わりに、設定ファイルを書き込んだことを確認し、ファイルの場所をユーザーに伝えてください。

UI の再利用： 新しいログイン／ログアウトコンポーネントを作成する前に、既存のプロジェクト内でログイン／ログアウトのハンドラーやボタンを検索してください。見つかった場合は、重複したコンポーネントを作成せず、既存の UI に Auth0 を組み込んでください。

ステップ 1：依存関係のインストール

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

ステップ 2：Auth0 の設定

エージェントへの指示： ユーザーがすでに認証情報を提供している場合でも、必ず AskUserQuestion を使用してセットアップ方法を提示してください。

AskUserQuestion:
  question: "Ionic Angular アプリの Auth0 をどのように設定しますか？"
  options:
    - label: "自動セットアップ（推奨）"
      description: "Auth0 CLI を使用してネイティブアプリケーションを作成し、コールバック URL を設定して、プロジェクトに認証情報を自動的に保存します。"
    - label: "手動セットアップ"
      description: "Auth0 ドメインとクライアント ID を含む .env ファイルを用意していただき、エージェントがそれを読み込んでプロジェクト設定に書き込みます。"

どちらの方法を選んだ場合も、両方の方法の手順を詳しく説明したセットアップガイドに従ってください。

Auth0 ダッシュボードの設定（アプリケーションタイプ：Native）：

設定	値
アプリケーションタイプ	Native
許可されたコールバック URL	PACKAGE_ID://YOUR_DOMAIN/capacitor/PACKAGE_ID/callback
許可されたログアウト URL	PACKAGE_ID://YOUR_DOMAIN/capacitor/PACKAGE_ID/callback
許可されたオリジン	capacitor://localhost, http://localhost

PACKAGE_ID は capacitor.config.ts の appId（例：com.example.myapp）に、YOUR_DOMAIN は Auth0 ドメインに置き換えてください。

注： 自動セットアップでは、これらの URL は Auth0 CLI によって自動的に設定されます。手動セットアップでは、ユーザーが Auth0 ダッシュボードで設定する必要があります。

注： ローカルで Web 開発（ionic serve）を行う場合は、許可されたコールバック URL、許可されたログアウト URL、および許可された Web オリジンにも http://localhost:8100 を追加してください。

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

src/app/app.module.ts（NgModule）または src/app/app.config.ts（スタンドアロン）で設定します。

provideAuth0() 関数（または AuthModule.forRoot()）は、Angular における Auth0Provider に相当します。アプリをラップするプロバイダー／ラッパーとして機能し、AuthService をアプリ全体で利用できるようにします。ionic serve でローカルの Web 開発を行う場合、コールバック URL は http://localhost:8100 です。

スタンドアロン（Angular 17 以降）：

import { ApplicationConfig } from '@angular/core';
import { provideAuth0 } from '@auth0/auth0-angular';

// Replace with your capacitor.config.ts appId and Auth0 domain
const appId = 'com.example.myapp';
const domain = 'YOUR_AUTH0_DOMAIN';
const callbackUri = `${appId}://${domain}/capacitor/${appId}/callback`;

export const appConfig: ApplicationConfig = {
  providers: [
    provideAuth0({
      domain,
      clientId: 'YOUR_AUTH0_CLIENT_ID',
      useRefreshTokens: true,
      useRefreshTokensFallback: false,
      authorizationParams: {
        redirect_uri: callbackUri,
      },
    }),
  ],
};

NgModule（Angular 16 以前）：

import { AuthModule } from '@auth0/auth0-angular';

const appId = 'com.example.myapp';
const domain = 'YOUR_AUTH0_DOMAIN';
const callbackUri = `${appId}://${domain}/capacitor/${appId}/callback`;

@NgModule({
  imports: [
    AuthModule.forRoot({
      domain,
      clientId: 'YOUR_AUTH0_CLIENT_ID',
      useRefreshTokens: true,
      useRefreshTokensFallback: false,
      authorizationParams: {
        redirect_uri: callbackUri,
      },
    }),
  ],
})
export class AppModule {}

ステップ 4：ディープリンクのコールバックを処理する（AppComponent）

ナビゲーション中もリスナーが維持されるよう、アプリのルートで appUrlOpen リスナーを登録します。

import { Component, NgZone, OnInit } from '@angular/core';
import { AuthService } from '@auth0/auth0-angular';
import { Browser } from '@capacitor/browser';
import { App as CapApp } from '@capacitor/app';
import { mergeMap } from 'rxjs/operators';

@Component({
  selector: 'app-root',
  template: `<ion-app><ion-router-outlet></ion-router-outlet></ion-app>`,
})
export class AppComponent implements OnInit {
  constructor(
    private auth: AuthService,
    private ngZone: NgZone
  ) {}

  ngOnInit() {
    CapApp.addListener('appUrlOpen', ({ url }) => {
      this.ngZone.run(() => {
        if (url.includes('state') && (url.includes('code') || url.includes('error'))) {
          this.auth
            .handleRedirectCallback(url)
            .pipe(mergeMap(() => Browser.close()))
            .subscribe();
        }
      });
    });
  }
}

ステップ 5：ログインを実装する

import { Component } from '@angular/core';
import { AuthService } from '@auth0/auth0-angular';
import { Browser } from '@capacitor/browser';

@Component({
  selector: 'app-login',
  template: `<ion-button (click)="login()">Log In</ion-button>`,
})
export class LoginPage {
  constructor(public auth: AuthService) {}

  login() {
    this.auth
      .loginWithRedirect({
        async openUrl(url: string) {
          await Browser.open({ url, windowName: '_self' });
        },
      })
      .subscribe();
  }
}

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

import { Component } from '@angular/core';
import { AuthService } from '@auth0/auth0-angular';
import { Browser } from '@capacitor/browser';

@Component({
  selector: 'app-logout-button',
  template: `<ion-button (click)="logout()">Log Out</ion-button>`,
})
export class LogoutButtonComponent {
  constructor(public auth: AuthService) {}

  logout() {
    this.auth
      .logout({
        logoutParams: {
          returnTo: `YOUR_PACKAGE_ID://YOUR_AUTH0_DOMAIN/capacitor/YOUR_PACKAGE_ID/callback`,
        },
        async openUrl(url: string) {
          await Browser.open({ url, windowName: '_self' });
        },
      })
      .subscribe();
  }
}

ステップ 7：ユーザープロファイルを表示する

import { Component } from '@angular/core';
import { AuthService } from '@auth0/auth0-angular';
import { AsyncPipe } from '@angular/common';

@Component({
  selector: 'app-profile',
  template: `
    <div *ngIf="auth.user$ | async as user">
      <img [src]="user.picture" [alt]="user.name" />
      <h2>{{ user.name }}</h2>
      <p>{{ user.email }}</p>
    </div>
  `,
})
export class ProfileComponent {
  constructor(public auth: AuthService) {}
}

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

エージェントへの指示： すべてのコードを書いた後、ビルドが成功することを確認してください。

npm run build
npx cap sync

ビルドが失敗した場合は、エラーを調査して修正してください（最大 5～6 回繰り返します）。それでも失敗する場合は、AskUserQuestion を使用してユーザーにサポートを求めてください。

詳細ドキュメント

• セットアップガイド — Auth0 の設定、Auth0 CLI のセットアップ、Capacitor プラットフォームのセットアップ、ディープリンク
• 統合パターン — ログイン／ログアウトのフロー、トークン管理、ユーザープロファイル、エラー処理、Capacitor のライフサイクル
• API リファレンスとテスト — AuthService API、設定オプション、クレームのリファレンス、テストチェックリスト

よくある間違い

間違い	修正方法
Auth0 アプリのタイプが Native ではなく SPA に設定されている	Auth0 ダッシュボードの「Application Settings」で Native に変更します
Auth0 ダッシュボードにコールバック URL がない	PACKAGE_ID://{domain}/capacitor/PACKAGE_ID/callback を「Allowed Callback URLs」と「Allowed Logout URLs」の両方に追加します
handleRedirectCallback を ngZone.run() で囲んでいない	Angular が認証状態の変更を検出できません。必ず ngZone.run() で囲みます
ログインのリダイレクトに window.location.href を使用している	システムブラウザーには @capacitor/browser の Browser.open() を使用する必要があります
useRefreshTokens が true に設定されていない	モバイルでは必須です。ネイティブプラットフォームでは localStorage の信頼性が低いためです
useRefreshTokensFallback が false に設定されていない	iframe ベースのトークン更新（モバイルでは非対応）へのフォールバックを避けるため、false にする必要があります
ディープリンク用の @capacitor/app リスナーがない	システムブラウザーからのコールバックを処理するには、appUrlOpen リスナーが必要です
モバイルで loginWithPopup を使用している	ネイティブではポップアップが動作しません。Browser.open と loginWithRedirect を使用します
コールバック URL が一致しない（スキームとパッケージ ID）	URL スキームは capacitor.config.ts の appId と完全に一致する必要があります

WebAuth メソッド

Capacitor を使用する Ionic では、認証に Web Auth メソッドを使用します。

1. ユーザーが Log In をタップ → アプリが Browser.open() を使用するカスタム openUrl を指定して loginWithRedirect を呼び出します
2. Capacitor の Browser プラグインが、システムブラウザーで Auth0 Universal Login ページを開きます（SFSafariViewController／Chrome Custom Tabs）
3. ユーザーが認証 → Auth0 がカスタム URL スキームのコールバックにリダイレクトします
4. OS がディープリンクをアプリに転送 → appUrlOpen イベントが発生します
5. handleRedirectCallback(url) が ngZone.run() 内で認証コードの交換を処理します
6. Browser.close() がシステムブラウザーを閉じます
7. auth.isAuthenticated$ が true を通知し、auth.user$ がユーザープロファイルを通知します

関連スキル

• auth0-ionic-react — Capacitor を使用する Ionic React
• auth0-ionic-vue — Capacitor を使用する Ionic Vue
• auth0-angular — Angular SPA（ブラウザーのみ）
• auth0-swift — ネイティブ iOS（Swift）
• auth0-android — ネイティブ Android（Kotlin）

クイックリファレンス

API	説明
AuthService.loginWithRedirect(options)	Capacitor 用にカスタムの openUrl を指定して、ログインフローを開始します
AuthService.logout(options)	カスタムの openUrl と returnTo を指定して、ログアウトします
AuthService.handleRedirectCallback(url)	ディープリンクからのコールバック URL を処理します
AuthService.isAuthenticated$	Observable の boolean 値 — ユーザーがログインしているかどうか
AuthService.user$	Observable — 現在のユーザープロフィール（名前、メールアドレス、画像）
AuthService.isLoading$	Observable の boolean 値 — SDK の初期化状態
AuthService.error$	Observable — 認証エラー
AuthService.getAccessTokenSilently()	アクセストークンを取得します（モバイルではリフレッシュトークンを使用します）
Browser.open({ url })	システムブラウザーで URL を開きます（Capacitor）
CapApp.addListener('appUrlOpen', cb)	ディープリンクのコールバックをリッスンします（Capacitor）

参考資料

• Auth0 Angular SDK — GitHub
• Auth0 Ionic Angular クイックスタート
• Auth0 Angular SDK — API リファレンス
• Capacitor Browser プラグイン
• Capacitor App プラグイン — ディープリンク
• Ionic フレームワーク — Angular