auth0-swift

Auth0 Swift の統合

Auth0.swift は Apple プラットフォーム（iOS、macOS、tvOS、watchOS、visionOS）向けの公式 Auth0 SDK です。このスキルでは、Web 認証（システムブラウザーへのリダイレクト）、CredentialsManager による安全な Keychain 認証情報の保存、オプションの生体認証保護を利用して、Swift アプリにネイティブ認証機能を追加します。

使用しない場合

• Android アプリ：auth0-android を使用してください
• React Native アプリ：auth0-react-native を使用してください
• Flutter アプリ：ネイティブの Flutter Auth0 SDK を使用してください
• Web SPA（React、Angular、Vue）：auth0-react、auth0-angular、または auth0-vue を使用してください
• Node.js/Express サーバー：auth0-express を使用してください

前提条件

• iOS 14.0 以降 / macOS 11.0 以降 / tvOS 14.0 以降 / watchOS 7.0 以降 / visionOS 1.0 以降
• Xcode 16.x
• Swift 6.0 以降
• Auth0 アカウント — 無料で登録
• Auth0 CLI — brew install auth0/auth0-cli/auth0（セットアップの自動化用）

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

エージェントへの指示： 次の手順を順番に実行してください。いずれかの手順でエラーが発生した場合は、ユーザーに案内を求めるために AskUserQuestion を呼び出す前に、最大 5 回まで修正を試みてください。必ず既存のコードを先に検索してください。ログイン／ログアウトのハンドラーがすでにある場合は、新しいものを作成せず、既存のものに接続してください。

重要 — 認証情報のプライバシー： Auth0 の認証情報（ドメイン、クライアント ID、クライアントシークレット）を、応答テキストやターミナル出力に絶対に表示しないでください。Write または Edit ツールを使用して、設定ファイルに直接書き込んでください。これらの値を含む出力が生成される Auth0 CLI コマンドを実行する場合は、出力をファイルにリダイレクトし、プログラムから読み取ってください。例：

auth0 apps create ... --json --no-input > /tmp/auth0-output.json 2>&1

次に、Read ツールを使用して /tmp/auth0-output.json から必要な値を抽出し、Auth0.plist またはその他の設定ファイルに直接書き込んでください。応答テキストやターミナルには絶対に表示しないでください。ユーザーにアクティブなテナントを確認するときは、マスクした形式（例：your-te****.us.auth0.com）を使用してください。

ステップ 1 — SDK をインストールする

エージェントへの指示： プロジェクトディレクトリに、既存のパッケージマネージャーのファイルがあるか確認してください：

• Podfile がある → CocoaPods
• Cartfile がある → Carthage
• Package.swift がある → Swift Package Manager

どれも見つからない場合は、AskUserQuestion を使って次のように尋ねてください："プロジェクトではどの依存関係マネージャーを使用していますか — Swift Package Manager、CocoaPods、Carthage のいずれですか？"

Swift Package Manager — Package.swift プロジェクト： プロジェクトのルートで次のコマンドを実行して依存関係を自動的に追加し、その後 Package.swift のターゲットの dependencies 配列に "Auth0" を追加してください：

swift package add-dependency https://github.com/auth0/Auth0.swift --from 2.18.0

Swift Package Manager — Xcode プロジェクト（.xcodeproj、Package.swift なし）： CLI コマンドは使用できません。Xcode からパッケージを追加するようユーザーに案内してください：File → Add Package Dependencies → https://github.com/auth0/Auth0.swift → Up to Next Major Version（2.18.0 以降）。

CocoaPods または Carthage： セットアップガイドの該当するインストール手順に従ってください。手順を提示するだけではなく、ファイルを編集してコマンドを実行してください。

ステップ 2 — Auth0 を設定する

エージェントへの指示：

• Auth0 の認証情報（ドメインとクライアント ID の両方）がすでにユーザーのプロンプトに含まれている場合： その値を使って Auth0.plist を直接作成します。ユーザーに質問してはいけません。Swift のソースファイルに値をハードコードしたり、Auth0.webAuth() や Auth0.authentication() の引数として渡したりしてはいけません。SDK は Auth0.plist を自動的に読み込むため、引数なしの形式 Auth0.webAuth() を必ず使用してください。その後、ステップ 3 に進みます。
• プロジェクトに Auth0.plist ファイルがすでに存在する場合： ファイルを読み込んで ClientId と Domain を取得し、ステップ 3 に進みます。
• Auth0.plist が存在せず、認証情報も提供されていない場合： AskUserQuestion を使ってユーザーに次のように質問します：「Auth0 をどのように設定しますか？」
  • 自動（Auth0 CLI） — Auth0 CLI を使ってアプリケーションを作成し、コールバック URL を設定して、すべてを構成します。
  • 手動 — ユーザーが事前設定済みの Auth0.plist ファイルを用意し、それをプロジェクトに追加します。

