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（または auth0 apis create）で API を作成し、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 で API ではなく Application を作成した	Auth0 Dashboard → Applications → APIs で API リソースを作成する必要があります
ミドルウェアの順序が間違っている	UseAuthentication() は UseAuthorization() より前に呼び出す必要があります
アクセストークンではなく ID トークンを使用している	API 認証には ID トークンではなく、アクセストークンを使用する必要があります
ローカルで HTTPS 証明書エラーが発生する	dotnet dev-certs https --trust を実行してください

---

スコープベースの認可

スコープポリシーの定義と適用については、連携ガイドを参照してください。

---

DPoP のサポート

RFC 9449 に準拠した、組み込みの Proof-of-Possession トークンバインディングです。構成については連携ガイドを参照してください。

---

関連スキル

• 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 ドキュメント
• アクセストークンガイド