auth0-net-android

auth0-net-android の統合

.NET Android アプリケーションに Auth0 認証を追加します。このスキルは、PKCE を使用した安全な OIDC ベースのログインおよびログアウトフローのために Chrome Custom Tabs を使用する Auth0.OidcClient.AndroidX NuGet パッケージを統合します。

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

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

以下の依存関係の各行では、ハードコードされたバージョンではなく、取得したバージョンを使用してください。

前提条件

• .NET 8.0 SDK 以降
• .NET Android ワークロードを含む Visual Studio 2022（17.8 以降）、または JetBrains Rider
• Android SDK API 21 以降（最小要件）。net9.0-android では API 34 以降を推奨
• Native アプリケーションを設定済みの Auth0 アカウント
• Node.js 20 以降（Auth0 CLI による自動セットアップ用）

使用しないケース

ユースケース	推奨スキル
.NET MAUI のクロスプラットフォームアプリ（iOS + Android + Windows）	auth0-maui
.NET の iOS 専用アプリ	auth0-net-ios
Android 専用 Kotlin アプリ	auth0-android
ASP.NET Core のサーバーサイド Web アプリ	auth0-aspnetcore-authentication
ASP.NET Core Web API（JWT 検証）	auth0-aspnetcore-api
React Native モバイルアプリ	auth0-react-native

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

エージェントへの指示： 開始する前に、ユーザーのプロジェクトを確認してください。

1. .csproj ファイルの TargetFramework から .NET のバージョンを特定します。
2. 既存の認証実装を確認します。既存のログイン／ログアウトハンドラーを検索し、見つかった場合はそれに組み込んでください（重複して作成するのではなく、ログインボタンなど既存の UI 要素を再利用します）。
3. .csproj または AndroidManifest.xml からプロジェクトの名前空間とパッケージ名を確認します。
4. 重複した設定を避けるため、既存の Auth0Client または Auth0ClientOptions の使用箇所を探します。

1. SDK をインストールする：dotnet add package Auth0.OidcClient.AndroidX
2. Auth0 を設定する：自動または手動での設定については、セットアップガイドを参照してください。
3. 認証を統合する：Auth0Client をインスタンス化し、Activity に IntentFilter を設定して、ログイン／ログアウトを UI アクションに接続します。
4. コールバックを処理する：OnNewIntent をオーバーライドし、ActivityMediator.Instance.Send(intent.DataString) を呼び出して認証フローを完了します。
5. ビルドして検証する：dotnet build

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

• Auth0Client コンストラクターの第 2 引数として this（Activity）を渡します。
• 必ず Scope = "openid profile email offline_access" を設定してください。リフレッシュトークンを受け取り、ユーザーに再度認証を求めずにトークンをサイレントに更新するには、offline_access スコープが必要です。
• コールバック URL の形式は YOUR_ANDROID_PACKAGE_NAME://YOUR_AUTH0_DOMAIN/android/YOUR_ANDROID_PACKAGE_NAME/callback です。すべて小文字にしてください。
• IntentFilter の DataScheme は小文字にしてください。そうしないと、Android がコールバックを受信できません。
• Activity に LaunchMode = LaunchMode.SingleTask を設定して、インスタンスの重複を防ぎます。SingleTop は使用しないでください。コールバックのリダイレクトを正しく処理できず、Activity のインスタンスが重複して作成されます。
• Activity は Auth0ClientActivity を継承するか、OnNewIntent を手動でオーバーライドして ActivityMediator.Instance.Send(intent.DataString) を呼び出す必要があります。
• トークンを安全に保存してください：ログイン成功後、SecureStorage（MAUI/Essentials）または EncryptedSharedPreferences（AndroidX Security。dotnet add package Xamarin.AndroidX.Security.SecurityCrypto が必要）を使用して、AccessToken と RefreshToken を永続化します。トークンを平文の SharedPreferences に保存したり、メモリ内変数だけに保存したりしないでください。

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

