auth0-maui

auth0-maui の統合

iOS、Android、macOS、Windows を対象とする .NET MAUI アプリケーションに Auth0 認証を追加します。このスキルでは、MAUI の WebAuthenticator を介してシステムブラウザーを使用する Auth0.OidcClient.MAUI NuGet パッケージを統合し、PKCE を利用した安全な OIDC ベースのログインおよびログアウトフローを実現します。

エージェントへの指示： SDK のセットアップ手順を提示する前に、次のコマンドを実行して最新の MAUI リリースバージョンを取得してください。

gh api repos/auth0/auth0-oidc-client-net/releases --jq '[.[] | select(.tag_name | startswith("maui-")) | .tag_name | ltrimstr("maui-")] | .[0]'

以下の依存関係の行に記載されているハードコードされたバージョンの代わりに、取得したバージョンを使用してください。

前提条件

• .NET 8.0 SDK 以降
• MAUI ワークロードを備えた Visual Studio 2022（17.8 以降）、または MAUI をサポートする JetBrains Rider
• iOS の場合：Xcode 15 以降を搭載した macOS
• Android の場合：Android SDK API 33 以降（net8.0）または API 34 以降（net9.0）
• Windows の場合：Windows 10（10.0.19041.0）以降
• Native アプリケーションを設定済みの Auth0 アカウント
• Node.js 20 以降（Auth0 CLI による自動セットアップ用）

使用しないケース

ユースケース	推奨されるスキル
ASP.NET Core サーバーサイド Web アプリ	auth0-aspnetcore-authentication
ASP.NET Core Web API（JWT 検証）	auth0-aspnetcore-api
React Native モバイルアプリ	auth0-react-native
iOS 専用の Swift アプリ	auth0-swift
Android 専用の Kotlin アプリ	auth0-android
Expo React Native アプリ	auth0-expo

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

エージェントへの指示： 始める前に、ユーザーのプロジェクトを調べてください。

1. .csproj ファイルの TargetFrameworks から .NET のバージョンを特定します
2. 既存の認証実装を確認します。既存のログイン／ログアウトハンドラーを検索し、見つかった場合はそこに組み込みます
3. プロジェクトの名前空間とディレクトリの規則を確認します
4. 重複した設定を避けるため、既存の Auth0Client または Auth0ClientOptions の使用箇所を探します

1. SDK をインストール：dotnet add package Auth0.OidcClient.MAUI
2. Auth0 を設定：自動設定または手動設定については、セットアップガイドを参照してください。
3. 認証を統合：Auth0Client のインスタンスを追加し、ログイン／ログアウトを UI アクションに接続します。
   • 重要： 常に Scope = "openid profile email offline_access" を設定してください。サイレントなトークン更新に必要なリフレッシュトークンを受け取るには、offline_access スコープが必要です。
4. SecureStorage でトークンを永続化：ログイン後、await SecureStorage.Default.SetAsync("refresh_token", loginResult.RefreshToken) を使用してリフレッシュトークンを保存します。アプリ起動時に RefreshTokenAsync でセッションを復元します。ログアウト時には SecureStorage.Default.Remove("refresh_token") で消去します。
5. URL スキームを登録：プラットフォーム固有のコールバック処理を設定します。
   • Android：カスタムスキーム（例：myapp）の IntentFilter を持つ WebAuthenticatorActivity を作成します
   • Windows（2 つの手順が必要）：（1）<uap:Extension Category="windows.protocol"><uap:Protocol Name="myapp"/></uap:Extension> を Platforms/Windows/Package.appxmanifest に追加し、さらに（2）Platforms/Windows/App.xaml.cs で Activator.Default.CheckRedirectionActivation() を呼び出します
   • iOS/macOS：追加の設定は不要です
6. ビルドして確認：dotnet build

エージェントへの指示： Auth0Client の設定を記述する際は、次の点に従ってください。

• Scope 文字列には必ず offline_access を含めてください。これがないとリフレッシュトークンは返されず、アクセストークンの期限が切れるたびにユーザーは再認証する必要があります。
• ログイン後は SecureStorage.Default.SetAsync("refresh_token", ...) を使用し、アプリ起動時には SecureStorage.Default.GetAsync("refresh_token") を使用してセッションをサイレントに復元するトークン永続化を必ず実装してください。
• ログアウト時には SecureStorage.Default.Remove("refresh_token") で保存済みのトークンを消去してください。
• カスタム URL スキームプロトコルを登録するため、Platforms/Windows/Package.appxmanifest を必ず作成または更新してください。これがないと、Windows は認証後のコールバック URL を捕捉できません。<Application> ノード内の <Extensions> 要素に <uap:Extension Category="windows.protocol"><uap:Protocol Name="myapp"/></uap:Extension> を追加してください。
• Platforms/Windows/App.xaml.cs のコンストラクターで、InitializeComponent() の前の最初の行に CheckRedirectionActivation() を必ず追加してください。

