auth0-android

Auth0 Android 集成

使用 com.auth0.android:auth0 为 Android 应用添加身份验证。

Agent 指令： 在提供 SDK 设置说明之前，请运行以下命令获取最新发布版本：

gh api repos/auth0/Auth0.Android/releases/latest --jq '.tag_name'

在所有 implementation 依赖项行中使用命令返回的版本，替代下方任何硬编码的版本。如果命令失败，请查看 https://github.com/auth0/Auth0.Android/releases。

前置条件

• Android API 21 或更高版本
• Kotlin 或 Java 项目
• 已配置 Native 应用的 Auth0 账户
• 如果尚未设置 Auth0，请参阅 auth0-quickstart

不适用场景

• 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/macOS 应用： 使用 auth0-swift

快速入门工作流

1. 安装 SDK：将 Auth0 Android SDK 依赖项添加到 build.gradle：

   implementation 'com.auth0.android:auth0:{LATEST_VERSION}'
   

2. 配置 Auth0：

   **Agent 指令：**检查用户提示词中是否已包含 Auth0 的 Client ID 和 Domain。

   • 如果两者都已提供，请直接使用这些值，按照设置指南中的手动设置进行操作。
   • 如果缺少任意一项，你必须在编写任何代码或文件之前询问用户：
     • 问题：“你希望如何为此项目配置 Auth0？”
     • 选项：“自动设置（推荐）——Auth0 CLI 创建应用并将凭据写入 strings.xml” / “手动设置——我会提供我的 Client ID 和 Domain”

   然后按照设置指南执行所选路径。 在确认 Auth0 凭据之前，不要继续执行第 3 步。

   **注意：**对于原生 Android 应用，Domain 和 Client ID 是公开配置（不是机密）。不使用客户端密钥。将值直接写入 strings.xml，不要在对话输出中显示这些值。

3. 初始化：创建 Auth0 账户实例：

   import com.auth0.android.Auth0
   
   val account = Auth0.getInstance(context)
   

   重要：Auth0.getInstance(context) 会自动从 strings.xml 中读取 com_auth0_client_id 和 com_auth0_domain。切勿将 clientId 或 domain 作为参数传入（例如 Auth0.getInstance(clientId, domain)）——这会将凭据硬编码在源代码中。

4. 添加 Auth UI：使用 Web Auth 实现登录和注销：

   **Agent 指令：**添加新的 UI 元素之前，先在项目中搜索登录、注销、登入或登出按钮的现有点击处理程序（例如，loginButton、signInButton、logoutButton、signOutButton，或名称中包含身份验证相关字样的 setOnClickListener）。如果找到现有处理程序，请将 Auth0 代码接入其中，不要修改现有 UI。只有在找不到现有处理程序时，才创建新按钮。

   登录：

   import com.auth0.android.Auth0
   import com.auth0.android.authentication.AuthenticationAPIClient
   import com.auth0.android.authentication.storage.SecureCredentialsManager
   import com.auth0.android.authentication.storage.SharedPreferencesStorage
   import com.auth0.android.callback.Callback
   import com.auth0.android.authentication.AuthenticationException
   import com.auth0.android.provider.WebAuthProvider
   import com.auth0.android.result.Credentials
   
   val account = Auth0.getInstance(context)
   val authentication = AuthenticationAPIClient(account)
   val storage = SharedPreferencesStorage(context)
   val credentialsManager = SecureCredentialsManager(context, authentication, storage)
   
   WebAuthProvider.login(account)
       .withScheme(getString(R.string.com_auth0_scheme))
       .withScope("openid profile email offline_access")
       .start(this, object : Callback<Credentials, AuthenticationException> {
           override fun onSuccess(result: Credentials) {
               // User authenticated
               val idToken = result.idToken
               val accessToken = result.accessToken
               // Store credentials securely
               credentialsManager.saveCredentials(result)
           }
           override fun onFailure(error: AuthenticationException) {
               // Handle authentication failure
               Log.e("Auth0", "Authentication failed", error)
           }
       })
   

   注销：

   WebAuthProvider.logout(account)
       .withScheme(getString(R.string.com_auth0_scheme))
       .start(this, object : Callback<Void?, AuthenticationException> {
           override fun onSuccess(result: Void) {
               // User logged out
           }
           override fun onFailure(error: AuthenticationException) {
               Log.e("Auth0", "Logout failed", error)
           }
       })
   