dotnet build

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

WebAuth — 認証の仕組み

SDK は Chrome Custom Tabs（システムブラウザー）を介して WebAuth パターンを使用します。LoginAsync() が呼び出されると、SDK は次の処理を行います。

1. PKCE パラメーターを含む /authorize URL を構築します
2. 認証 URL を指定して Chrome Custom Tabs を開きます
3. 認証後、Auth0 がネイティブコールバック URL にリダイレクトします
4. Android システムが URL スキームを照合し、OnNewIntent を介して Activity に URL を渡します
5. ActivityMediator がトークン交換を完了します

これは、ネイティブモバイルアプリケーションに推奨される、PKCE を使用した標準の OAuth 2.0 Authorization Code フローです。

コールバック URL の設定

.NET Android のネイティブコールバック URL では、パッケージ名をスキームとして使用します。形式は次のとおりです。

YOUR_ANDROID_PACKAGE_NAME://YOUR_AUTH0_DOMAIN/android/YOUR_ANDROID_PACKAGE_NAME/callback

YOUR_ANDROID_PACKAGE_NAME は、com.mycompany.myapplication など、アプリケーションのパッケージ名です。たとえば、com.mycompany.myapp://tenant.us.auth0.com/android/com.mycompany.myapp/callback です。

注： 一部の Auth0 ネイティブ SDK では、https://{domain}/android/{package}/callback をコールバック URL の形式として使用します。.NET Android SDK では、パッケージ名を URL スキームとして使用します。

コールバック URL が小文字であることを確認してください。

この URL は、次の設定が必要です。

1. Auth0 Dashboard の Allowed Callback URLs と Allowed Logout URLs に登録します
2. Activity の IntentFilter 属性（DataScheme、DataHost、DataPathPrefix）と一致させます

完了条件

• Auth0.OidcClient.AndroidX パッケージをインストール済み（最新の安定版）
• Auth0Client に Domain、ClientId、Scope = "openid profile email offline_access" を設定済み
• Activity に正しい DataScheme、DataHost、DataPathPrefix を指定して IntentFilter を設定済み
• Activity に LaunchMode = LaunchMode.SingleTask を設定済み
• ActivityMediator.Instance.Send(intent.DataString) を使用して OnNewIntent を処理済み
• コールバック URL を Auth0 Dashboard の Allowed Callback URLs と Allowed Logout URLs に追加済み
• トークンを安全に保存済み（SecureStorage または EncryptedSharedPreferences）
• ログイン／ログアウトのフローが動作中
• エラーなしでビルド成功

詳細なドキュメント

• セットアップガイド — Auth0 テナントの設定、SDK のインストール、IntentFilter の設定
• 統合パターン — ログイン／ログアウトのフロー、トークンへのアクセス、ユーザープロフィール、エラー処理
• API リファレンスとテスト — Auth0ClientOptions の全リファレンス、クレーム、テストチェックリスト、トラブルシューティング

よくある間違い

間違い	修正方法
Auth0 Dashboard でアプリの種類が Native に設定されていない	Dashboard の設定でアプリケーションの種類を「Native」に変更します
Auth0 Dashboard にコールバック URL がない	yourpackagename://{domain}/android/yourpackagename/callback を Allowed Callback URLs と Allowed Logout URLs の両方に追加します
DataScheme が小文字ではない	Android ではスキームを小文字にする必要があります。パッケージ名を小文字で使用します
LaunchMode.SingleTask が設定されていない	Activity に LaunchMode = LaunchMode.SingleTask を設定し、インスタンスの重複を防ぎます
OnNewIntent を処理していない	OnNewIntent をオーバーライドし、ActivityMediator.Instance.Send(intent.DataString) を呼び出します
Domain に https:// プレフィックスを使用している	Domain はホスト名のみを指定します（例：https://tenant.auth0.com ではなく tenant.auth0.com）
Auth0Client に Activity コンテキストを渡していない	2 番目のパラメーターとして this を渡します：new Auth0Client(options, this)
IntentFilter の DataHost／DataPathPrefix が一致しない	DataHost が Auth0 ドメインと一致し、DataPathPrefix が /android/yourpackagename/callback であることを確認します
offline_access スコープがない	サイレント更新用のリフレッシュトークンを受け取るため、必ず Scope に offline_access を含めます
SingleTask の代わりに LaunchMode.SingleTop を使用している	LaunchMode.SingleTask を使用する必要があります。SingleTop では Auth0 のコールバックリダイレクトを正しく処理できません
トークンを暗号化されていない SharedPreferences に保存している	AndroidX Security ライブラリの SecureStorage または EncryptedSharedPreferences を使用します

