auth0-maui

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

auth0-maui Integration

auth0-maui 集成

Add Auth0 authentication to .NET MAUI applications targeting iOS, Android, macOS, and Windows. This skill integrates the

Auth0.OidcClient.MAUI

NuGet package which uses the system browser via MAUI's

WebAuthenticator

for secure OIDC-based login and logout flows with PKCE.

Agent instruction: Before providing SDK setup instructions, fetch the latest MAUI release version by running:
bash
gh api repos/auth0/auth0-oidc-client-net/releases --jq '[.[] | select(.tag_name | startswith("maui-")) | .tag_name | ltrimstr("maui-")] | .[0]'
Use the returned version in all dependency lines instead of any hardcoded version below.

为面向iOS、Android、macOS和Windows的.NET MAUI应用添加Auth0身份认证功能。本技能集成了

Auth0.OidcClient.MAUI

NuGet包，该包通过MAUI的

WebAuthenticator

调用系统浏览器，实现基于OIDC的安全登录和登出流程，并支持PKCE。

Agent 指令： 在提供SDK设置说明前，运行以下命令获取最新MAUI版本：
bash
gh api repos/auth0/auth0-oidc-client-net/releases --jq '[.[] | select(.tag_name | startswith("maui-")) | .tag_name | ltrimstr("maui-")] | .[0]'
将返回的版本号用于所有依赖项配置，替代下方所有硬编码版本。

Prerequisites

前提条件

.NET 8.0 SDK or later
Visual Studio 2022 (17.8+) with MAUI workload, or JetBrains Rider with MAUI support
For iOS: macOS with Xcode 15+
For Android: Android SDK API 33+ (net8.0) or API 34+ (net9.0)
For Windows: Windows 10 (10.0.19041.0)+
Auth0 account with a Native application configured
Node.js 20+ (for Auth0 CLI automated setup)

.NET 8.0 SDK或更高版本
安装了MAUI工作负载的Visual Studio 2022（17.8+），或支持MAUI的JetBrains Rider
iOS开发：安装Xcode 15+的macOS系统
Android开发：Android SDK API 33+（net8.0）或API 34+（net9.0）
Windows开发：Windows 10（10.0.19041.0）及以上版本
已配置Native应用的Auth0账户
Node.js 20+（用于Auth0 CLI自动化设置）

When NOT to Use

不适用于以下场景

Use Case	Recommended Skill
ASP.NET Core server-side web app	`auth0-aspnetcore-authentication`
ASP.NET Core Web API (JWT validation)	`auth0-aspnetcore-api`
React Native mobile app	`auth0-react-native`
iOS-only Swift app	`auth0-swift`
Android-only Kotlin app	`auth0-android`
Expo React Native app	`auth0-expo`

使用场景	推荐技能
ASP.NET Core服务器端Web应用	`auth0-aspnetcore-authentication`
ASP.NET Core Web API（JWT验证）	`auth0-aspnetcore-api`
React Native移动应用	`auth0-react-native`
仅iOS的Swift应用	`auth0-swift`
仅Android的Kotlin应用	`auth0-android`
Expo React Native应用	`auth0-expo`

Quick Start Workflow

快速开始流程

Agent instruction: Before starting, examine the user's project:
Identify the .NET version from the
.csproj
file (
TargetFrameworks
)
Check for existing authentication implementations — search for existing login/logout handlers and hook into them if found

Note the project's namespace and directory conventions
Look for existing
Auth0Client
or
Auth0ClientOptions
usage to avoid duplicate configuration

Install SDK:

dotnet add package Auth0.OidcClient.MAUI

Configure Auth0: See Setup Guide for automatic or manual configuration.
Integrate authentication: Add
```
Auth0Client
```
instantiation and wire login/logout to UI actions.
- IMPORTANT: Always set
```
Scope = "openid profile email offline_access"
```
  — the
```
offline_access
```
  scope is required to receive a refresh token for silent token renewal.