設定とコードを記述した後、ビルドが成功することを確認してください。

dotnet build

ビルドに失敗した場合は、問題の修正を試みてください。5～6 回試しても失敗する場合は、ユーザーに助けを求めてください。

コールバック URL の設定

MAUI SDK はコールバックにカスタム URL スキームを使用します。デフォルトの形式は次のとおりです。

myapp://callback

https://{domain}/{platform}/{bundleId}/callback や {bundleId}.auth0://{domain}/ios/{bundleId}/callback の形式を使用する他の Auth0 ネイティブ SDK とは異なり、MAUI はよりシンプルなカスタムスキーム方式を使用します。スキームはカスタマイズできます（例：com.mycompany.myapp://callback）。選択したスキームは、次の条件を満たす必要があります。

1. Auth0 ダッシュボードの Allowed Callback URLs と Allowed Logout URLs に登録されている
2. プラットフォーム固有のコールバックハンドラー（Android の IntentFilter、Windows の Package.appxmanifest）に設定されている
3. Auth0ClientOptions.RedirectUri と Auth0ClientOptions.PostLogoutRedirectUri に設定されている

注： 本番アプリでは、URL スキームの乗っ取りリスクを減らすため、逆ドメイン形式のスキーム（例：com.yourcompany.yourapp://callback）を使用してください。

完了条件

• Auth0.OidcClient.MAUI パッケージがインストールされている
• Domain、ClientId、および offline_access を含む Scope を指定して Auth0Client が構成されている
• Android（WebAuthenticatorCallbackActivity）と Windows（Package.appxmanifest）で URL スキームが登録されている
• コールバック URL（myapp://callback）が Auth0 Dashboard の Allowed Callback URLs と Allowed Logout URLs に追加されている
• ログイン／ログアウトのフローが動作している
• ログイン後、SecureStorage.Default.SetAsync を使用してリフレッシュトークンが永続化されている
• アプリ起動時に SecureStorage.Default.GetAsync と RefreshTokenAsync を使用してセッションを復元する処理が実装されている
• エラーなくビルドが成功する
• 実機またはエミュレーター／シミュレーターでテスト済み

詳細ドキュメント

• セットアップガイド — Auth0 テナントの構成、SDK のインストール、プラットフォーム固有のコールバック設定
• 統合パターン — ログイン／ログアウトのフロー、トークンの更新、ユーザープロファイル、エラー処理、MVVM パターン
• API リファレンスとテスト — Auth0ClientOptions の完全なリファレンス、クレーム、テストチェックリスト、トラブルシューティング

よくある間違い

間違い	修正方法
Auth0 Dashboard でアプリの種類が Native に設定されていない	Dashboard の設定でアプリケーションの種類を「Native」に変更します
Auth0 Dashboard にコールバック URL がない	Allowed Callback URLs と Allowed Logout URLs の両方に myapp://callback（または使用するスキーム）を追加します
Android：WebAuthenticatorCallbackActivity がない	コールバックスキームに一致する [IntentFilter] を持つアクティビティクラスを作成します
Windows：CheckRedirectionActivation() を呼び出していない	Windows の App.xaml.cs で、InitializeComponent() の前に Activator.Default.CheckRedirectionActivation() を追加します
Domain に https:// のプレフィックスを使用している	Domain はホスト名のみを指定します（例：tenant.auth0.com。https://tenant.auth0.com ではありません）
トークン更新用の offline_access スコープを要求していない	リフレッシュトークンを取得するため、Auth0ClientOptions の Scope に offline_access を追加します
RedirectUri/PostLogoutRedirectUri が Dashboard の設定と一致していない	URI（スキーム＋パス）が Auth0 Dashboard で設定したものと完全に一致していることを確認します
Android／Windows で URL スキームを登録していない	プラットフォーム固有の設定でカスタム URL スキームを登録します（「プラットフォームのセットアップ」の手順を参照）
トークンを平文で保存している	リフレッシュトークンの永続化には MAUI Essentials の SecureStorage を使用します

テストに関する注意事項

エージェントへの指示： エミュレーター／シミュレーターに加えて、実機でもテストするようユーザーに伝えてください。WebAuthenticator の動作（システムブラウザーとの連携、URL スキームのインターセプト）は、実機とエミュレーターで異なる場合があります。リリース前に、実機でログイン → コールバック → トークンの一連のフローをテストしてください。

