auth0-android-major-migration

Auth0.Android v4 への移行

既存の Auth0.Android（com.auth0.android:auth0）v3 統合を v4 に移行します。コードの変更は、対象の API がプロジェクトで実際に呼び出されていることを検索で確認した場合にのみ行います。プロジェクトで SecureCredentialsManager を使用していない場合、そのコードには一切手を加えません。変更は、プロジェクトの既存のアーキテクチャ（Kotlin または Java、コールバックまたはコルーチン）と Android の規約に従います。

対象バージョンは引数で指定

このスキルでは、対象バージョンを任意の引数で指定できます。

• /auth0-android-major-migration 4.0.0 — タグ 4.0.0 へ移行します（使用前に検証されます）。
• /auth0-android-major-migration（引数なし）— 次のメジャーバージョン（v4.x）内の最新リリースを自動的に解決します。プレリリースも含みます。

$ARGUMENTS が指定されている場合、これはリクエストされた対象タグです。ステップ 2 でこれを検証し、移行の残りの手順で使用する最終的な <TARGET_TAG> を解決します。

使用しない場合

• Auth0 の新規統合（Auth0.Android SDK がまだない場合）：auth0-android を使用してください
• マイナー／パッチアップデート（例：3.18 → 3.19）：Gradle で com.auth0.android:auth0 のバージョンを上げてください。移行は不要です
• iOS／macOS アプリ：auth0-swift-major-migration を使用してください
• React Native／Expo：auth0-react-native または auth0-expo を使用してください
• Flutter：ネイティブの Flutter Auth0 SDK を使用してください

前提条件

• 既存の Auth0.Android v3 統合（com.auth0.android:auth0:3.x）
• Android SDK／Gradle ツールチェーンがインストールされており、現在のバージョンでプロジェクトが正常にビルドできること
• プロジェクトが git のバージョン管理下にあり、作業ツリーがクリーンであること

---

移行ワークフロー

エージェントへの指示： すべての手順を順番に実行してください。目標は、変更を正しく必要最小限に抑えながら、ビルドを成功させることです。各コード変更ステップは、ステップ 5 のファイル読み取り監査を経てから実行してください。プロジェクトのソースファイルに API が見つからなかった場合、その箇所に関するステップ全体をスキップしてください。プロジェクトがすでに呼び出していないコードを追加してはいけません。v4 ではプラットフォーム要件も引き上げられます（ステップ 3）。要件を満たすまで移行が妨げられる場合があるため、Auth0 API の呼び出し箇所に手を加える前に対応してください。

---

ステップ 1 — 事前確認と安全のためのバックアップ

# 1a. Verify clean working tree — stop if there are uncommitted changes
git status --porcelain

出力が空でない場合は、ユーザーに確認してください。

「コミットされていない変更があります。続行する前に git stash で退避しますか？それとも、先にコミットしますか？」

# 1b. Create a safety branch the user can reset to at any time
git checkout -b auth0-v4-migration-backup
git checkout -

# 1c. Confirm the project builds on the current version before touching anything
./gradlew assembleDebug 2>&1 | tail -15

ビルドに失敗した場合は、作業を中止してください。まず既存の問題を解決するようユーザーに依頼してください。ビルドできないプロジェクトを移行してはいけません。

---

Step 2 — 現在のバージョンを検出し、対象バージョンを決定する

現在の Auth0.Android のバージョンを検出します（該当する場所をそれぞれ確認してください）。

# Inline dependency in a module build file (Groovy or Kotlin DSL)
grep -rEn "com\.auth0\.android:auth0:[0-9]" --include=build.gradle --include=build.gradle.kts .

# Gradle version catalog
grep -rEn "auth0" --include=libs.versions.toml .

# Resolved lockfile (most reliable if present)
grep -rEn "com\.auth0\.android:auth0:[0-9]" --include=gradle.lockfile .

対象バージョンを決定します。 方法は 2 つあります。

方法 A — ユーザーが対象バージョンの引数（$ARGUMENTS）を渡した場合：

使用する前に、公開済みリリースと照合して検証します。次の3 つすべての条件を満たす必要があります。