Persist tokens with SecureStorage: After login, store the refresh token using
```
await SecureStorage.Default.SetAsync("refresh_token", loginResult.RefreshToken)
```
. On app startup, restore the session with
```
RefreshTokenAsync
```
. Clear on logout with
```
SecureStorage.Default.Remove("refresh_token")
```
.

Register URL scheme: Configure platform-specific callback handling:

Android: Create
```
WebAuthenticatorActivity
```
with IntentFilter for your custom scheme (e.g.,
```
myapp
```
)

Windows (two steps required): (1) Add

<uap:Extension Category="windows.protocol"><uap:Protocol Name="myapp"/></uap:Extension>

Platforms/Windows/Package.appxmanifest

, AND (2) call

Activator.Default.CheckRedirectionActivation()

Platforms/Windows/App.xaml.cs

iOS/macOS: No extra configuration needed

Build and verify:
```
dotnet build
```

Agent instruction: When writing the Auth0Client configuration:
ALWAYS include
offline_access
in the Scope string — without it, no refresh token is returned and the user must re-authenticate every time the access token expires.
ALWAYS implement token persistence using
SecureStorage.Default.SetAsync("refresh_token", ...)
after login and
SecureStorage.Default.GetAsync("refresh_token")
on app startup to restore sessions silently.
Clear stored tokens on logout with
SecureStorage.Default.Remove("refresh_token")
.
ALWAYS create/update
Platforms/Windows/Package.appxmanifest
to register the custom URL scheme protocol. Without this, Windows will not intercept the callback URL after authentication. Add a
<uap:Extension Category="windows.protocol"><uap:Protocol Name="myapp"/></uap:Extension>
inside the
<Extensions>
element of the
<Application>
node.
ALWAYS add
CheckRedirectionActivation()
in
Platforms/Windows/App.xaml.cs
as the first line in the constructor, before
InitializeComponent()
.
After writing configuration and code, verify the build succeeds:
bash
dotnet build
If the build fails, attempt to fix the issue. After 5-6 failed attempts, ask the user for help.

Agent 指令： 开始前先检查用户项目：
从
.csproj
文件的
TargetFrameworks
字段识别.NET版本
检查是否已有身份认证实现——搜索现有的登录/登出处理程序，若存在则对接现有逻辑

记录项目的命名空间和目录规范
查找是否已有
Auth0Client
或
Auth0ClientOptions
的使用，避免重复配置

安装SDK：

dotnet add package Auth0.OidcClient.MAUI

配置Auth0：参考设置指南进行自动或手动配置。
集成身份认证：实例化
```
Auth0Client
```
并将登录/登出功能关联到UI操作。
- 重要提示： 务必设置
```
Scope = "openid profile email offline_access"
```
  ——
```
offline_access
```
  权限是获取刷新令牌以实现静默令牌续期的必要条件。
使用SecureStorage持久化令牌：登录成功后，通过
```
await SecureStorage.Default.SetAsync("refresh_token", loginResult.RefreshToken)
```
存储刷新令牌。应用启动时，调用
```
RefreshTokenAsync
```
恢复会话。登出时通过
```
SecureStorage.Default.Remove("refresh_token")
```
清除令牌。

注册URL协议：配置平台特定的回调处理：

Android：创建带有IntentFilter的
```
WebAuthenticatorActivity
```
，匹配自定义协议（如
```
myapp
```
）

Windows（需两步）：(1) 在

Platforms/Windows/Package.appxmanifest

中添加

<uap:Extension Category="windows.protocol"><uap:Protocol Name="myapp"/></uap:Extension>

；(2) 在

Platforms/Windows/App.xaml.cs

中调用

Activator.Default.CheckRedirectionActivation()

iOS/macOS：无需额外配置

构建并验证：
```
dotnet build
```

