auth0-net-ios

auth0-net-ios 集成

为 .NET iOS 应用添加 Auth0 身份验证。此技能集成了 Auth0.OidcClient.iOS NuGet 包，该包使用 ASWebAuthenticationSession 通过 PKCE 实现安全的基于 OIDC 的登录和注销流程。

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

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

在所有依赖项声明中使用返回的版本，而不是下面任何硬编码的版本。

前提条件

• .NET 8.0 SDK 或更高版本（也支持 .NET 9 — 使用 net9.0-ios 目标框架）
• 安装了 iOS 工作负载的 JetBrains Rider 或 VS Code 和 C# Dev Kit
• 装有 Xcode 15+ 的 macOS
• iOS 14.0+ 部署目标
• 已配置 Native 应用的 Auth0 帐户
• Node.js 20+（用于 Auth0 CLI 自动设置）

不适用场景

使用场景	推荐技能
.NET MAUI 跨平台应用（iOS + Android + Windows）	auth0-maui
仅面向 .NET Android 的应用	auth0-net-android
仅面向 iOS 的 Swift 应用	auth0-swift
ASP.NET Core 服务端 Web 应用	auth0-aspnetcore-authentication
ASP.NET Core Web API（JWT 验证）	auth0-aspnetcore-api
React Native 移动应用	auth0-react-native

快速入门工作流

Agent 指令： 开始之前，检查用户的项目：

1. 从 .csproj 文件（TargetFramework）中确定 .NET 版本
2. 检查现有的身份验证实现 — 搜索现有的登录/注销处理程序，并在找到时接入它们（复用登录按钮等现有 UI 元素，而不是创建重复元素）
3. 记下项目的 Bundle Identifier，可从 Info.plist 或 .csproj 获取
4. 查找现有的 Auth0Client 或 Auth0ClientOptions 用法，以避免重复配置

1. 安装 SDK：dotnet add package Auth0.OidcClient.iOS
2. 配置 Auth0：自动或手动配置请参见设置指南。
3. 集成身份验证：添加 Auth0Client 实例化，在 Info.plist 中注册 URL scheme，并将登录/注销绑定到 UI 操作。
4. 处理回调：在 AppDelegate 中实现 OpenUrl，并调用 ActivityMediator.Instance.Send(url.AbsoluteString)。
5. 构建并验证：dotnet build

Agent 指令： 编写 Auth0Client 配置时：

• iOS SDK 不需要传入 Activity 上下文 — 只需使用 new Auth0Client(options)。
• 始终设置 Scope = "openid profile email offline_access" — offline_access 范围是接收刷新令牌的必要条件，可在不重新提示用户的情况下静默续订令牌。
• 回调 URL 会根据 Bundle Identifier 自动生成：{BundleId}://{domain}/ios/{BundleId}/callback。
• 必须在 Info.plist 中将 Bundle Identifier 注册为 URL scheme。
• AppDelegate 必须处理 OpenUrl，并调用 ActivityMediator.Instance.Send(url.AbsoluteString)。
• 安全存储令牌：登录成功后，使用 iOS Keychain（通过 Security framework 或 KeychainAccess 等封装库）持久化 AccessToken 和 RefreshToken。切勿将令牌存储在 UserDefaults 中，也不要只存储在内存变量中。

编写配置和代码后，验证构建是否成功：

dotnet build

如果构建失败，请尝试修复问题。失败 5-6 次后，请向用户求助。

WebAuth — 身份验证的工作方式

SDK 使用 ASWebAuthenticationSession（安全的系统浏览器）。调用 LoginAsync() 时：

1. SDK 使用 PKCE 参数（代码验证器 + 挑战）构造 /authorize URL
2. ASWebAuthenticationSession 打开并显示 Auth0 登录页面
3. 用户进行身份验证（登录表单、社交连接、MFA 等）
4. Auth0 重定向到原生回调 URL：{BundleId}://{domain}/ios/{BundleId}/callback
5. iOS 拦截 URL 方案并将其传递给 AppDelegate.OpenUrl
6. ActivityMediator.Instance.Send(url.AbsoluteString) 完成令牌交换
7. SDK 返回 LoginResult，其中包含访问令牌、ID 令牌、刷新令牌和用户声明

这是 OAuth 2.0 授权码流程搭配 PKCE 的标准方式，推荐用于原生移动应用。

回调 URL 配置

.NET iOS 的原生回调 URL 使用 Bundle Identifier 作为方案。格式如下：

YOUR_BUNDLE_IDENTIFIER://YOUR_AUTH0_DOMAIN/ios/YOUR_BUNDLE_IDENTIFIER/callback

其中，YOUR_BUNDLE_IDENTIFIER 是应用的 Bundle Identifier，例如 com.mycompany.myapplication。例如：com.mycompany.myapp://tenant.us.auth0.com/ios/com.mycompany.myapp/callback。