# List all published Auth0.Android release tags
gh api repos/auth0/Auth0.Android/releases --paginate \
  --jq '.[] | select(.draft==false) | .tag_name'

1. 存在する — 指定されたタグが上記の公開済みリリース一覧に含まれている。
2. 次のメジャーバージョンである — タグが v4 のメジャー系列に含まれている（tag_name が 4 で始まる）。3.x 以下のタグは次のメジャーバージョンではないため、拒否します。
3. ダウングレードではない — タグがプロジェクトで検出されたバージョンより新しい。

いずれかの条件を満たさない場合は、停止してユーザーに確認してください。 暗黙に別のバージョンへ切り替えてはいけません。たとえば次のように伝えます。

• 「4.9.9 は公開済みの Auth0.Android リリースではありません。公開済みの v4 リリースは 4.0.0-beta.1、… です。有効な v4 タグを指定するか、引数を省略して最新の v4 リリースを自動的に決定してください。」
• 「3.19.0 は v3 のリリースであり、次のメジャーバージョンではありません。このスキルでは v4 に移行します。v4 のタグ（例：4.0.0）を指定するか、引数を省略してください。」
• 「4.0.0-beta.0 は、プロジェクトにすでにある 4.0.0-beta.1 より古いため、ダウングレードになります。より新しい v4 のタグを指定するか、引数を省略してください。」

方法 B — 引数がない場合：最新の v4 リリースを自動的に決定します（プレリリースを含む）。

# Newest v4.x release tag (stable or pre-release), most recent first
gh api repos/auth0/Auth0.Android/releases --paginate \
  --jq '[.[] | select(.draft==false) | select(.tag_name|startswith("4"))] | .[0].tag_name'

結果を <TARGET_TAG> として記録し、以降のすべての手順で使用します。

<TARGET_TAG> がプレリリースの場合（-beta、-rc などを含む場合）は、続行する前にユーザーに伝えてください。 「v4 はまだ一般提供されていません。最新の v4 リリースは <TARGET_TAG>（プレリリース）です。このバージョンに移行します。別のタグに固定するには、引数として指定してください。」

v4 のリリースがまだない場合（リゾルバーが空を返した場合）は、停止して、移行先となる公開済みの v4 リリースがないことをユーザーに伝えてください。

---

Step 3 — 前提条件の確認（要件の変更）

v4 では、ビルドツールチェーンとプラットフォームの最低要件が引き上げられています。API を移行する前に、各要件を確認してください。要件を満たしていない場合は、ユーザーに確認し、ビルドファイルを変更するか、承認が得られるまで作業を止めてください。これらの要件を満たさないプロジェクトは、API を変更しても v4 に対してビルドできません。

<TARGET_TAG> で必要となる正確なバージョンが以下の値と異なる場合は、Step 4 で SDK 自身の build.gradle / gradle-wrapper.properties を取得して確認してください（以下の値は v4 の基準を示しています）。

要件	v3	v4	確認・変更箇所
minSdk	21	26（Android 8.0）	android { defaultConfig { minSdk } }
Java	8 以降	17	compileOptions { sourceCompatibility/targetCompatibility }、kotlinOptions { jvmTarget }
Gradle	—	8.11.1 以降	gradle/wrapper/gradle-wrapper.properties（distributionUrl）
AGP	—	8.10.1 以降	ルートの build.gradle にある com.android.tools.build:gradle のクラスパス／plugins ブロック
Kotlin	—	2.0.21	ext.kotlin_version / バージョンカタログ（プロジェクトが Kotlin を使用する場合のみ）

# Inspect current values
grep -rEn "minSdk(Version)?\s*[ =]" --include=build.gradle --include=build.gradle.kts .
grep -rEn "sourceCompatibility|targetCompatibility|jvmTarget" --include=build.gradle --include=build.gradle.kts .
grep -En "distributionUrl" gradle/wrapper/gradle-wrapper.properties
grep -rEn "com\.android\.tools\.build:gradle|kotlin_version|kotlin(\"|-)" --include=build.gradle --include=build.gradle.kts --include=libs.versions.toml .