Agent 指令： 编写Auth0Client配置时：
务必在Scope字符串中包含
offline_access
——缺少该权限将无法获取刷新令牌，用户需在访问令牌过期后重新认证。
务必在登录后使用
SecureStorage.Default.SetAsync("refresh_token", ...)
持久化令牌，并在应用启动时通过
SecureStorage.Default.GetAsync("refresh_token")
+
RefreshTokenAsync
实现会话静默恢复。
登出时通过
SecureStorage.Default.Remove("refresh_token")
清除存储的令牌。
务必创建/更新
Platforms/Windows/Package.appxmanifest
以注册自定义URL协议。否则Windows将无法拦截认证后的回调URL。在
<Application>
节点的
<Extensions>
元素内添加
<uap:Extension Category="windows.protocol"><uap:Protocol Name="myapp"/></uap:Extension>
。
务必在Windows的
App.xaml.cs
构造函数的第一行（
InitializeComponent()
之前）添加
CheckRedirectionActivation()
。
完成配置和代码编写后，验证构建是否成功：
bash
dotnet build
若构建失败，尝试修复问题。经过5-6次失败尝试后，向用户求助。

Callback URL Configuration

回调URL配置

The MAUI SDK uses a custom URL scheme for callbacks. The default pattern is:

text

myapp://callback

Unlike other Auth0 native SDKs that use

https://{domain}/{platform}/{bundleId}/callback

{bundleId}.auth0://{domain}/ios/{bundleId}/callback

patterns, MAUI uses a simpler custom scheme approach. You can customize the scheme (e.g.,

com.mycompany.myapp://callback

). Whatever scheme you choose must be:

Registered in Auth0 Dashboard under Allowed Callback URLs and Allowed Logout URLs
Configured in the platform-specific callback handler (Android
```
IntentFilter
```
, Windows
```
Package.appxmanifest
```
)

Set in

Auth0ClientOptions.RedirectUri

and

Auth0ClientOptions.PostLogoutRedirectUri

Note: For production apps, use a reverse-domain scheme (e.g.,
com.yourcompany.yourapp://callback
) to reduce the risk of URL scheme hijacking.

MAUI SDK使用自定义URL协议处理回调。默认格式为：

text

myapp://callback

与其他Auth0原生SDK使用

https://{domain}/{platform}/{bundleId}/callback

或

{bundleId}.auth0://{domain}/ios/{bundleId}/callback

格式不同，MAUI采用更简洁的自定义协议方式。你可以自定义协议（如

com.mycompany.myapp://callback

）。无论选择哪种协议，都必须满足：

在Auth0控制台的允许回调URL和允许登出URL中注册
在平台特定的回调处理程序中配置（Android的
```
IntentFilter
```
、Windows的
```
Package.appxmanifest
```
）

在

Auth0ClientOptions.RedirectUri

和

Auth0ClientOptions.PostLogoutRedirectUri

中设置

注意： 生产应用建议使用反向域名格式的协议（如
com.yourcompany.yourapp://callback
），以降低URL协议劫持风险。

Done When

完成标准

```
Auth0.OidcClient.MAUI
```
package installed
```
Auth0Client
```
configured with Domain, ClientId, and
```
Scope
```
including
```
offline_access
```
URL scheme registered on Android (WebAuthenticatorCallbackActivity) and Windows (Package.appxmanifest)
Callback URL (
```
myapp://callback
```
) added to Auth0 Dashboard Allowed Callback URLs and Allowed Logout URLs
Login/logout flow working
Refresh token persisted via
```
SecureStorage.Default.SetAsync
```
after login
Session restoration implemented via
```
SecureStorage.Default.GetAsync
```
+
```
RefreshTokenAsync
```
on app startup
Build succeeds with no errors
Tested on physical device or emulator/simulator

已安装
```
Auth0.OidcClient.MAUI
```
包
```
Auth0Client
```
已配置Domain、ClientId，且
```
Scope
```
包含
```
offline_access
```
已在Android（WebAuthenticatorCallbackActivity）和Windows（Package.appxmanifest）中注册URL协议
回调URL（
```
myapp://callback
```
）已添加到Auth0控制台的允许回调URL和允许登出URL
登录/登出流程正常工作
登录后已通过
```
SecureStorage.Default.SetAsync
```
持久化刷新令牌

应用启动时已通过

SecureStorage.Default.GetAsync

RefreshTokenAsync