テストに関する注意事項

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

実機テスト：

• ログインフロー：Chrome Custom Tab が開く → 認証する → アプリに戻る
• コールバック：OnNewIntent が正しいインテントデータで呼び出される
• ログアウトフロー：ブラウザーが開く → セッションがクリアされる → アプリに戻る
• キャンセル：ユーザーが戻るボタンを押す → アプリが UserCancel を適切に処理する

関連スキル

• auth0-maui — .NET MAUI クロスプラットフォームアプリ（iOS + Android + Windows）
• auth0-net-ios — .NET iOS 専用アプリ
• auth0-android — Android ネイティブの Kotlin アプリ
• auth0-aspnetcore-authentication — ASP.NET Core サーバーサイドの Web アプリ
• auth0-aspnetcore-api — JWT 検証を備えた ASP.NET Core Web API

クイックリファレンス

using Auth0.OidcClient;

var client = new Auth0Client(new Auth0ClientOptions
{
    Domain = "YOUR_AUTH0_DOMAIN",
    ClientId = "YOUR_AUTH0_CLIENT_ID",
    Scope = "openid profile email offline_access"
}, this);

ログイン

var loginResult = await client.LoginAsync();

エラーの処理

var loginResult = await client.LoginAsync();

if (loginResult.IsError)
{
    Debug.WriteLine($"An error occurred during login: {loginResult.Error}");
}

アクセストークン

var loginResult = await client.LoginAsync();

if (!loginResult.IsError)
{
    Debug.WriteLine($"Authentication successful.");
}

ユーザー情報

if (!loginResult.IsError)
{
    Debug.WriteLine($"name: {loginResult.User.FindFirst(c => c.Type == "name")?.Value}");
    Debug.WriteLine($"email: {loginResult.User.FindFirst(c => c.Type == "email")?.Value}");
}

すべてのクレームを一覧表示

if (!loginResult.IsError)
{
    foreach (var claim in loginResult.User.Claims)
    {
        Debug.WriteLine($"{claim.Type} = {claim.Value}");
    }
}

ログアウト

BrowserResultType browserResult = await client.LogoutAsync();

IntentFilter を指定したアクティビティ（必須）

[Activity(Label = "AndroidSample", MainLauncher = true, Icon = "@drawable/icon",
    LaunchMode = LaunchMode.SingleTask)]
[IntentFilter(
    new[] { Intent.ActionView },
    Categories = new[] { Intent.CategoryDefault, Intent.CategoryBrowsable },
    DataScheme = "YOUR_ANDROID_PACKAGE_NAME",
    DataHost = "YOUR_AUTH0_DOMAIN",
    DataPathPrefix = "/android/YOUR_ANDROID_PACKAGE_NAME/callback")]
public class MainActivity : Activity
{
    // Code omitted
}

OnNewIntent でのコールバック処理（必須）

protected override async void OnNewIntent(Intent intent)
{
    base.OnNewIntent(intent);

    Auth0.OidcClient.ActivityMediator.Instance.Send(intent.DataString);
}

参考資料

• .NET Android & iOS クイックスタート
• GitHub リポジトリ
• NuGet パッケージ — Auth0.OidcClient.AndroidX
• SDK API ドキュメント