ユーザーが自動を選んだ場合：セットアップガイド — Auth0 CLI による自動セットアップに従います。 ユーザーが手動を選んだ場合：セットアップガイド — 手動セットアップに従います。

Auth0.plist の形式：

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
  <key>ClientId</key>
  <string>YOUR_CLIENT_ID</string>
  <key>Domain</key>
  <string>YOUR_DOMAIN</string>
</dict>
</plist>

SDK が自動的に見つけられるよう、Auth0.plist をアプリの Swift ソースファイルと同じディレクトリに配置します。

ステップ 3 — コールバック URL を設定する

エージェントへの指示：

1. Auth0.plist を読み込んで ClientId と Domain を取得します。
2. project.pbxproj からバンドル識別子を抽出します：PRODUCT_BUNDLE_IDENTIFIER を検索し、$( または Tests を含む値は除外します。
3. AskUserQuestion を使ってユーザーに次のように質問します：「どのコールバック URL スキームを使用しますか？」
   • カスタムスキーム（{bundle}://）— より簡単で、すべての Apple プラットフォームで動作します
   • HTTPS ユニバーサルリンク — 本番環境で推奨されます。URL スキームの乗っ取りを防ぎます

次に、以下の該当する手順のみに従います。

パス A — カスタムスキーム

エージェントへの指示： Auth0 CLI を使ってコールバック URL を登録します（CLIENT_ID、BUNDLE_ID、DOMAIN を実際の値に置き換えます）。

まず、既存の URL を上書きしないよう、現在のコールバック URL とログアウト URL を取得します：

auth0 apps show CLIENT_ID --json --no-input > /tmp/auth0-app-info.json 2>&1

/tmp/auth0-app-info.json を読み込み、既存の callbacks と allowed_logout_urls の配列を抽出します。

次に、既存の URL があれば、新しい URL とカンマ区切りのリストにして指定します：

auth0 apps update CLIENT_ID \
  --callbacks "EXISTING_CALLBACKS,BUNDLE_ID://DOMAIN/ios/BUNDLE_ID/callback" \
  --logout-urls "EXISTING_LOGOUT_URLS,BUNDLE_ID://DOMAIN/ios/BUNDLE_ID/callback" \
  --no-input > /dev/null 2>&1

既存の URL がない場合は、EXISTING_ の部分を省略し、新しい URL のみを使用します。

次に、Xcode で $(PRODUCT_BUNDLE_IDENTIFIER) を URL タイプとして登録するため、セットアップガイドの URL スキーム登録手順に従います。

パス B — HTTPS ユニバーサルリンク

エージェントへの指示： 以下の4つの手順はすべて必須です。いずれかを省略すると、ログイン後にコールバックのリダイレクトが失敗しても、何も通知されません。

手順 B1 — Auth0 CLI でコールバック URL を登録します： すべてのシナリオでアプリが動作するように、HTTPS とカスタムスキームの両方を登録します。

まず、既存の URL を上書きしないように、既存のコールバック URL とログアウト URL を取得します：

auth0 apps show CLIENT_ID --json --no-input > /tmp/auth0-app-info.json 2>&1

/tmp/auth0-app-info.json を読み取り、既存の callbacks 配列と allowed_logout_urls 配列を抽出します。

次に、新しい URL とともに既存の URL もカンマ区切りリストに含めます：

auth0 apps update CLIENT_ID \
  --callbacks "EXISTING_CALLBACKS,https://DOMAIN/ios/BUNDLE_ID/callback,BUNDLE_ID://DOMAIN/ios/BUNDLE_ID/callback" \
  --logout-urls "EXISTING_LOGOUT_URLS,https://DOMAIN/ios/BUNDLE_ID/callback,BUNDLE_ID://DOMAIN/ios/BUNDLE_ID/callback" \
  --no-input > /dev/null 2>&1

既存の URL がない場合は、EXISTING_ のプレフィックスを省略し、新しい URL のみを使用します。

手順 B2 — Auth0 CLI でデバイス設定を行います： project.pbxproj から DEVELOPMENT_TEAM を抽出します（10文字の値です。例：ABC12DE34F）。見つからない場合は、AskUserQuestion で確認します：「Apple Team ID を教えてください。（developer.apple.com → Account → Membership Details）」

auth0 api patch applications/CLIENT_ID \
  --data '{"mobile":{"ios":{"team_id":"TEAM_ID","app_bundle_identifier":"BUNDLE_ID"}}}' \
  --no-input > /dev/null 2>&1

これで Auth0 が apple-app-site-association ファイルを自動的にホストします。これは、デバイス上でユニバーサルリンクを機能させるために必要です。

手順 B3 — Xcode で Associated Domains エンタイトルメントを追加します： アプリの .entitlements ファイルに com.apple.developer.associated-domains を追加し、Auth0 ドメインの applinks: と webcredentials: の両方のエントリーを設定します。エンタイトルメントの XML、Xcode の機能設定手順、ビルド設定の確認方法については、セットアップガイド — Associated Domains を参照してください。

手順 B4 — SDK で .useHTTPS() を使用します：

Auth0.webAuth().useHTTPS()

手順 4 — 認証を実装します

エージェントへの指示： プロジェクト内を検索し、UI フレームワークを特定するために @main struct（SwiftUI）または AppDelegate／UIViewController（UIKit）を探します。判断できない場合は、AskUserQuestion で確認します：「アプリでは SwiftUI と UIKit のどちらを使用していますか？」その後、以下のうち該当するパスのみを実行します。

重要 — コード内で認証情報を渡さないでください： clientId や domain を Auth0.webAuth()、Auth0.authentication()、その他の SDK 呼び出しに引数として渡さないでください。SDK はこれらの値を Auth0.plist から自動的に読み取ります。引数なしの形式を必ず使用してください：

Auth0.webAuth()           // ✓ Auth0.plist から自動的に読み取ります
Auth0.authentication()    // ✓ Auth0.plist から自動的に読み取ります

Auth0.webAuth(clientId: "...", domain: "...")      // ✗ 絶対に使用しないでください
Auth0.authentication(clientId: "...", domain: "...") // ✗ 絶対に使用しないでください

SwiftUI

エージェントへの指示： AuthenticationService.swift を ObservableObject として作成し、アプリのエントリーポイントとルートビューに組み込みます。@main 構造体と ContentView（または同等のルートビュー）を検索し、以下の例のように更新します。

// AuthenticationService.swift
import Auth0
import Combine

class AuthenticationService: ObservableObject {
    @Published var isAuthenticated = false
    private let credentialsManager = CredentialsManager(authentication: Auth0.authentication())

    init() { isAuthenticated = credentialsManager.canRenew() }

    func login() async {
        do {
            let credentials = try await Auth0
                .webAuth()
                .useHTTPS()
                .scope("openid profile email offline_access")
                .start()
            _ = credentialsManager.store(credentials: credentials)
            await MainActor.run { isAuthenticated = true }
        } catch WebAuthError.userCancelled { }
        catch { print("Login failed: \(error)") }
    }

    func logout() async {
        do { try await Auth0.webAuth().useHTTPS().clearSession() }
        catch { print("Logout failed: \(error)") }
        _ = credentialsManager.clear()
        await MainActor.run { isAuthenticated = false }
    }
}

// @main App struct — inject AuthenticationService as environment object
@StateObject private var auth = AuthenticationService()
// In body: ContentView().environmentObject(auth)

// Root ContentView — branch on authentication state
@EnvironmentObject var auth: AuthenticationService
// In body: if auth.isAuthenticated { HomeView() } else { LoginView() }

SwiftUI アプリのライフサイクルへの組み込み方法については、統合パターンを参照してください。

UIKit

エージェントへの指示： AuthenticationService.swift を通常のクラスとして作成し、関連する UIViewController にログイン／ログアウトの呼び出しを追加してください。また、アプリが SFSafariViewController を使用しているかどうかも確認してください。使用している場合は、AppDelegate／SceneDelegate に WebAuthentication.resume(with:) を追加してください（下記の注を参照）。

// AuthenticationService.swift
import Auth0

class AuthenticationService {
    private let credentialsManager = CredentialsManager(authentication: Auth0.authentication())

    var isAuthenticated: Bool { credentialsManager.canRenew() }

    func login() async throws {
        let credentials = try await Auth0
            .webAuth()
            .useHTTPS()
            .scope("openid profile email offline_access")
            .start()
        _ = credentialsManager.store(credentials: credentials)
    }

    func logout() async throws {
        try await Auth0.webAuth().useHTTPS().clearSession()
        _ = credentialsManager.clear()
    }
}

// In your UIViewController
private let auth = AuthenticationService()

@IBAction func loginTapped(_ sender: UIButton) {
    Task {
        do {
            try await auth.login()
            await MainActor.run { navigateToHome() }
        } catch WebAuthError.userCancelled { }
        catch { print("Login failed: \(error)") }
    }
}

@IBAction func logoutTapped(_ sender: UIButton) {
    Task {
        do { try await auth.logout() }
        catch { print("Logout failed: \(error)") }
        await MainActor.run { navigateToLogin() }
    }
}

注 — SFSafariViewController のみ： デフォルトの ASWebAuthenticationSession の代わりに .provider(WebAuthentication.safariProvider()) を使用している場合は、AppDelegate.application(_:open:url:options:) と SceneDelegate.scene(_:openURLContexts:) に WebAuthentication.resume(with: url) を追加してください。正確なコードについては、統合パターンを参照してください。

Step 5 — ビルドを確認する

エージェントへの指示： ビルドを実行して、統合にエラーがなくコンパイルできることを確認してください。

xcodebuild build -scheme YOUR_SCHEME -destination "platform=iOS Simulator,name=iPhone 16"

ビルドに失敗した場合は、エラーメッセージを確認して修正してください。ユーザーに尋ねる前に、最大 5 回まで試してください。

詳細ドキュメント

• セットアップガイド — Auth0 CLI の設定、Auth0.plist、URL スキームの登録、Associated Domains、CocoaPods／SPM／Carthage によるインストール
• 統合パターン — Web Auth によるログイン／ログアウト、CredentialsManager、生体認証による保護、MFA、組織、エラー処理、SwiftUI／UIKit のパターン
• API リファレンスとテスト — API リファレンス全般、設定オプション、クレームのリファレンス、テストチェックリスト、トラブルシューティング

よくある間違い

間違い	修正方法
Auth0 アプリの種類が Native に設定されていない	Auth0 Dashboard でアプリケーションを作成する際に「Native」を選択します
Auth0 Dashboard にコールバック URL が登録されていない	https:// の Universal Link と {bundle}:// のカスタムスキームの両方を、Allowed Callback URLs と Logout URLs に追加します
Auth0.plist が Xcode ターゲットに追加されていない	Navigator でファイルを右クリックし、→「Add Files to Target」を選択して、アプリのターゲットにチェックを入れます
offline_access スコープが設定されていない	サイレント更新用のリフレッシュトークンを受け取るには、スコープ文字列に "offline_access" を追加します
トークンが UserDefaults に保存されている	必ず CredentialsManager を使用してください。アクセス制御付きでトークンを Keychain に保存します
store() の前に credentialsManager.credentials() を呼び出している	取得を試みる前に、ログイン結果から認証情報を保存します
.xcworkspace ではなく .xcodeproj を開いている（CocoaPods）	pod install の後は、必ず .xcworkspace ファイルを開きます
ログアウト時に clearSession() を呼び出していない	ブラウザーから Auth0 セッション Cookie を削除するため、必ず clearSession() を呼び出します
ビルドエラー「No such module 'Auth0'」	パッケージが正しいターゲットに追加されていることを確認します。CocoaPods の場合は .xcworkspace を開きます
プロンプトにドメイン／clientId があるのに、Swift ソースに直接記述している	Auth0.plist に記述し、引数なしで Auth0.webAuth() を呼び出します。SDK が plist を自動的に読み込みます

関連スキル

• auth0-quickstart - Auth0 の基本設定
• auth0-cli - ターミナルから Auth0 リソースを管理

---

参考資料

• Auth0.swift GitHub
• iOS/macOS クイックスタート
• Auth0.swift API ドキュメント
• Auth0 Dashboard
• EXAMPLES.md