5. 构建并验证：

   **Agent 指令：**完成集成后，构建项目以验证其能否成功编译：

   ./gradlew assembleDebug
   

   如果构建失败，请分析错误输出并修复问题。常见的集成构建失败包括：

   • 未解析的引用：缺少导入语句——添加所需的 import com.auth0.android.* 导入
   • 无法解析符号 R.string.com_auth0_scheme：未更新 strings.xml——确认其中存在 com_auth0_scheme、com_auth0_client_id 和 com_auth0_domain 条目
   • 回调中的类型不兼容：回调类型参数不匹配——登录时确保使用 Callback<Credentials, AuthenticationException>，注销时确保使用 Callback<Void?, AuthenticationException>
   • 未解析的 lifecycleScope：缺少依赖项——添加 implementation 'androidx.lifecycle:lifecycle-runtime-ktx:2.6.+'，或将代码移出协程作用域
   • minSdk 过低：SDK 要求 API 21+——将 minSdkVersion 更新为至少 21
   • Java 版本不匹配：SDK 要求 Java 8——添加包含 JavaVersion.VERSION_1_8 的 compileOptions

   每次修复后重新运行构建。跟踪构建—修复迭代的次数。

   **失败检查：**如果尝试修复 5–6 次后构建仍然失败，请停止并询问用户：

   • 问题：“经过多次修复尝试后，构建仍然失败。你希望如何继续？”
   • 选项：“让 Agent 继续迭代修复” / “我会手动修复——向我显示错误” / “跳过构建验证并继续”

   如果错误仍然存在，请每经过 5–6 次迭代重复此检查。未经用户明确同意，不要让项目处于无法编译的状态。

   回调 URL 必须与 Auth0 应用设置匹配：{SCHEME}://{YOUR_AUTH0_DOMAIN}/android/{YOUR_APP_PACKAGE_NAME}/callback

详细文档

• 设置指南 — 安装 SDK、配置 Auth0 应用、设置回调 URL、Android App Links、自定义 scheme、ProGuard/R8
• 集成模式 — Web Auth 登录/登出、凭据存储、生物识别身份验证、数据库登录、无密码身份验证、MFA 处理、自定义标签页、错误处理
• 测试与参考 — 测试清单、常见问题、安全注意事项、API 参考

常见错误

错误	修复方法
未在 Auth0 Dashboard 中将应用类型设为 Native	在你的 Auth0 租户中创建 Native 类型的应用。Android SDK 要求使用 Native 应用配置，而不是 Machine-to-Machine 或其他类型。
Allowed Callback URLs 中缺少回调 URL	将 {SCHEME}://{YOUR_AUTH0_DOMAIN}/android/{YOUR_APP_PACKAGE_NAME}/callback 添加到 Auth0 应用的 Allowed Callback URLs 设置中，其中 {SCHEME} 与 strings.xml 中的 com_auth0_scheme 相匹配（例如，默认为 demo）。
缺少 <uses-permission android:name="android.permission.INTERNET" />	将 INTERNET 权限添加到 AndroidManifest.xml。SDK 需要网络访问权限才能进行身份验证。
自定义 scheme 使用小写字母	Android 要求 scheme 名称使用小写字母。使用 https（推荐）或小写自定义 scheme，例如 myapp://callback。
直接调用身份验证时忘记 .validateClaims()	直接使用 AuthenticationAPIClient 时，务必调用 .validateClaims()（适用于数据库、无密码或 API 登录）。Web Auth 会自动进行验证。
未加密便将令牌存储在 SharedPreferences 中	使用 SecureCredentialsManager 存储凭据。切勿以明文手动存储令牌。该管理器会加密静态存储的令牌。
缺少 manifest 占位符	将 manifestPlaceholders = [auth0Domain: "@string/com_auth0_domain", auth0Scheme: "@string/com_auth0_scheme"] 添加到 build.gradle 的 defaultConfig 块中。

相关技能

• auth0-quickstart — 设置 Auth0 账户和应用
• auth0-mfa — 配置多因素身份验证
• auth0-swift — iOS/macOS 身份验证
• auth0-cli — 在终端中管理 Auth0 资源

快速参考

核心类

类	用途
Auth0	SDK 的入口，保存应用凭据
WebAuthProvider	通过浏览器进行 OAuth 2.0 登录/登出
AuthenticationAPIClient	直接调用 API（数据库登录、无密码身份验证、MFA）
SecureCredentialsManager	安全存储和检索凭据
Credentials	用户令牌和过期时间

常见用例

• 通过 Web Auth 登录
• 登出
• 安全存储凭据
• 要求进行生物识别身份验证
• 数据库登录
• 无密码身份验证
• 处理 MFA
• 调用受保护的 API

参考资料

• Auth0 Android SDK 文档
• Auth0 Android GitHub 仓库
• Android SDK Javadoc
• Auth0 Android 快速入门
• 示例应用