テストチェックリスト：

• ログインフロー：システムブラウザーが開く → 認証する → アプリに戻る
• ログアウトフロー：ブラウザーが開く → セッションがクリアされる → アプリに戻る
• トークンの更新：保存済みのリフレッシュトークンを使用して RefreshTokenAsync が動作する
• キャンセル：ユーザーがログインをキャンセルした場合、アプリが UserCancel を適切に処理する
• 実機：実際の iOS／Android デバイスでテストする（シミュレーターだけではなく）
• オフライン：アプリを再起動したときにトークンの更新が動作することを確認する
• マルチプラットフォーム：少なくとも 1 つのモバイルプラットフォーム（iOS または Android）と Windows でテストする

関連スキル

• auth0-aspnetcore-authentication — ASP.NET Core のサーバーサイド Web アプリ
• auth0-aspnetcore-api — JWT 検証を使用する ASP.NET Core Web API
• auth0-android — Android ネイティブの Kotlin アプリ
• auth0-swift — iOS／macOS の Swift アプリ
• auth0-react-native — React Native のモバイルアプリ
• auth0-net-android-ios — .NET Android／iOS（MAUI 以外）

クイックリファレンス

using Auth0.OidcClient;

// Initialize client
var client = new Auth0Client(new Auth0ClientOptions
{
    Domain = "YOUR_AUTH0_DOMAIN",
    ClientId = "YOUR_AUTH0_CLIENT_ID",
    RedirectUri = "myapp://callback",
    PostLogoutRedirectUri = "myapp://callback",
    Scope = "openid profile email offline_access"
});

// Login — opens system browser
var loginResult = await client.LoginAsync();
if (!loginResult.IsError)
{
    var user = loginResult.User;
    var accessToken = loginResult.AccessToken;
    var idToken = loginResult.IdentityToken;
    var refreshToken = loginResult.RefreshToken;

    // Access user claims
    var name = user.FindFirst("name")?.Value;
    var email = user.FindFirst("email")?.Value;

    // Persist refresh token securely for session restoration
    if (!string.IsNullOrEmpty(refreshToken))
        await SecureStorage.Default.SetAsync("refresh_token", refreshToken);
}

// Logout — clears Auth0 session and stored tokens
await client.LogoutAsync();
SecureStorage.Default.Remove("refresh_token");

// Restore session on app startup (no user interaction needed)
var savedToken = await SecureStorage.Default.GetAsync("refresh_token");
if (!string.IsNullOrEmpty(savedToken))
{
    var refreshResult = await client.RefreshTokenAsync(savedToken);
    if (!refreshResult.IsError)
    {
        var newAccessToken = refreshResult.AccessToken;
        // Update stored token if rotated
        if (!string.IsNullOrEmpty(refreshResult.RefreshToken))
            await SecureStorage.Default.SetAsync("refresh_token", refreshResult.RefreshToken);
    }
    else
    {
        // Refresh failed — clear and require re-login
        SecureStorage.Default.Remove("refresh_token");
    }
}

// Get user info from /userinfo endpoint
var userInfo = await client.GetUserInfoAsync(accessToken);

// Login with extra parameters (organization, audience, connection)
var orgLogin = await client.LoginAsync(new { organization = "org_abc123" });
var apiLogin = await client.LoginAsync(new { audience = "https://my-api.example.com" });

Android コールバックアクティビティ（必須）

[Activity(NoHistory = true, LaunchMode = LaunchMode.SingleTop, Exported = true)]
[IntentFilter(new[] { Intent.ActionView },
    Categories = new[] { Intent.CategoryDefault, Intent.CategoryBrowsable },
    DataScheme = CALLBACK_SCHEME)]
public class WebAuthenticatorActivity : Microsoft.Maui.Authentication.WebAuthenticatorCallbackActivity
{
    const string CALLBACK_SCHEME = "myapp";
}

Windows プラットフォームのセットアップ（必須 — 両方の手順）

手順 1：Platforms/Windows/Package.appxmanifest でプロトコルを登録します：

<Extensions>
  <uap:Extension Category="windows.protocol">
    <uap:Protocol Name="myapp"/>
  </uap:Extension>
</Extensions>

手順 2：Platforms/Windows/App.xaml.cs でリダイレクトを処理します：

// In Platforms/Windows/App.xaml.cs
public App()
{
    if (Auth0.OidcClient.Platforms.Windows.Activator.Default.CheckRedirectionActivation())
        return;
    this.InitializeComponent();
}

References

• Auth0 MAUI Quickstart
• GitHub Repository
• NuGet Package
• SDK API Documentation
• Auth0 Native App Documentation