注意： 部分 Auth0 原生 SDK 使用 https://{domain}/ios/{bundleId}/callback 或 {bundleId}.auth0://{domain}/ios/{bundleId}/callback 作为回调 URL 格式。.NET iOS SDK 直接使用 Bundle Identifier 作为 URL 方案。

确保回调 URL 使用小写字母。

此 URL 必须：

1. 在 Auth0 Dashboard 的 Allowed Callback URLs 和 Allowed Logout URLs 中注册
2. 在 Info.plist 的 CFBundleURLSchemes 下注册为 URL 方案

完成标准

• 已安装 Auth0.OidcClient.iOS 包（最新稳定版本）
• 已使用 Domain、ClientId 和 Scope = "openid profile email offline_access" 配置 Auth0Client
• 已在 Info.plist 中注册与 Bundle Identifier 匹配的 URL 方案
• 已实现 AppDelegate.OpenUrl，并调用 ActivityMediator.Instance.Send(url.AbsoluteString)
• 已将回调 URL 添加到 Auth0 Dashboard 的 Allowed Callback URLs 和 Allowed Logout URLs
• 已使用 iOS Keychain 安全存储令牌（通过 Security 框架和 SecKeyChain.Add）
• 登录／注销流程正常工作
• 构建成功且无错误

详细文档

• 设置指南 — Auth0 租户配置、SDK 安装、Info.plist URL 方案设置
• 集成模式 — 登录／注销流程、令牌访问、用户资料、错误处理
• API 参考与测试 — 完整的 Auth0ClientOptions 参考、声明、测试清单、故障排查

常见错误

错误	修复方法
Auth0 Dashboard 中未将应用类型设为 Native	在 Dashboard 设置中将应用类型改为 "Native"
Auth0 Dashboard 中缺少回调 URL	将 yourbundleid://{domain}/ios/yourbundleid/callback 添加到 Allowed Callback URLs 和 Allowed Logout URLs
Info.plist 中缺少 URL 方案	添加与 Bundle Identifier 匹配的 CFBundleURLSchemes 条目
未在 AppDelegate 中处理 OpenUrl	重写 OpenUrl，并调用 ActivityMediator.Instance.Send(url.AbsoluteString)
Domain 使用了 https:// 前缀	Domain 应仅包含主机名（例如 tenant.auth0.com，而不是 https://tenant.auth0.com）
向 Auth0Client 传递 Activity 上下文（Android 模式）	iOS 不需要上下文——只需使用 new Auth0Client(options)
URL 方案与 Bundle Identifier 不匹配	CFBundleURLSchemes 的值必须与 Bundle Identifier 完全一致
将令牌存储在 UserDefaults 中或仅保存在内存中	使用 Security 框架通过 iOS Keychain 持久化令牌（SecKeyChain.Add）

测试说明

**Agent 指令：**提醒用户除了模拟器外，还要在实体设备上进行测试。WebAuth/ASWebAuthenticationSession 的某些行为在实体设备和模拟器上可能有所不同。发布前，请在真实硬件上测试完整的登录 → 回调 → 令牌流程。

实体设备测试：

• 登录流程：ASWebAuthenticationSession 打开 → 完成身份验证 → 返回应用
• 回调：AppDelegate 中触发 OpenUrl，并携带正确的 URL
• 登出流程：浏览器打开 → 会话清除 → 返回应用
• 取消：用户关闭工作表 → 应用妥善处理 UserCancel

相关技能

• auth0-maui — .NET MAUI 跨平台应用（iOS + Android + Windows）
• auth0-net-android — 仅限 .NET Android 应用
• auth0-swift — 仅限 iOS 的 Swift 应用
• 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"
});

var loginResult = await client.LoginAsync();
BrowserResultType browserResult = await client.LogoutAsync();

**Agent 指令：**始终在作用域中包含 offline_access，以启用刷新令牌。这样应用无需强制用户重新进行身份验证，即可静默刷新访问令牌。

**Agent 指令：**登录后，始终使用 Security 框架将令牌持久化到 iOS Keychain（使用 SecAccessible.WhenUnlockedThisDeviceOnly 的 SecKeyChain.Add）。切勿将令牌存储在 UserDefaults 中，也不要只将其保留在内存中。登出时清除令牌。完整的 SecureTokenStorage 辅助类请参阅集成模式。

必需的平台配置

要使回调正常工作，必须配置以下两项内容——完整代码请参阅设置指南：

1. Info.plist：添加与 Bundle Identifier 匹配的 CFBundleURLSchemes 条目
2. AppDelegate：重写 OpenUrl 并调用 ActivityMediator.Instance.Send(url.AbsoluteString)

有关使用额外参数登录、错误处理、令牌刷新、用户声明访问权限以及完整的 ViewController 示例，请参阅集成模式。

参考资料

• .NET Android 和 iOS 快速入门
• GitHub 仓库
• NuGet 包 — Auth0.OidcClient.iOS
• SDK API 文档
• Auth0 原生应用文档