实现会话恢复

构建无错误
已在物理设备或模拟器/仿真器上测试

Detailed Documentation

详细文档

Setup Guide — Auth0 tenant configuration, SDK installation, platform-specific callback setup
Integration Patterns — Login/logout flows, token refresh, user profile, error handling, MVVM patterns
API Reference & Testing — Full
```
Auth0ClientOptions
```
reference, claims, testing checklist, troubleshooting

设置指南 — Auth0租户配置、SDK安装、平台特定回调设置
集成模式 — 登录/登出流程、令牌刷新、用户信息、错误处理、MVVM模式
API参考与测试 —
```
Auth0ClientOptions
```
完整参考、声明、测试清单、故障排除

Common Mistakes

常见错误

Mistake	Fix
App type not set to Native in Auth0 Dashboard	Change application type to "Native" in Dashboard settings
Missing callback URL in Auth0 Dashboard	Add `myapp://callback` (or your scheme) to Allowed Callback URLs AND Allowed Logout URLs
Android: Missing `WebAuthenticatorCallbackActivity`	Create activity class with `[IntentFilter]` matching your callback scheme
Windows: Not calling `CheckRedirectionActivation()`	Add `Activator.Default.CheckRedirectionActivation()` at start of Windows `App.xaml.cs` , before `InitializeComponent()`
Using `https://` prefix in Domain	Domain should be hostname only (e.g., `tenant.auth0.com` , not `https://tenant.auth0.com` )
Not requesting `offline_access` scope for token refresh	Add `offline_access` to `Scope` in `Auth0ClientOptions` to get a refresh token
RedirectUri/PostLogoutRedirectUri not matching Dashboard	Ensure the exact URI (scheme + path) matches what's configured in Auth0 Dashboard
Not registering URL scheme on Android/Windows	Register the custom URL scheme in platform-specific config (see Platform setup step)
Storing tokens in plain text	Use `SecureStorage` from MAUI Essentials for persisting refresh tokens

错误	修复方案
Auth0控制台中应用类型未设置为Native	在控制台设置中将应用类型改为“Native”
Auth0控制台中缺少回调URL	将 `myapp://callback` （或自定义协议）添加到允许回调URL和允许登出URL
Android：缺少 `WebAuthenticatorCallbackActivity`	创建带有 `[IntentFilter]` 的活动类，匹配回调协议
Windows：未调用 `CheckRedirectionActivation()`	在Windows的 `App.xaml.cs` 构造函数开头（ `InitializeComponent()` 之前）添加 `Activator.Default.CheckRedirectionActivation()`
Domain使用 `https://` 前缀	Domain应仅为主机名（如 `tenant.auth0.com` ，而非 `https://tenant.auth0.com` ）
未请求 `offline_access` 权限以实现令牌刷新	在 `Auth0ClientOptions` 的 `Scope` 中添加 `offline_access` 以获取刷新令牌
RedirectUri/PostLogoutRedirectUri与控制台配置不匹配	确保URI（协议+路径）与Auth0控制台中的配置完全一致
Android/Windows未注册URL协议	在平台特定配置中注册自定义URL协议（见平台设置步骤）
明文存储令牌	使用MAUI Essentials的 `SecureStorage` 持久化刷新令牌

Testing Notes

测试注意事项

Agent instruction: Remind the user to test on a physical device in addition to emulators/simulators. Some WebAuthenticator behaviors (system browser integration, URL scheme interception) may differ on physical devices vs. emulators. Test the full login → callback → token flow on real hardware before shipping.

Testing Checklist:

Login flow: System browser opens → authenticate → returns to app
Logout flow: Browser opens → session cleared → returns to app
Token refresh:
```
RefreshTokenAsync
```
with stored refresh token works
Cancel: User cancels login → app handles
```
UserCancel
```
gracefully
Physical device: Test on real iOS/Android device (not just simulator)
Offline: Verify token refresh works when the app is restarted
Multi-platform: Test on at least one mobile platform (iOS or Android) and Windows

