auth0-aspnetcore-api

Auth0 ASP.NET Core Web API 集成

使用 Auth0.AspNetCore.Authentication.Api，通过 JWT 访问令牌验证保护 ASP.NET Core Web API 端点。

---

前提条件

• .NET 8.0 SDK 或更高版本
• 已配置 Auth0 API（不是 Application，必须是 API 资源）
• 如果尚未设置 Auth0，请先使用 auth0-quickstart 技能

不适用场景

• 服务器渲染的 Web 应用 - MVC/Razor Pages 应用请使用基于会话的身份验证（Auth0.AspNetCore.Authentication）
• 单页应用 - 客户端身份验证请使用 auth0-react、auth0-vue 或 auth0-angular
• 移动应用 - React Native/Expo 请使用 auth0-react-native
• Blazor WebAssembly - 需要采用不同的身份验证方式（OIDC 客户端身份验证）

---

快速入门工作流

1. 安装 SDK

dotnet add package Auth0.AspNetCore.Authentication.Api

2. 创建 Auth0 API

你需要在 Auth0 中创建一个 API（而不是 Application）。

停止 — 继续之前先询问用户。

仅询问以下问题，并等待用户回答后再进行其他操作：

"你希望如何创建 Auth0 API 资源？

1. 自动 — 我会运行 Auth0 CLI 脚本来创建资源，并自动将确切的值写入 appsettings.json。
2. 手动 — 你在 Auth0 Dashboard 中自行创建 API（或通过 auth0 apis create 创建），并向我提供 Domain 和 Audience。

你更倾向于哪种方式？（1 = 自动 / 2 = 手动）"

在用户回答之前，不要继续任何设置步骤。不要默认选择手动方式。

如果用户选择自动方式，请按照设置指南中的完整 CLI 脚本操作。自动方式会为你写入 appsettings.json — 跳过下面的步骤 3，直接继续步骤 4。

如果用户选择手动方式，请按照设置指南（手动设置部分）中的完整说明操作，包括 User Secrets 和环境变量选项。然后继续下面的步骤 3。

手动创建 API 的快速参考：

# Using Auth0 CLI
auth0 apis create \
  --name "My ASP.NET Core API" \
  --identifier https://my-api.example.com

或者在 Auth0 Dashboard → Applications → APIs 中手动创建

3. 配置 appsettings.json

{
  "Auth0": {
    "Domain": "your-tenant.auth0.com",
    "Audience": "https://my-api.example.com"
  }
}

重要： Domain 不能包含 https://。该库会自动构造 authority URL。

4. 配置 Program.cs

var builder = WebApplication.CreateBuilder(args);

// Register Auth0 JWT validation
builder.Services.AddAuth0ApiAuthentication(options =>
{
    options.Domain = builder.Configuration["Auth0:Domain"];
    options.JwtBearerOptions = new JwtBearerOptions
    {
        Audience = builder.Configuration["Auth0:Audience"]
    };
});

builder.Services.AddAuthorization();

var app = builder.Build();

// Middleware order matters: authentication before authorization
app.UseAuthentication();
app.UseAuthorization();

// Add your endpoints here (see Step 5)
app.MapGet("/api/public", () => Results.Ok(new { message = "Public" }));

app.Run();

5. 保护端点

Minimal API：

// Public endpoint - no authentication
app.MapGet("/api/public", () => Results.Ok(new { message = "Hello from a public endpoint!" }));

// Protected endpoint - requires valid JWT
app.MapGet("/api/private", (HttpContext ctx) =>
{
    var userId = ctx.User.FindFirst("sub")?.Value;
    return Results.Ok(new { message = "Hello from a protected endpoint!", userId });
}).RequireAuthorization();

基于控制器：

[ApiController]
[Route("api")]
public class MessagesController : ControllerBase
{
    [HttpGet("public")]
    public IActionResult Public() =>
        Ok(new { message = "Hello from a public endpoint!" });

    [Authorize]
    [HttpGet("private")]
    public IActionResult Private() =>
        Ok(new { message = "Hello from a protected endpoint!", userId = User.FindFirst("sub")?.Value });
}

6. 测试 API

测试公开端点：

curl http://localhost:5000/api/public

测试受保护端点（需要访问令牌）：

curl http://localhost:5000/api/private \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

通过 Client Credentials 流程或 Auth0 Dashboard → APIs → Test 选项卡获取测试令牌。

---

常见错误

错误	修正方法
Domain 包含 https://	仅使用 your-tenant.auth0.com 格式 — 不带方案前缀
Audience 与 API Identifier 不匹配	必须与 Auth0 Dashboard 中设置的 API Identifier 完全一致
在 Auth0 中创建了 Application，而不是 API	必须在 Auth0 Dashboard → Applications → APIs 中创建 API 资源
中间件顺序错误	UseAuthentication() 必须位于 UseAuthorization() 之前
使用了 ID token，而不是 access token	API 身份验证必须使用 access token，而不是 ID token
本地 HTTPS 证书错误	运行 dotnet dev-certs https --trust

---

基于 Scope 的授权

有关如何定义和强制执行 scope 策略，请参阅集成指南。

---

DPoP 支持

内置符合 RFC 9449 的持有证明令牌绑定。有关配置，请参阅集成指南。

---

相关技能

• auth0-quickstart - Auth0 基础设置
• auth0-mfa - 添加多重身份验证
• auth0-cli - 在终端中管理 Auth0 资源

---

快速参考

配置选项：

• options.Domain - Auth0 租户域名，不带 https:// 前缀（必需）
• options.JwtBearerOptions.Audience - Auth0 API 设置中的 API 标识符（必需）
• options.JwtBearerOptions - 完全访问底层 Microsoft JWT Bearer 选项

用户声明：

• ctx.User.FindFirst("sub")?.Value - 用户 ID（主体）
• ctx.User.FindFirst("scope")?.Value - 以空格分隔的作用域
• ctx.User.FindAll("scope") - 所有作用域声明

常见用例：

• 保护 Minimal API 路由 → .RequireAuthorization()（参见步骤 5）
• 保护控制器操作 → [Authorize] 特性（参见步骤 5）
• 作用域强制执行 → 集成指南
• DPoP 令牌绑定 → 集成指南
• 高级 JWT Bearer 配置 → API 参考

---

详细文档

• 设置指南 - Auth0 CLI 设置、环境配置
• 集成指南 - 作用域策略、DPoP、控制器模式、错误处理
• API 参考 - 完整的配置选项和扩展方法

---

参考资料

• Auth0 ASP.NET Core Web API 快速入门
• SDK GitHub 仓库
• API 文档
• 访问令牌指南