> ## Documentation Index
> Fetch the complete documentation index at: https://translations.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Auth0.swift SDK を使用して iOS または macOS アプリケーションにログイン機能を追加する

export const HowToSchema = () => <script type="application/ld+json">
    {'{"@context":"https://schema.org","@type":"HowTo"}'}
  </script>;

export const AuthCodeGroup = ({children, dropdown}) => {
  const [processedChildren, setProcessedChildren] = useState(children);
  useEffect(() => {
    let unsubscribe = null;
    function init() {
      unsubscribe = window.autorun(() => {
        const processChildren = node => {
          if (typeof node === "string") {
            let processedNode = node;
            for (const [key, value] of window.rootStore.variableStore.values.entries()) {
              const escapedKey = key.replaceAll(/[.*+?^${}()|[\]\\]/g, (String.raw)`\$&`);
              processedNode = processedNode.replaceAll(new RegExp(escapedKey, "g"), value);
            }
            return processedNode;
          } else if (Array.isArray(node)) {
            return node.map(processChildren);
          } else if (node && node.props && node.props.children) {
            return {
              ...node,
              props: {
                ...node.props,
                children: processChildren(node.props.children)
              }
            };
          }
          return node;
        };
        setProcessedChildren(processChildren(children));
      });
    }
    if (window.rootStore) {
      init();
    } else {
      window.addEventListener("adu:storeReady", init);
    }
    return () => {
      window.removeEventListener("adu:storeReady", init);
      unsubscribe?.();
    };
  }, [children]);
  return <CodeGroup dropdown={dropdown}>{processedChildren}</CodeGroup>;
};

<HowToSchema />

