Auth0 Android 是用于为 Android 应用添加 Auth0 身份认证的集成技能，适用语言为 Kotlin 或 Java，依赖 com.auth0.android:auth0。
一、用途 在 Android 应用中集成 Auth0 的登录、登出与凭证管理能力，覆盖 Web Auth 流程、受生物识别保护的 CredentialsManager 以及凭证安全存储等场景。
二、前置条件
- Android API 21 及以上
- Kotlin 或 Java 项目
- 已配置 Native 类型应用的 Auth0 账号；若尚未配置，参见 auth0-quickstart
三、不适用场景
- React Native 应用：使用 auth0-react-native
- Flutter 应用：使用原生 Flutter Auth0 SDK
- Web 单页应用（React、Angular、Vue）：使用 auth0-react、auth0-angular 或 auth0-vue
- Node.js/Express 服务器：使用 auth0-express
- iOS/macOS 应用：使用 auth0-swift
四、使用方式（快速开始流程）
- 安装 SDK：在 build.gradle 中添加 implementation 'com.auth0.android:auth0:{LATEST_VERSION}'。技能说明中要求先通过以下命令获取最新版本号，并使用返回版本替换所有硬编码版本；若命令失败，则回退查看 https://github.com/auth0/Auth0.Android/releases： gh api repos/auth0/Auth0.Android/releases/latest --jq '.tag_name'
- 配置 Auth0：先确认用户提示中是否同时包含 Client ID 和 Domain；若都提供则直接进入手动设置；若缺少任一，需先向用户询问采用自动设置还是手动设置，得到确认后再继续。原生 Android 应用的 Domain 与 Client ID 属于公开配置（非密钥），不使用客户端密钥，值直接写入 strings.xml，不在对话中显示。
- 初始化：创建 Auth0 实例，val account = Auth0.getInstance(context)。注意 Auth0.getInstance(context) 会自动从 strings.xml 读取 com_auth0_client_id 和 com_auth0_domain；不应把 clientId 或 domain 作为参数传入（例如 Auth0.getInstance(clientId, domain)），以免硬编码凭证到源码。
- 添加 Auth UI：用 Web Auth 实现登录与登出。在添加新 UI 元素前，先在项目中搜索是否已有登录、登出、sign-in、sign-out 按钮的点击处理器（如 loginButton、signInButton、logoutButton、signOutButton，或与 auth 命名相关的 setOnClickListener）；若已存在，则把 Auth0 代码接入现有处理器而不修改现有 UI，仅在未找到时新建按钮。登录使用 WebAuthProvider.login(account).withScheme(...).withScope("openid profile email offline_access").start(...)，成功回调中保存凭证 credentialsManager.saveCredentials(result)；登出使用 WebAuthProvider.logout(account).withScheme(...).start(...)。
- 构建与验证：集成完成后运行 ./gradlew assembleDebug 验证编译。若构建失败，需分析错误并修复，常见问题包括：缺少 import com.auth0.android.*；strings.xml 未更新（需确认 com_auth0_scheme、com_auth0_client_id、com_auth0_domain 存在）；回调类型不匹配（登录为 Callback<Credentials, AuthenticationException>，登出为 Callback<Void?, AuthenticationException>）；缺少 lifecycleScope 依赖；minSdk 低于 21；Java 版本不匹配（需 Java 8，添加 compileOptions 与 JavaVersion.VERSION_1_8）。每次修复后重新构建并统计迭代次数；若修复 5–6 次后仍失败，须停下来询问用户后续处理方式（继续迭代修复、手动修复并展示错误、或跳过构建验证），且不得在未经用户明确同意的情况下让项目停留在无法编译状态。
- 回调 URL 必须与 Auth0 应用设置一致：{SCHEME}://{YOUR_AUTH0_DOMAIN}/android/{YOUR_APP_PACKAGE_NAME}/callback
五、常见错误与修复
- Auth0 Dashboard 中应用类型未设为 Native：创建 Native 类型应用，Android SDK 需要 Native 配置。
- Allowed Callback URLs 缺少回调 URL：按上述格式添加，其中 {SCHEME} 与 strings.xml 中的 com_auth0_scheme 一致（默认如 demo）。
- 缺少 <uses-permission android:name="android.permission.INTERNET" />：在 AndroidManifest.xml 中添加 INTERNET 权限。
- 自定义 scheme 使用小写：Android 要求 scheme 名小写，推荐使用 https，或使用小写自定义 scheme 如 myapp://callback。
- 直接认证调用忘记 .validateClaims()：使用 AuthenticationAPIClient 直接调用（数据库、无密码或 API 登录）时必须调用 .validateClaims()，Web Auth 会自动验证。
- 明文 SharedPreferences 存储 token：使用 SecureCredentialsManager 存储凭证，避免手动明文存储，该管理器会在静态加密。
- 缺少 manifest 占位符：在 build.gradle 的 defaultConfig 块添加 manifestPlaceholders = [auth0Domain: "@string/com_auth0_domain", auth0Scheme: "@string/com_auth0_scheme"]。
六、相关技能与核心类 相关技能：auth0-quickstart、auth0-mfa、auth0-swift、auth0-cli。 核心类：Auth0（SDK 入口，保存应用凭证）、WebAuthProvider（基于浏览器的 OAuth 2.0 登录/登出）、AuthenticationAPIClient（直接 API 调用，如数据库登录、无密码、MFA）、SecureCredentialsManager（凭证的安全存储与读取）、Credentials（用户 token 与过期时间）。 常见用例包括：Web Auth 登录、登出、安全存储凭证、要求生物识别认证、数据库登录、无密码认证、处理 MFA、调用受保护 API。
七、限制
- 仅适用于原生 Android（Kotlin/Java），不适用于跨平台或 Web/服务端/iOS 场景。
- 需 Android API 21+、Java 8，且应用需在 Auth0 中配置为 Native 类型并设置正确的回调 URL。
- 其他未在资料中说明的功能、收费、价格、平台或效果暂未提供。