minSdk が 26 未満の場合は、必ず作業を止めてください。 プロジェクトの対象 API レベルが 25 以下の場合、これによりサポート対象の Android の最低バージョンが引き上げられ（Android 7.1 以前のデバイスはサポート対象外になります）、minSdk を 26 に引き上げるか、v3 を使い続けるか、ユーザーに確認してください。

必要なバージョンの引き上げを適用します（以下は例です。プロジェクトの DSL に合わせてください）。

android {
    defaultConfig { minSdk 26 }
    compileOptions {
        sourceCompatibility JavaVersion.VERSION_17
        targetCompatibility JavaVersion.VERSION_17
    }
    kotlinOptions { jvmTarget = '17' }
}

Kotlin DSL、バージョンカタログ、Gradle／AGP ラッパーの特殊なケースについては、references/process.md を参照してください。

---

ステップ 4 — v4 SDK のソースを取得して読む

<TARGET_TAG> の Kotlin ソースを取得します。ここに記載されているシグネチャは、ステップ 7 で行うすべての変更の正式な参照元です。記憶やガイドだけを頼りに移行せず、取得したソースで各シグネチャを確認してください。

TAG=<TARGET_TAG>   # the version resolved in Step 2, e.g. 4.0.0-beta.1
BASE="https://raw.githubusercontent.com/auth0/Auth0.Android/${TAG}/auth0/src/main/java/com/auth0/android"

# List all public Kotlin files in the SDK (confirm paths for this tag)
gh api "repos/auth0/Auth0.Android/git/trees/${TAG}?recursive=1" \
  --jq '.tree[].path | select(startswith("auth0/src/main/") and endswith(".kt"))'

# Fetch the files that back the breaking changes
for FILE in \
  provider/WebAuthProvider.kt \
  authentication/AuthenticationAPIClient.kt \
  authentication/mfa/MfaApiClient.kt \
  authentication/storage/SecureCredentialsManager.kt \
  authentication/storage/CredentialsManager.kt \
  authentication/storage/BaseCredentialsManager.kt \
  authentication/storage/Storage.kt \
  dpop/DPoPException.kt \
  result/SSOCredentials.kt \
  request/DefaultClient.kt ; do
    CONTENT=$(curl -sf "${BASE}/${FILE}")
    [ -n "$CONTENT" ] && echo "=== ${FILE} ===" && echo "$CONTENT"
done

リリースタグにソースがまだない場合（たとえば v4 の開発期間中で、完全なツリーを含む最初のタグがまだない場合）は、シグネチャの確認に v4_development ブランチを使用してください。上記の URL で ${TAG} を v4_development に置き換えます。選択したタグにソースがある場合は、必ずそのタグを優先してください。

取得したソースを読み、各ファイルについて次の点を確認します。

• 変更された公開メソッドのシグネチャ（パラメーター、戻り値の型、@Throws）
• 削除されたコンストラクター
• 削除または名前変更された型／クラス
• 変更されたデフォルトパラメーター値（例：minTtl）

これが信頼できる唯一の情報源です。ステップ 7 の変更はすべて、これらのファイルにある実際のシグネチャと一致させる必要があります。

---

ステップ 5 — プロジェクトで使用している Auth0 API を監査する

Auth0 SDK をインポートしているすべてのソースファイルを探します。これらが移行対象です。

grep -rlE "import com\.auth0\.android" --include="*.kt" --include="*.java" .

リストにあるすべてのファイルを読みます。 個別の API パターンを grep して確認を終わらせず、ソース全体を読んで、Auth0、WebAuthProvider、AuthenticationAPIClient、SecureCredentialsManager／CredentialsManager、および Auth0 の型がどのように使われているかを確認してください。複数行にわたるビルダーチェーンや、独自の Storage 実装も含めて確認します。

各ファイルで次の点を確認します。