<Accordion title="AI を使って Auth0 を統合する" icon="microchip-ai" iconType="solid" defaultOpen>
  Claude Code、Cursor、GitHub Copilot などの AI コーディングアシスタントを使えば、[agent skills](https://agentskills.io/home) を利用して数分で Auth0 の認証を自動的に追加できます。

  **インストール:**

  ```bash theme={null}
  npx skills add auth0/agent-skills --skill auth0
  ```

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

  ```text theme={null}
  Add Auth0 authentication to my iOS app
  ```

  AI アシスタントが Auth0 アプリケーションの作成、資格情報の取得、Auth0.swift SDK の依存関係の追加、Auth0.plist の設定、コールバックURLの設定、ログイン／ログアウトフローの実装を自動的に行います。[agent skills の完全なドキュメント →](/docs/ja-jp/quickstart/agent-skills)
</Accordion>

<div id="get-started">
  ## はじめに
</div>

<Steps>
  <Step title="新しいプロジェクトを作成する" stepNumber={1}>
    このクイックスタート用に、新しい iOS または macOS プロジェクトを作成します。

    **Xcode で:**

    1. **File** → **New** → **Project** (または **⌘+Shift+N**)
    2. 次のいずれかを選択します。
       * **iOS** タブ → **App** テンプレート
       * **macOS** タブ → **App** テンプレート
    3. プロジェクトを設定します。
       * **Product Name**: `Auth0-Sample`
       * **Interface**: SwiftUI
       * **Language**: Swift
       * **Use Core Data**: オフ
       * **Include Tests**: オン (推奨)
    4. 保存場所を選択し、**Create** をクリックします

    <Tip>
      これにより、SwiftUI と Swift Package Manager に対応した標準的なアプリが作成され、Auth0 との連携に最適です。
    </Tip>
  </Step>

  <Step title="Auth0 SDK を追加" stepNumber={2}>
    お好みの package manager を使って、プロジェクトに Auth0 SDK を追加します。

    <Tabs>
      <Tab title="Swift Package Manager">
        **Xcode の場合:**

        1. **File** → **Add Package Dependencies...** (または **⌘+Shift+K**)
        2. Auth0 SDK の URL を入力します。
           ```
           https://github.com/auth0/Auth0.swift
           ```
        3. **Add Package** → アプリのターゲットを選択 → **Add Package**
      </Tab>

      <Tab title="CocoaPods">
        1. プロジェクトのディレクトリに `Podfile` を作成します。
           ```ruby Podfile theme={null}
           platform :ios, '14.0' # macOS の場合は platform :osx, '11.0'
           use_frameworks!

           target 'YourApp' do
             pod 'Auth0', '~> 3.0'
           end
           ```
        2. dependencies をインストールします。
           ```bash theme={null}
           pod install
           ```
        3. 生成された `.xcworkspace` ファイルを開きます (`.xcodeproj` ではなく)
      </Tab>

      <Tab title="Carthage">
        1. プロジェクトのディレクトリに `Cartfile` を作成します。
           ```text Cartfile theme={null}
           github "auth0/Auth0.swift" ~> 3.0
           ```
        2. Carthage を実行します。
           ```bash theme={null}
           carthage update --platform iOS --use-xcframeworks
           ```
           macOS の場合は `--platform macOS` を使用します。
        3. 生成された `Auth0.xcframework` を `Carthage/Build` から Xcode プロジェクトにドラッグします。
        4. ターゲットの **General** 設定で、`Auth0.xcframework` を **Frameworks, Libraries, and Embedded Content** に追加します。
      </Tab>
    </Tabs>
  </Step>

  <Step title="Auth0 の設定" stepNumber={3}>
    新しいAuth0アプリケーションを作成し、コールバックURLを設定します。

    1. [Auth0 Dashboard](https://manage.auth0.com/dashboard/) を開きます
    2. **アプリケーション** > **Create Application** > 名前を入力し、**Native** を選択 > **Create**
    3. **設定** タブで、**Client ID** と **Domain** を控えておきます
    4. 次のURLを **Allowed Callback URLs** に追加します:

    <Tabs>
      <Tab title="iOS">
        ```
        https://{yourDomain}/ios/YOUR_BUNDLE_IDENTIFIER/callback,
        YOUR_BUNDLE_IDENTIFIER://{yourDomain}/ios/YOUR_BUNDLE_IDENTIFIER/callback
        ```
      </Tab>

      <Tab title="macOS">
        ```
        https://{yourDomain}/macos/YOUR_BUNDLE_IDENTIFIER/callback,
        YOUR_BUNDLE_IDENTIFIER://{yourDomain}/macos/YOUR_BUNDLE_IDENTIFIER/callback
        ```
      </Tab>
    </Tabs>

    5. 次のURLを **Allowed Logout URLs** に追加します:

    <Tabs>
      <Tab title="iOS">
        ```
        https://{yourDomain}/ios/YOUR_BUNDLE_IDENTIFIER/callback,
        YOUR_BUNDLE_IDENTIFIER://{yourDomain}/ios/YOUR_BUNDLE_IDENTIFIER/callback
        ```
      </Tab>

      <Tab title="macOS">
        ```
        https://{yourDomain}/macos/YOUR_BUNDLE_IDENTIFIER/callback,
        YOUR_BUNDLE_IDENTIFIER://{yourDomain}/macos/YOUR_BUNDLE_IDENTIFIER/callback
        ```
      </Tab>
    </Tabs>

    6. **Save Changes** をクリックします
  </Step>

  <Step title="アプリの資格情報を設定" stepNumber={4}>
    プロジェクトのディレクトリに`Auth0.plist`を作成します：

    ```xml Auth0.plist theme={null}
    <?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_AUTH0_CLIENT_ID</string>
        <key>Domain</key>
        <string>{yourDomain}</string>
    </dict>
    </plist>
    ```

    `Auth0.plist`をXcodeにドラッグし、"Add to target"にチェックが入っていることを確認します。
  </Step>

  <Step title="認証サービスを作成する" stepNumber={5}>
    ログイン、ログアウト、トークンの保存を処理する `AuthenticationService.swift` を作成します。

    <Info>
      **トークンの保存には `CredentialsManager` を使用します。** `CredentialsManager` クラスは資格情報を Keychain に安全に保存し、期限切れのアクセストークンを自動的に更新します。必ずこれを使用し、トークンをメモリ、`UserDefaults`、または `localStorage` に保存しないでください。
    </Info>

    1. プロジェクトを右クリック → **New File...** → **Swift File**
    2. 名前を `AuthenticationService` にします
    3. 内容を次のように置き換えます:

    ```swift AuthenticationService.swift expandable lines theme={null}
    import Foundation
    import Auth0
    import Combine

    @MainActor
    class AuthenticationService: ObservableObject {
        @Published var isAuthenticated = false
        @Published var user: UserProfile?
        @Published var isLoading = false
        @Published var errorMessage: String?
        
        private let credentialsManager = CredentialsManager(authentication: Auth0.authentication())
        
        init() {
            Task {
                await checkAuthenticationStatus()
            }
        }
        
        private func checkAuthenticationStatus() async {
            isLoading = true
            defer { isLoading = false }
            
            guard let credentials = try? await credentialsManager.credentials() else {
                isAuthenticated = false
                return
            }
            
            isAuthenticated = true
            // 保存されている ID トークンからユーザープロファイルを取得する
            user = try? credentialsManager.userProfile()
        }
        
        func login() async {
            isLoading = true
            errorMessage = nil
            defer { isLoading = false }
            
            do {
                // v3 以降、offline_access はデフォルトのスコープに含まれていますが、わかりやすくするためここでも明示しています
                _ = try await Auth0
                    .webAuth()
                    .scope("openid profile email offline_access")
                    .useCredentialsManager(credentialsManager)
                    .start()
                
                isAuthenticated = true
                // 保存されている ID トークンからユーザープロファイルを取得する
                user = try? credentialsManager.userProfile()
            } catch {
                errorMessage = "Login failed: \(error.localizedDescription)"
            }
        }
        
        func logout() async {
            isLoading = true
            defer { isLoading = false }
            
            do {
                try await Auth0
                  .webAuth()
                  .useCredentialsManager(credentialsManager)
                  .logout()
                isAuthenticated = false
                user = nil
            } catch {
                errorMessage = "Logout failed: \(error.localizedDescription)"
            }
        }
    }
    ```
  </Step>

  <Step title="認証フローを設定する（任意）" stepNumber={6}>
    ユーザー体験を向上させるには、次の方法でシステムアラートを最小限に抑えられます。

    1. Universal Links を使用する: リダイレクト中に表示される「“AppName”で開きますか？」という確認が出なくなります。注: ASWebAuthenticationSession の権限アラートは引き続き表示されます。
    2. 一時セッションを使用する: これにより、すべての権限アラートが表示されなくなります。注: これによりシングルサインオン (SSO) と共有Cookie は無効になります。

    <Tip>
      **この手順はスキップ**して、権限アラートが表示されるデフォルトの動作を使用できます。これは後で設定できます。
    </Tip>

    <Tabs>
      <Tab title="Universal Links">
        1. Auth0 Dashboard → **アプリケーション** → アプリ → **設定** → **Advanced Settings** → **Device Settings**
        2. **Apple Team ID** と **bundle identifier** を追加 → **保存**
        3. Xcode: Target → **Signing & Capabilities** → **+ Capability** → **Associated Domains**
        4. 追加: `webcredentials:{yourDomain}`

        <Warning>必要: 有料の Apple Developer アカウント、iOS 17.4+/macOS 14.4+</Warning>

        <Tip>
          本番環境のアプリに最適です。
        </Tip>
      </Tab>

      <Tab title="一時セッション">
        `AuthenticationService.swift` の login 呼び出しに `.useEphemeralSession()` を追加します:

        ```swift theme={null}
        // login() 関数内
        let credentials = try await Auth0
            .webAuth()
            .scope("openid profile email offline_access")
            .useCredentialsManager(credentialsManager)
            .useEphemeralSession()
            .start()
        ```

        <Info>
          一時セッションを使用している場合、Web Auth クライアントで `logout()` を呼び出す必要はありません。アプリから資格情報を消去するだけで十分です。削除する共有Cookie はありません。
        </Info>

        <Tip>
          手早く設定でき、アラートも表示されませんが、ユーザーは毎回ログインする必要があります (SSO なし)。
        </Tip>
      </Tab>
    </Tabs>
  </Step>

  <Step title="アプリを起動する" stepNumber={8}>
    Xcodeで **⌘+R** を押します。

    1. "Log In"をタップ → 権限の確認 (デフォルトを使用している場合) → "Continue"をタップ
    2. ブラウザーでログインを完了します
    3. プロファイルが表示されます！
  </Step>
</Steps>

<Check>
  **チェックポイント**

  これで、iOS または macOS アプリで Auth0 ログインが完全に機能するようになりました。
</Check>

***

<div id="troubleshooting-advanced">
  ## トラブルシューティングと高度な設定
</div>

<Accordion title="よくある問題と解決策">
  ### ビルドエラー: 'Auth0' module not found

  **解決策**:

  1. **Swift Package Manager**: **Package Dependencies** を確認し、`Auth0.swift` が一覧に含まれていることを確認
  2. **CocoaPods**: `.xcodeproj` ではなく `.xcworkspace` ファイルを開いていることを確認
  3. **Carthage**: `Auth0.xcframework` が **Frameworks, Libraries, and Embedded Content** に追加されていることを確認
  4. クリーンして再ビルド: **⌘+Shift+K** の後に **⌘+R**
  5. 必要に応じて Xcode を再起動

  ### アプリがクラッシュする: 'Auth0.plist not found'

  **修正方法**:

  1. `Auth0.plist` が Xcode のプロジェクトナビゲータ内にあることを確認
  2. ファイルを選択 → Inspector → アプリのターゲットにチェックが入っていることを確認
  3. `ClientId` キーと `Domain` キーに正しい値が設定されていることを確認

  ### ブラウザは開くがアプリに戻らない

  **修正方法**:

  1. Auth0 Dashboard のコールバック URL が、バンドル識別子およびプラットフォームと完全に一致していることを確認
  2. iOS の場合は URL に `/ios/`、macOS の場合は `/macos/` を含める
  3. Xcode のバンドル識別子が Auth0 の設定と一致していることを確認
  4. URL にタイプミスがないことを確認 (よくある例: コロンの不足、ドメイン形式の誤り)
  5. **カスタムドメインを使用している場合**: Auth0ドメインではなく、カスタムドメインを使用していることを確認

  ### 毎回権限アラートが表示される

  これは、カスタム URL スキームを使用する際の iOS/macOS の標準的なセキュリティ動作です。Universal Links または Ephemeral Sessions を使ってこのアラートを表示しないようにする方法については、**Step 6** を参照してください。
</Accordion>

<Accordion title="カスタムドメインの設定">
  [カスタムドメイン](/docs/ja-jp/customize/custom-domains) を使用している場合は、すべての箇所で Auth0ドメインの代わりにその値を使用してください。

  **例:** `tenant.auth0.com` ではなく `login.example.com` を使用

  これは、特定の機能を正しく動作させるために**必須**です:

  * `Auth0.plist` をカスタムドメインの値で更新する
  * コールバック URL/logout URL にカスタムドメインを使用する
  * Universal Links では次を使用: `webcredentials:login.example.com`
</Accordion>

<Accordion title="本番デプロイ">
  ### App Store 公開準備

  * 権限アラートをなくすために Universal Links を設定する
  * 複数のプラットフォームバージョンとデバイスサイズでテストする
  * ネットワーク障害に対する適切なエラーハンドリングを実装する
  * biometrics とともに Keychain を使用する場合は Privacy Usage の説明を追加する
  * 認証フローについて App Store Review Guidelines に従う

  ### セキュリティのベストプラクティス

  * 本番環境では機密性の高い認証データを絶対にログに出力しない
  * App Transport Security (ATS) への準拠を実装する
  * すべてのネットワークリクエストに HTTPS を使用する
  * Auth0 API 証明書をピン留めしては**いけません** - [Auth0 はこの方法を推奨していません](/docs/ja-jp/troubleshoot/product-lifecycle/past-migrations#avoid-pinning-or-fingerprinting-tls-certificates-for-auth0-endpoints)

  ### パフォーマンス最適化

  * すべての非同期処理で、UI 更新に `@MainActor` を適切に使用する
  * `@Published` プロパティで適切なメモリ管理を行う
  * オフラインアクセスのために、資格情報は Keychain に安全にキャッシュされる
  * ユーザープロファイルは ID トークン から取得される (追加のネットワークリクエストは不要)
</Accordion>

<Accordion title="高度な連携">
  ### biometrics による Keychain セキュリティの強化

  保存された資格情報にアクセスする際に、Face ID または Touch ID による認証を必須にします。

  ```swift theme={null}
  private let credentialsManager: CredentialsManager = {
      var manager = CredentialsManager(authentication: Auth0.authentication())
      manager.enableBiometrics(
          withTitle: "Face IDでロック解除", 
          cancelTitle: "キャンセル", 
          fallbackTitle: "パスコードを使用"
      )
      return manager
  }()
  ```

  有効にすると、SDK が保存済みの資格情報を取得する前に、ユーザーは biometrics を行う必要があります。

  ### トークンの自動更新

  `CredentialsManager` は、有効期限が切れたアクセストークンを自動的に更新します。

  ```swift theme={null}
  // 資格情報を取得 - 期限切れの場合は自動的に更新
  func getAccessToken() async throws -> String {
      let credentials = try await credentialsManager.credentials()
      return credentials.accessToken
  }
  ```

  アクセストークンが必要な API 呼び出しを行う場合は、このパターンを使用してください。

  ### App Extensions 間での資格情報の共有

  アクセストークンを必要とするウィジェット、App Extension、バックグラウンドタスク向け:

  ```swift theme={null}
  // app group を使って共有 credentials manager を作成
  let credentialsManager = CredentialsManager(
      authentication: Auth0.authentication(),
      storeKey: "credentials",
      storage: SimpleKeychain(accessGroup: "group.com.example.myapp")
  )
  ```

  **要件:**

  1. すべてのターゲットで Xcode の **App Groups** 機能を有効にする
  2. ターゲット間で同じ App Group 識別子を使用する
  3. 各ターゲットで共有の `CredentialsManager` を設定する

  ### 認証フローオプションの比較

  | 機能                      | Universal Links     | Ephemeral Session | デフォルト (アラート) |
  | ----------------------- | ------------------- | ----------------- | ------------ |
  | 権限アラート                  | 軽減 (リダイレクトのプロンプトなし) | なし                | すべてのアラートを表示  |
  | SSO サポート                | あり                  | なし                | あり           |
  | Apple Developer Account | 必須                  | 不要                | 不要           |
  | ユーザー体験                  | 最良                  | 良好                | 許容範囲         |
  | セットアップの複雑さ              | 中程度                 | 簡単                | 簡単           |
  | プライベートブラウジング対応          | あり                  | あり                | なし           |

  **推奨事項:**

  * **SSO を使用する本番アプリ**: Universal Links (より優れた UX、SSO 対応、Apple Developer Account が必要)
  * **SSO を使用しない本番アプリ**: Ephemeral Session (アラートなし、セットアップが簡単)
  * **テスト/開発**: Ephemeral Session (すばやく設定でき、最もすっきりした UX)
  * **クイックスタート/プロトタイピング**: アラート付きのデフォルト (設定不要、後から移行可能)
</Accordion>