Agent 指令： 提醒用户除了模拟器/仿真器外，还要在物理设备上测试。部分WebAuthenticator行为（系统浏览器集成、URL协议拦截）在物理设备和模拟器上可能存在差异。发布前务必在真实硬件上测试完整的登录→回调→令牌流程。

测试清单：

登录流程：系统浏览器打开→完成认证→返回应用
登出流程：浏览器打开→会话清除→返回应用
令牌刷新：使用存储的刷新令牌调用
```
RefreshTokenAsync
```
成功
取消操作：用户取消登录→应用优雅处理
```
UserCancel
```
错误
物理设备：在真实iOS/Android设备上测试（而非仅模拟器）
离线测试：验证应用重启后令牌刷新功能正常
多平台测试：至少在一个移动平台（iOS或Android）和Windows上测试

Related Skills

Quick Reference

快速参考

csharp

using Auth0.OidcClient;

// Initialize client
var client = new Auth0Client(new Auth0ClientOptions
{
    Domain = "YOUR_AUTH0_DOMAIN",
    ClientId = "YOUR_AUTH0_CLIENT_ID",
    RedirectUri = "myapp://callback",
    PostLogoutRedirectUri = "myapp://callback",
    Scope = "openid profile email offline_access"
});

// Login — opens system browser
var loginResult = await client.LoginAsync();
if (!loginResult.IsError)
{
    var user = loginResult.User;
    var accessToken = loginResult.AccessToken;
    var idToken = loginResult.IdentityToken;
    var refreshToken = loginResult.RefreshToken;

    // Access user claims
    var name = user.FindFirst("name")?.Value;
    var email = user.FindFirst("email")?.Value;

    // Persist refresh token securely for session restoration
    if (!string.IsNullOrEmpty(refreshToken))
        await SecureStorage.Default.SetAsync("refresh_token", refreshToken);
}

// Logout — clears Auth0 session and stored tokens
await client.LogoutAsync();
SecureStorage.Default.Remove("refresh_token");

// Restore session on app startup (no user interaction needed)
var savedToken = await SecureStorage.Default.GetAsync("refresh_token");
if (!string.IsNullOrEmpty(savedToken))
{
    var refreshResult = await client.RefreshTokenAsync(savedToken);
    if (!refreshResult.IsError)
    {
        var newAccessToken = refreshResult.AccessToken;
        // Update stored token if rotated
        if (!string.IsNullOrEmpty(refreshResult.RefreshToken))
            await SecureStorage.Default.SetAsync("refresh_token", refreshResult.RefreshToken);
    }
    else
    {
        // Refresh failed — clear and require re-login
        SecureStorage.Default.Remove("refresh_token");
    }
}

// Get user info from /userinfo endpoint
var userInfo = await client.GetUserInfoAsync(accessToken);

// Login with extra parameters (organization, audience, connection)
var orgLogin = await client.LoginAsync(new { organization = "org_abc123" });
var apiLogin = await client.LoginAsync(new { audience = "https://my-api.example.com" });

csharp

using Auth0.OidcClient;

// 初始化客户端
var client = new Auth0Client(new Auth0ClientOptions
{
    Domain = "YOUR_AUTH0_DOMAIN",
    ClientId = "YOUR_AUTH0_CLIENT_ID",
    RedirectUri = "myapp://callback",
    PostLogoutRedirectUri = "myapp://callback",
    Scope = "openid profile email offline_access"
});

// 登录 — 打开系统浏览器
var loginResult = await client.LoginAsync();
if (!loginResult.IsError)
{
    var user = loginResult.User;
    var accessToken = loginResult.AccessToken;
    var idToken = loginResult.IdentityToken;
    var refreshToken = loginResult.RefreshToken;

    // 访问用户声明
    var name = user.FindFirst("name")?.Value;
    var email = user.FindFirst("email")?.Value;

    // 安全持久化刷新令牌用于会话恢复
    if (!string.IsNullOrEmpty(refreshToken))
        await SecureStorage.Default.SetAsync("refresh_token", refreshToken);
}