確認項目	セクション
PasskeyAuthProvider の使用	§7.1 — クラスが削除されました
UsersAPIClient、ManagementException、ManagementCallback	§7.2 — Management API が削除されました
AuthenticationAPIClient での loginWithOTP(、loginWithOOB(、loginWithRecoveryCode(、multifactorChallenge(	§7.3 — 非推奨の MFA メソッドが削除されました
.login( の前にあるオブジェクトでの WebAuthProvider.useDPoP( の呼び出し	§7.4 — useDPoP がログインビルダーに移動しました
DPoPException.UNSUPPORTED_ERROR	§7.5 — 定数が削除されました
SSOCredentials 値の .expiresIn へのアクセス	§7.6 — expiresAt に変更されました（型は Date）
最初の引数に Auth0 インスタンスを渡す SecureCredentialsManager(	§7.7 — Auth0 ベースのコンストラクターが削除されました
明示的な minTtl を指定しない getCredentials(／awaitCredentials(、または hasValidCredentials()	§9.1 — デフォルトの minTtl が 0 から 60 秒に変更されました（動作への影響あり）
clearCredentials(	§9.3 — ストレージ全体がクリアされるようになりました
Storage インターフェースを実装するクラス	§9.4 — 新しい removeAll()（デフォルト実装が提供されています）

チェックリストを作成します。**「このプロジェクトで使用しているもの：[リスト]」と「このプロジェクトで使用していないもの：[リスト]」**を記載します。「使用しているもの」のリストにある §7.x／§9.x セクションのみ作業し、それ以外はすべてスキップします。

---

ステップ 6 — SDK の依存関係を更新する

該当する宣言形式を適用します。ステップ 2 の <TARGET_TAG> を使用してください。

インライン — Groovy DSL（build.gradle）：

implementation 'com.auth0.android:auth0:<TARGET_TAG>'

インライン — Kotlin DSL（build.gradle.kts）：

implementation("com.auth0.android:auth0:<TARGET_TAG>")

バージョンカタログ（gradle/libs.versions.toml）：

[versions]
auth0 = "<TARGET_TAG>"

プレリリースタグ（例：4.0.0-beta.1）は、正確なバージョンを指定する必要があります。Gradle が別のアーティファクトを解決する可能性があるため、4.+ や [4.0,5.0) のような動的な範囲は使用しないでください。安定版 v4 リリースでも、再現性を確保するために正確なバージョンの指定を推奨します。

まだビルドしないでください。既知のコード変更をすべて先に適用し（ステップ 7）、その後にビルドして（ステップ 8）、残りを確認します。

---

ステップ 7 — 破壊的変更を適用する

エージェントへの指示： ステップ 5 の監査で該当した §7.x セクションのみ作業してください。プロジェクトで使用していない API に関するセクションはすべてスキップし、それらのファイルには手を加えないでください。ステップ 4 で取得したソースと照合し、各変更を記載どおりに適用します。移行対象ではないコードの変数名変更、再フォーマット、モダナイズは行わないでください。プロジェクト既存のスタイルに合わせます。コールバックはコールバックのまま、コルーチンの await はコルーチンの await のまま、Kotlin は Kotlin のまま、Java は Java のままにします。

7.1 — PasskeyAuthProvider の削除

該当する場合： ステップ 5 で、プロジェクトのソースファイルに PasskeyAuthProvider が見つかった場合。

com.auth0.android.provider.PasskeyAuthProvider クラスは削除されました。パスキー操作は AuthenticationAPIClient の passkeyChallenge()、signupWithPasskey()、signinWithPasskey() に移動しました。ステップ 4 で取得した AuthenticationAPIClient.kt で正確なシグネチャを確認してから、各呼び出し箇所を対応するクライアントメソッドに移行してください。ソースからパスキーフローを確実に移行できない場合は、推測せずに // TODO: を追加し、ステップ 10 の概要に記載してください。

---

7.2 — Management API（UsersAPIClient）の削除

該当する場合： ステップ 5 で、プロジェクトのソースファイルに UsersAPIClient、ManagementException、または ManagementCallback が見つかった場合。

Management API クライアント全体が SDK の v4 で削除されました。モバイルアプリから Management API を直接呼び出すことは、これまでも推奨されていませんでした。デバイス上に特権トークンが必要になるためです。呼び出し箇所を黙って削除しないでください。 意図を残す // TODO: を追加し、ステップ 10 の概要でバックエンド作業が必要であることを明記してください。

// v3 — direct Management API call from the app (e.g. updating user_metadata)
val users = UsersAPIClient(account, accessToken)
users.updateMetadata(userId, metadata)
    .start(object : Callback<UserProfile, ManagementException> { /* ... */ })

// v4 — Management client removed; preserve intent, move to a backend
// TODO: Auth0.Android v4 removed the Management API client (UsersAPIClient).
// Expose an endpoint on your own backend (e.g. PATCH /me/metadata) that performs
// this operation. Call it from the app with the user's access token as a Bearer
// token. On the backend, obtain a machine-to-machine token via Client Credentials
// and call the Management API with the minimum required scopes.
// NEVER embed a Management API token in the app.
// See: https://auth0.com/docs/manage-users/user-accounts/manage-user-metadata

バックエンド作業が必要です。ステップ 10 の概要に記録してください。

---

7.3 — AuthenticationAPIClient から削除された非推奨の MFA メソッド → MfaApiClient

該当する場合： ステップ 5 で、プロジェクトのソースファイルにある AuthenticationAPIClient で loginWithOTP(、loginWithOOB(、loginWithRecoveryCode(、または multifactorChallenge( が呼び出されているのが見つかった場合。

これら 4 つのメソッドは v3 で非推奨となり、v4 で削除されました。AuthenticationAPIClient.mfaClient(mfaToken) から MfaApiClient を取得し、その API を使用してください。変更を適用する前に、ステップ 4 で取得した MfaApiClient.kt で正確な MfaApiClient のメソッドシグネチャを確認してください。

// v3 — removed methods on AuthenticationAPIClient
authentication
    .loginWithOTP(mfaToken, otp)
    .start(object : Callback<Credentials, AuthenticationException> { /* ... */ })

// v4 — obtain an MfaApiClient and use its verify API (confirm signature in MfaApiClient.kt)
val mfaClient = authentication.mfaClient(mfaToken)
// e.g. mfaClient.verifyWithOTP(otp) — use the exact method/parameters from the fetched source

mfaToken は引き続き同じ場所、つまりチャレンジが必要であることを示す AuthenticationException から取得します。移行した MFA フローをすべてステップ 10 の概要に記載し、テナントに対して各 MFA フローをエンドツーエンドで再テストするようユーザーに依頼してください。メソッドの対応表全体については、references/process.md を参照してください。

---

7.4 — WebAuthProvider.useDPoP(context) をログインビルダーに移動

該当する場合： ステップ 5 で、.login( より前に WebAuthProvider オブジェクトで WebAuthProvider.useDPoP( が呼び出されているのが見つかった場合。実際の呼び出しチェーンを確認してください。複数行にわたる場合があります。

v4 では、useDPoP(context) は WebAuthProvider オブジェクトでグローバルに設定するのではなく、リクエストごとにログインビルダーで設定します。.useDPoP(context) の呼び出しを移動し、.login(account) の後にチェーンしてください。

// v3 — global configuration (no longer compiles)
WebAuthProvider
    .useDPoP(context)
    .login(account)
    .start(context, callback)

// v4 — builder-based, per-request
WebAuthProvider
    .login(account)
    .useDPoP(context)
    .start(context, callback)

---

7.5 — DPoPException.UNSUPPORTED_ERROR の削除

該当する場合： ステップ 5 で、プロジェクトのソースファイルに DPoPException.UNSUPPORTED_ERROR が見つかった場合。

最小 SDK が API 26 に引き上げられたため、v4 が対象とするすべての API レベルで DPoP がサポートされ、この定数は削除されました。この定数への参照を削除してください。たとえば、UNSUPPORTED_ERROR を確認する when／if 分岐や比較などです。置き換えは不要です。未サポートのバージョンに該当するケースは発生しなくなります。

// v3 — guarding against the unsupported case
if (error == DPoPException.UNSUPPORTED_ERROR) {   // ❌ no longer exists in v4
    showDeviceUnsupported()
} else {
    handle(error)
}

// v4 — the guard is no longer applicable; handle the remaining cases
handle(error)

---

7.6 — SSOCredentials.expiresIn → expiresAt（Int → Date）

該当する場合： ステップ 5 で、プロジェクトのソースファイルにある SSOCredentials の値で .expiresIn が参照されているのが見つかった場合。

SSOCredentials.expiresIn（秒単位の生の値、Int）は expiresAt に名前が変更され、現在は絶対時刻を示す Date です（Credentials.expiresAt と同様にデシリアライズ時に計算されます）。プロパティ名を変更し、秒単位の期間を前提としていた演算も更新してください。

JSON のワイヤーフォーマットは変更されていません。SDK では引き続きこのフィールドに @field:SerializedName("expires_in") が指定されています。変更されたのは Kotlin のプロパティ名と型だけです（expiresIn: Int → expiresAt: Date）。生の JSON を検索しても、名前が変更された expires_at キーは見つからないので注意してください。

// v3 — seconds until expiry (Int)
val secondsUntilExpiry: Int = ssoCredentials.expiresIn

// v4 — absolute expiration Date
val expirationDate: Date = ssoCredentials.expiresAt
// If you previously did `now + expiresIn` to get an absolute time, use expiresAt directly.

---

7.7 — SecureCredentialsManager の Auth0 ベースのコンストラクターを削除

該当する場合： Step 5 で、プロジェクトのソースファイル内に、最初の引数として Auth0 インスタンスを指定して構築された SecureCredentialsManager( が見つかった場合。

Auth0 インスタンスを受け取る2つのコンストラクターが削除されました。残る2つのコンストラクターは、最初の引数として AuthenticationAPIClient を受け取ります。Auth0 アカウントからクライアントを作成し、同じクライアントを SecureCredentialsManager に渡してください。

// v3 — Auth0-based constructors (removed in v4)
val manager = SecureCredentialsManager(auth0, context, storage)
val manager = SecureCredentialsManager(auth0, context, storage, fragmentActivity, localAuthenticationOptions)

// v4 — build an AuthenticationAPIClient first, pass it in
val apiClient = AuthenticationAPIClient(auth0)
val manager = SecureCredentialsManager(apiClient, context, storage)

// v4 — biometric variant
val apiClient = AuthenticationAPIClient(auth0)
val manager = SecureCredentialsManager(
    apiClient,
    context,
    storage,
    fragmentActivity,
    localAuthenticationOptions
)

// Java — same change; there is no Java-specific overload
AuthenticationAPIClient apiClient = new AuthenticationAPIClient(auth0);
SecureCredentialsManager manager = new SecureCredentialsManager(apiClient, context, storage);

プロジェクトで DPoP を有効にしている場合は、クライアントを渡す前に設定してください：AuthenticationAPIClient(auth0).useDPoP(context)。Step 4 で取得した SecureCredentialsManager.kt でコンストラクターのシグネチャを確認してください。

---

Step 8 — ビルドが成功するまで修正する

./gradlew assembleDebug 2>&1 | tail -40

エラーごとに、内容を読み、ソースの該当行を特定し、Step 7 の該当セクションと照合して、Step 4 で取得したシグネチャに基づいて修正を確認し、プロジェクトの既存のスタイルに合わせて適用してから、再ビルドしてください。

よくあるエラーと原因の対応：

ビルドエラー	考えられる原因
unresolved reference: PasskeyAuthProvider	§7.1 — クラスが削除されています。AuthenticationAPIClient のパスキー API を使用してください
unresolved reference: UsersAPIClient / ManagementException / ManagementCallback	§7.2 — Management API が削除されています。// TODO: とバックエンド側の対応事項を追加してください
unresolved reference: loginWithOTP / loginWithOOB / loginWithRecoveryCode / multifactorChallenge	§7.3 — mfaClient(mfaToken) / MfaApiClient を使用してください
unresolved reference: useDPoP on WebAuthProvider	§7.4 — .useDPoP(context) を .login(account) の後に移動してください
unresolved reference: UNSUPPORTED_ERROR	§7.5 — この参照を削除してください
unresolved reference: expiresIn on SSOCredentials, or Int/Date type mismatch	§7.6 — expiresAt（現在は Date）に名前を変更してください
none of the following functions can be called / too many arguments on SecureCredentialsManager(	§7.7 — 先に AuthenticationAPIClient(auth0) を作成し、それを渡してください
class … must override removeAll (custom Storage)	§9.4 — インターフェースにはデフォルト実装があります。必要な場合のみオーバーライドしてください

上限： ビルド修正サイクルは最大 10回 です。10回試してもビルドに失敗する場合は、そこで中止し、残っているエラーを前後の情報とともに示してください。推測で修正しないでください。

---

Step 9 — 動作とデフォルト値の変更（確認のみ。通常、コード変更は不要）

これらの変更は編集なしでコンパイルできますが、実行時の動作が変わります。それぞれ Step 10 の概要に記載してください。古い動作に依存している場合にのみ、コードを変更してください。

9.1 — Credentials Manager のデフォルト minTtl が 0 から 60s に変更

該当する場合： プロジェクトが、明示的な minTtl を指定せずに getCredentials(...) / awaitCredentials(...) を呼び出す場合、または hasValidCredentials() を呼び出す場合。

v4 では、すでに期限切れの場合に限らず、60秒以内に期限切れとなる認証情報も更新されます。これは、リクエストの途中で期限切れとなるトークンの払い出しを避けるための推奨動作です。v3 の動作に戻すには、明示的に minTtl = 0 を渡してください：

// v4 — restore v3 behavior explicitly if required
credentialsManager.getCredentials(scope = null, minTtl = 0, callback = callback)

9.2 — CredentialsManager がグローバルエグゼキューターを使用

実行時のみの変更です。同じ Auth0 オブジェクトを使用する複数のマネージャー間で更新がシリアル化され、リフレッシュトークンの重複交換が解消されます。コード変更は不要です。

9.3 — clearCredentials() がすべてのストレージをクリア

該当する場合： プロジェクトが clearCredentials() を呼び出す場合。

v4 では Storage.removeAll() が呼び出され、特定のオーディエンス用に保存された API 認証情報も含め、ストレージ内のすべての値がクリアされます。同じ Storage 内の他のデータを保持する必要がある場合は、API 認証情報用に別の Storage インスタンスを使用することを推奨するか、新しい clearAll()（Step 10 の任意の改善）を検討してください。

9.4 — Storage インターフェースに removeAll() を追加

該当条件： プロジェクトに Storage インターフェースを実装するクラスがある場合。

removeAll() にはデフォルトの空実装が用意されているため、既存のカスタム Storage 実装は引き続きコンパイルできます。そのカスタムストレージを clearCredentials() と併用する場合は、ストレージを実際に消去できるよう、removeAll() をオーバーライドしてください。そうしないと、そのカスタムストレージに対する clearCredentials() は何もしません。

---

ステップ 10 — 移行の概要

以下を含む簡潔な概要を提示します。

1. 変更された前提条件 — 適用した minSdk／Java／Gradle／AGP／Kotlin のバージョン引き上げ、および minSdk 26 により Android 7.1 以下のサポートが終了すること。

2. 適用した変更 — API 領域（§7.x）ごとにまとめ、各領域で変更したファイルを記載します。

3. 手動レビューが必要な項目

• §7.1 のパスキー／§7.3 の MFA フローを新しいクライアントに移行した場合 — テナントに対してエンドツーエンドで再テストしてください。
• §7.2（Management API）に // TODO: が残っている場合 — バックエンドでの対応が必要です。

4. 動作の変更（コード変更なし。許容できるか確認してください）

• §9.1 minTtl のデフォルトが 60s になりました — トークンは有効期限の 60s 前に更新されます。
• §9.3 clearCredentials() が、API 認証情報を含むすべてのストレージを消去するようになりました。
• §9.2 CredentialsManager がグローバルエグゼキューターを使用するようになりました（更新処理は直列化されます）。

5. バックエンド／設定に関するフォローアップ

• §7.2 の Management API の削除 — TODO を付けてスタブ化した操作と、安全なバックエンド（M2M トークンはデバイス上に置かない）に移す必要があるものを列挙します。

6. 適用しなかった任意の改善（簡潔に列挙します。自動適用はしません）

• clearAll() — ログアウト／アカウント削除時に、認証情報および暗号鍵を完全に消去します。
• onCreate() での WebAuthProvider.registerCallbacks() — 認証中に構成変更やプロセス終了が発生した場合のコールバック消失／メモリーリークを防ぎます。
• DefaultClient.Builder — コンストラクターは非推奨ですが、削除されていません。ビルダーを使うと、書き込み／呼び出しのタイムアウト、カスタムインターセプター、ロガーを追加できます。
• Gson 2.8.9 → 2.11.0（推移的依存関係）— TypeToken／型の強制変換がより厳格になります。references/process.md を参照してください。

7. ユーザーへの確認 — 移行をコミットするか、任意の改善を検討するか、特定のファイルを一緒に確認するかを尋ねます。

セキュリティに関する注意： 概要やビルドログにトークン、シークレット、クライアント認証情報、保存済み認証情報の値を含めないでください。

---

詳細なリファレンス

• 移行プロセス — バージョン引数の検証、前提条件／ツールチェーンへの対応、ビルドシステムのエッジケース（Groovy DSL、Kotlin DSL、バージョンカタログ）、MFA メソッドの対応表、Management API のバックエンドパターン、Gson の推移的依存関係に関する注意、ロールバック、および「非推奨 ≠ 削除」のガイダンス。
• セキュリティチェックリスト — 移行前後に満たす必要がある不変条件。

よくある間違い

間違い	正しい対応
Step 5でプロジェクト内に該当APIが見つからなかったのに、§7.xのセクションを適用する	Step 5のファイル読み取りが適用可否の判断基準です。見つからなければ、そのセクション全体をスキップします
APIが使われているかどうかをgrepだけで判断する	grepでは、複数行にわたるビルダーチェーン（例：loginより前のuseDPoP）やエイリアスされた変数を見落とすことがあります。実際のファイルを読み取ります
Step 3の前提条件を満たす前にAPI呼び出し箇所を移行する	プロジェクトがminSdk 26／Java 17未満の場合、v4ではビルドできません。まず前提条件に対応します
検証せずにターゲットバージョンの引数を受け入れる	存在すること／次のメジャーバージョンであること／ダウングレードではないことを検証し、失敗した場合は停止して確認を求めます
プレリリースタグに動的な範囲（4.+）を指定する	プレリリースは正確なバージョンに固定します。範囲指定では別の成果物が解決される可能性があります
Management APIや削除されたMFAの呼び出し箇所を黙って削除する	// TODO:を追加し、概要に明記します。削除すると機能が壊れます
SDKのソースを確認せずに移行ガイドの変更を適用する	すべての修正について、Step 4で取得したファイル内のシグネチャを根拠として示せる必要があります
DefaultClient(...)コンストラクターを破壊的変更として扱う	非推奨になっただけで、削除されてはいません。そのままにし、Builderは任意であることを記載します
作業ツリーがクリーンでない状態で開始する	まずgit status --porcelainの出力が空であることを必ず確認します
ビルドに10回失敗した後も続ける	停止し、残っているエラーをユーザーに提示します
移行の概要を省略する	必ず完全な概要を作成します。ユーザーにはその概要が必要です

関連スキル

• auth0-android — Auth0.Androidを新規に統合する
• auth0-swift-major-migration — Auth0.swiftのメジャーバージョンをアップグレードする
• auth0-mfa — 多要素認証を設定する

---

参考資料

• Auth0.Android GitHub
• Auth0.Androidリリース
• V4移行ガイド
• Auth0 Android SDKドキュメント

セキュリティ： ビルドログやターミナル出力にトークン、クライアントシークレット、認証情報を決して出力しないでください。シークレットをバージョン管理にコミットしないでください。