// 登出 — 清除Auth0会话和存储的令牌
await client.LogoutAsync();
SecureStorage.Default.Remove("refresh_token");

// 应用启动时恢复会话（无需用户交互）
var savedToken = await SecureStorage.Default.GetAsync("refresh_token");
if (!string.IsNullOrEmpty(savedToken))
{
    var refreshResult = await client.RefreshTokenAsync(savedToken);
    if (!refreshResult.IsError)
    {
        var newAccessToken = refreshResult.AccessToken;
        // 若令牌轮转则更新存储的令牌
        if (!string.IsNullOrEmpty(refreshResult.RefreshToken))
            await SecureStorage.Default.SetAsync("refresh_token", refreshResult.RefreshToken);
    }
    else
    {
        // 刷新失败 — 清除令牌并要求重新登录
        SecureStorage.Default.Remove("refresh_token");
    }
}

// 从/userinfo端点获取用户信息
var userInfo = await client.GetUserInfoAsync(accessToken);

// 带额外参数登录（组织、受众、连接）
var orgLogin = await client.LoginAsync(new { organization = "org_abc123" });
var apiLogin = await client.LoginAsync(new { audience = "https://my-api.example.com" });

Android Callback Activity (Required)

Android回调活动（必填）

csharp

[Activity(NoHistory = true, LaunchMode = LaunchMode.SingleTop, Exported = true)]
[IntentFilter(new[] { Intent.ActionView },
    Categories = new[] { Intent.CategoryDefault, Intent.CategoryBrowsable },
    DataScheme = CALLBACK_SCHEME)]
public class WebAuthenticatorActivity : Microsoft.Maui.Authentication.WebAuthenticatorCallbackActivity
{
    const string CALLBACK_SCHEME = "myapp";
}

csharp

[Activity(NoHistory = true, LaunchMode = LaunchMode.SingleTop, Exported = true)]
[IntentFilter(new[] { Intent.ActionView },
    Categories = new[] { Intent.CategoryDefault, Intent.CategoryBrowsable },
    DataScheme = CALLBACK_SCHEME)]
public class WebAuthenticatorActivity : Microsoft.Maui.Authentication.WebAuthenticatorCallbackActivity
{
    const string CALLBACK_SCHEME = "myapp";
}

Windows Platform Setup (Required — Both Steps)

Windows平台设置（必填——两步都要完成）

Step 1: Register protocol in
Platforms/Windows/Package.appxmanifest
:

xml

<Extensions>
  <uap:Extension Category="windows.protocol">
    <uap:Protocol Name="myapp"/>
  </uap:Extension>
</Extensions>

Step 2: Handle redirection in
Platforms/Windows/App.xaml.cs
:

csharp

// In Platforms/Windows/App.xaml.cs
public App()
{
    if (Auth0.OidcClient.Platforms.Windows.Activator.Default.CheckRedirectionActivation())
        return;
    this.InitializeComponent();
}

步骤1：在
Platforms/Windows/Package.appxmanifest
中注册协议：

xml

<Extensions>
  <uap:Extension Category="windows.protocol">
    <uap:Protocol Name="myapp"/>
  </uap:Extension>
</Extensions>

步骤2：在
Platforms/Windows/App.xaml.cs
中处理重定向：

csharp

// 在Platforms/Windows/App.xaml.cs中
public App()
{
    if (Auth0.OidcClient.Platforms.Windows.Activator.Default.CheckRedirectionActivation())
        return;
    this.InitializeComponent();
}

auth0-maui

Original

Translation

auth0-maui Integration

auth0-maui 集成

Prerequisites

前提条件

When NOT to Use

不适用于以下场景

Quick Start Workflow

快速开始流程

Callback URL Configuration

回调URL配置

Done When

完成标准

Detailed Documentation

详细文档

Common Mistakes

常见错误

Testing Notes

测试注意事项

Related Skills

相关技能

Quick Reference

快速参考

Android Callback Activity (Required)

Android回调活动（必填）

Windows Platform Setup (Required — Both Steps)

Windows平台设置（必填——两步都要完成）

References

参考链接