ASP.NET Core Web API

保護されたエンドポイントを持つ ASP.NET Core Web API に Auth0 JWT 認証を追加する

このQuickstartは現在ベータ版です。ぜひご意見をお聞かせください。

AI を使って Auth0 を統合する

Claude Code、Cursor、GitHub Copilot などのAIコーディングアシスタントを使っている場合は、Agent Skills を使って、数分で Auth0認証 を自動的に追加できます。

インストール:

npx skills add auth0/agent-skills --skill auth0

次に、AI アシスタントに次のように依頼します:

Add Auth0 JWT authentication to my ASP.NET Core Web API

AI アシスタントが、Auth0 API の作成、資格情報の取得、Auth0 ASP.NET Core Authentication API SDK のインストール、JWT Bearer認証の設定、保護された API エンドポイントの実装を自動的に行います。Agent Skills の完全なドキュメント →

前提条件: 始める前に、次のものがインストールされていることを確認してください。

• .NET 8.0 SDK 以降
• 使用する IDE (Visual Studio 2022、VS Code、または Rider)

.NET のバージョン互換性: このQuickstartは .NET 8.0 以降で動作します。

​

はじめましょう

このQuickstartでは、ASP.NET Core Web API に Auth0 の JWT 認証を追加する方法を説明します。Auth0 ASP.NET Core API SDK を使用して、保護されたエンドポイントを備えた安全な API を構築します。

1. 新しいプロジェクトを作成する

   このQuickstart用に、新しいASP.NET Core Web APIプロジェクトを作成します

   dotnet new webapi -n Auth0Api
   

   プロジェクトを開く

   cd Auth0Api
   
2. Auth0 SDK をインストール

   dotnet add package Auth0.AspNetCore.Authentication.Api
   
3. Auth0 APIを設定する

   次に、Auth0 テナントで新しい API を作成し、プロジェクトに設定を追加します。

   CLIコマンドを実行して自動的に行う方法と、Auth0 Dashboardから手動で行う方法のいずれかを選択できます：

   CLI

   Auth0 API を作成し、appsettings.json ファイルを更新するには、プロジェクトのルートディレクトリで次のシェルコマンドを実行します。

   Mac/Linux

   AUTH0_API_NAME="My ASP.NET Core API" && \
   AUTH0_API_IDENTIFIER="https://my-api" && \
   brew tap auth0/auth0-cli && \
   brew install auth0 && \
   auth0 login --no-input && \
   auth0 apis create -n "${AUTH0_API_NAME}" -i "${AUTH0_API_IDENTIFIER}" --offline-access --token-lifetime 86400 --signing-alg RS256 --json > auth0-api-details.json && \
   DOMAIN=$(auth0 tenants list --json | jq -r '.[] | select(.active == true) | .name') && \
   AUDIENCE=$(jq -r '.identifier' auth0-api-details.json) && \
   jq --arg domain "$DOMAIN" --arg audience "$AUDIENCE" \
     '.Auth0.Domain = $domain | .Auth0.Audience = $audience' \
     appsettings.json > appsettings.tmp.json && \
   mv appsettings.tmp.json appsettings.json && \
   rm auth0-api-details.json && \
   echo "✅ appsettings.json updated with your Auth0 API details:" && \
   cat appsettings.json
   

   Windows (PowerShell)

   $ApiName = "My ASP.NET Core API"
   $ApiIdentifier = "https://my-api"
   $latestRelease = Invoke-RestMethod -Uri "https://api.github.com/repos/auth0/auth0-cli/releases/latest"
   $latestVersion = $latestRelease.tag_name
   $version = $latestVersion -replace "^v"
   Invoke-WebRequest -Uri "https://github.com/auth0/auth0-cli/releases/download/${latestVersion}/auth0-cli_${version}_Windows_x86_64.zip" -OutFile ".\auth0.zip"
   Expand-Archive ".\auth0.zip" .\
   [System.Environment]::SetEnvironmentVariable('PATH', $Env:PATH + ";${pwd}")
   auth0 login --no-input
   auth0 apis create -n "$ApiName" -i "$ApiIdentifier" --offline-access --token-lifetime 86400 --signing-alg RS256 --json | Set-Content -Path auth0-api-details.json
   $Domain = (auth0 tenants list --json | ConvertFrom-Json | Where-Object { $_.active -eq $true }).name
   $Audience = (Get-Content -Raw auth0-api-details.json | ConvertFrom-Json).identifier
   $Config = Get-Content -Raw appsettings.json | ConvertFrom-Json
   if (-not $Config.Auth0) { $Config | Add-Member -MemberType NoteProperty -Name Auth0 -Value @{} }
   $Config.Auth0.Domain = $Domain
   $Config.Auth0.Audience = $Audience
   $Config | ConvertTo-Json -Depth 10 | Set-Content appsettings.json
   Remove-Item auth0-api-details.json
   Write-Output "✅ appsettings.json updated with your Auth0 API details:"
   Get-Content appsettings.json
   

   Auth0 Dashboard

   始める前に、appsettings.json ファイルに Auth0 の設定を追加してください

   appsettings.json

   {
     "Logging": {
       "LogLevel": {
         "Default": "Information",
         "Microsoft.AspNetCore": "Warning"
       }
     },
     "AllowedHosts": "*",
     "Auth0": {
       "Domain": "YOUR_AUTH0_DOMAIN",
       "Audience": "YOUR_AUTH0_API_IDENTIFIER"
     }
   }
   

   1. Auth0 Dashboard → アプリケーション → APIs を開きます
   2. Create API をクリックします
   3. API の詳細を入力します。
      • Name: My ASP.NET Core API
      • Identifier: https://my-api (これが Audience になります)
      • Signing Algorithm: RS256
   4. Create をクリックします
   5. appsettings.json の YOUR_AUTH0_DOMAIN を、Test タブの Domain に置き換えます (例: your-tenant.auth0.com)
   6. appsettings.json の YOUR_AUTH0_API_IDENTIFIER を、Identifier に置き換えます (例: https://my-api)

   Domain には https:// を含めず、ドメイン名のみを使用してください (例: your-tenant.auth0.com) 。

   Audience (API 識別子) は API の一意の識別子であり、有効な URI であれば任意の値を指定できます。公開アクセス可能な URL である必要はありません。

4. 認証を設定する

   Program.cs の内容全体を、以下のコードに置き換えます:

   Program.cs

   using Auth0.AspNetCore.Authentication.Api;
   using Microsoft.AspNetCore.Authentication.JwtBearer;
   
   var builder = WebApplication.CreateBuilder(args);
   
   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();
   
   if (!app.Environment.IsDevelopment())
   {
       app.UseHttpsRedirection();
   }
   
   app.UseAuthentication();
   app.UseAuthorization();
   
   app.Run();
   
5. 公開エンドポイントと保護エンドポイントを作成する

   認証をテストするエンドポイントを追加します。app.Run() の前に、次のコードを Program.cs に追加します：

   Program.cs

   // 公開エンドポイント - 認証不要
   app.MapGet("/api/public", () => 
       Results.Ok(new { Message = "This endpoint is public" }))
       .WithName("GetPublic");
   
   // 保護されたエンドポイント - 認証が必要
   app.MapGet("/api/private", () => 
       Results.Ok(new { Message = "This endpoint requires authentication" }))
       .RequireAuthorization()
       .WithName("GetPrivate");
   
6. APIを起動する

   dotnet run
   

   API は現在 https://localhost:7190 で実行中です (またはそれに近い URL です。正確な URL はコンソール出力で確認してください) 。

確認

これで、localhost 上で動作する Auth0 で保護された完全な機能を備えた API が利用できるようになっているはずです

---

​

高度な使い方

保護された API の呼び出し

アクセストークンを使って、保護されたエンドポイントをテストします。

1. クライアント認証情報フローを使用して Auth0 からアクセストークンを取得します:

curl --request POST \
  --url https://YOUR_DOMAIN/oauth/token \
  --header 'content-type: application/json' \
  --data '{"client_id":"YOUR_CLIENT_ID","client_secret":"YOUR_CLIENT_SECRET","audience":"YOUR_AUDIENCE","grant_type":"client_credentials"}'

YOUR_CLIENT_ID と YOUR_CLIENT_SECRET を取得するには、Auth0 Dashboard で Machine to Machine Application を作成し、そのアプリケーションを API で認可してください。

2. 公開エンドポイントをテストします (200 OK が返されるはずです) :

curl https://localhost:7190/api/public

3. 認証なしで保護されたエンドポイントをテストします (401 Unauthorized が返されるはずです) :

curl https://localhost:7190/api/private

4. トークンを使って保護されたエンドポイントを呼び出します:

curl https://localhost:7190/api/private \
  --header 'Authorization: Bearer YOUR_ACCESS_TOKEN'

コントローラーベースのエンドポイントを使用する

より大規模な API では、minimal API エンドポイントではなくコントローラーを使用します。

1. コントローラーのサポートを追加します:

Program.cs

builder.Services.AddControllers();

var app = builder.Build();

if (!app.Environment.IsDevelopment())
{
    app.UseHttpsRedirection();
}

app.UseAuthentication();
app.UseAuthorization();

app.MapControllers();

app.Run();

2. コントローラーを作成します:

Controllers/MessagesController.cs を作成します:

Controllers/MessagesController.cs

using Microsoft.AspNetCore.Authorization;
using Microsoft.AspNetCore.Mvc;

namespace Auth0Api.Controllers;

[ApiController]
[Route("api/[controller]")]
public class MessagesController : ControllerBase
{
    [HttpGet]
    public IActionResult GetPublic()
    {
        return Ok(new { Message = "This endpoint is public" });
    }

    [Authorize]
    [HttpGet("private")]
    public IActionResult GetPrivate()
    {
        var userId = User.FindFirst("sub")?.Value;
        return Ok(new { Message = "This endpoint is protected", UserId = userId });
    }

    [Authorize(Policy = "read:messages")]
    [HttpGet("messages")]
    public IActionResult GetMessages()
    {
        return Ok(new { Messages = new[] { "Message 1", "Message 2" } });
    }
}

スコープベースの認可でルートを保護する

アクセストークン内の特定のスコープに基づいてエンドポイントを保護します。

1. Auth0 API でスコープを定義します:

Auth0 Dashboard → APIs → Your API → Permissions で、スコープを追加します:

• read:messages - メッセージの読み取り
• write:messages - メッセージの書き込み

2. 認可ポリシーを設定します:

Program.cs

builder.Services.AddAuthorization(options =>
{
    options.AddPolicy("read:messages", policy =>
        policy.RequireClaim("scope", "read:messages"));
    
    options.AddPolicy("write:messages", policy =>
        policy.RequireClaim("scope", "write:messages"));
});

3. エンドポイントにポリシーを適用します:

app.MapGet("/api/messages", () => 
    Results.Ok(new { Messages = new[] { "Message 1", "Message 2" } }))
    .RequireAuthorization("read:messages");

app.MapPost("/api/messages", () => 
    Results.Created("/api/messages/1", new { Id = 1, Text = "New message" }))
    .RequireAuthorization("write:messages");

アクセストークンをリクエストするときは、必要なスコープを含めます:

curl --request POST \
  --url https://YOUR_DOMAIN/oauth/token \
  --header 'content-type: application/json' \
  --data '{"client_id":"YOUR_CLIENT_ID","client_secret":"YOUR_CLIENT_SECRET","audience":"YOUR_AUDIENCE","grant_type":"client_credentials","scope":"read:messages write:messages"}'

Enhanced Security のために DPoP を使用する

DPoP (Demonstration of Proof-of-Possession) はアクセストークンを暗号鍵に結び付け、トークンの盗難やリプレイ攻撃を防ぎます。

DPoP サポートを有効にする:

Program.cs

builder.Services.AddAuth0ApiAuthentication(options =>
{
    options.Domain = builder.Configuration["Auth0:Domain"];
    options.JwtBearerOptions = new JwtBearerOptions
    {
        Audience = builder.Configuration["Auth0:Audience"]
    };
}).WithDPoP();  // デフォルト設定で DPoP を有効化

DPoP モード:

DPoP と Bearer トークンの両方を受け入れる (デフォルト) :

using Auth0.AspNetCore.Authentication.Api.DPoP;

.WithDPoP(dpopOptions =>
{
    dpopOptions.Mode = DPoPModes.Allowed;
});

DPoP トークンのみを受け入れ、Bearer トークンを拒否する:

using Auth0.AspNetCore.Authentication.Api.DPoP;

.WithDPoP(dpopOptions =>
{
    dpopOptions.Mode = DPoPModes.Required;
});

時刻のバリデーションパラメータを設定する:

.WithDPoP(dpopOptions =>
{
    dpopOptions.Mode = DPoPModes.Allowed;
    dpopOptions.IatOffset = 300;  // 最大 5 分前までの DPoP proof を許可
    dpopOptions.Leeway = 30;      // 30 秒のクロックスキューを許容
});

DPoP の詳細については、Auth0 DPoPドキュメント を参照してください。

カスタム認可ポリシーを実装する

複雑な要件に対応するための、再利用可能な認可ポリシーを作成します。

1. カスタム要件を作成する:

Authorization/HasScopeRequirement.cs

using Microsoft.AspNetCore.Authorization;

namespace Auth0Api.Authorization;

public class HasScopeRequirement : IAuthorizationRequirement
{
    public string Scope { get; }
    public string Issuer { get; }

    public HasScopeRequirement(string scope, string issuer)
    {
        Scope = scope;
        Issuer = issuer;
    }
}

2. ハンドラーを作成する:

Authorization/HasScopeHandler.cs

using Microsoft.AspNetCore.Authorization;

namespace Auth0Api.Authorization;

public class HasScopeHandler : AuthorizationHandler<HasScopeRequirement>
{
    protected override Task HandleRequirementAsync(
        AuthorizationHandlerContext context,
        HasScopeRequirement requirement)
    {
        if (!context.User.HasClaim(c => c.Type == "scope" && c.Issuer == requirement.Issuer))
        {
            return Task.CompletedTask;
        }

        var scopes = context.User
            .FindFirst(c => c.Type == "scope" && c.Issuer == requirement.Issuer)?
            .Value.Split(' ');

        if (scopes?.Any(s => s == requirement.Scope) == true)
        {
            context.Succeed(requirement);
        }

        return Task.CompletedTask;
    }
}

3. ポリシーを登録して使用する:

Program.cs

using Auth0Api.Authorization;

var builder = WebApplication.CreateBuilder(args);

var domain = $"https://{builder.Configuration["Auth0:Domain"]}";

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

builder.Services.AddAuthorization(options =>
{
    options.AddPolicy("read:messages", policy =>
        policy.Requirements.Add(new HasScopeRequirement("read:messages", domain)));
});

builder.Services.AddSingleton<IAuthorizationHandler, HasScopeHandler>();

var app = builder.Build();
// ... 残りの構成

ユーザー情報へのアクセス

認証されたトークンからユーザー情報を取得します。

app.MapGet("/api/user-info", (HttpContext context) =>
{
    var userId = context.User.FindFirst("sub")?.Value;
    var email = context.User.FindFirst("email")?.Value;
    var name = context.User.FindFirst("name")?.Value;
    var scopes = context.User.FindAll("scope")
        .SelectMany(c => c.Value.Split(' '))
        .Distinct();

    return Results.Ok(new
    {
        UserId = userId,
        Email = email,
        Name = name,
        Scopes = scopes
    });
})
.RequireAuthorization();

カスタムトークン検証

特定の要件に応じて、JWT トークンのバリデーションパラメータをカスタマイズします。

Program.cs

using Microsoft.IdentityModel.Tokens;
using System.Security.Claims;

builder.Services.AddAuth0ApiAuthentication(options =>
{
    options.Domain = builder.Configuration["Auth0:Domain"];
    options.JwtBearerOptions = new JwtBearerOptions
    {
        Audience = builder.Configuration["Auth0:Audience"],
        
        TokenValidationParameters = new TokenValidationParameters
        {
            ValidateIssuerSigningKey = true,
            ValidateIssuer = true,
            ValidateAudience = true,
            ValidateLifetime = true,
            ClockSkew = TimeSpan.FromMinutes(5),
            NameClaimType = ClaimTypes.NameIdentifier,
            RoleClaimType = "https://my-app.com/roles"
        },
        
        Events = new JwtBearerEvents
        {
            OnAuthenticationFailed = context =>
            {
                Console.WriteLine($"Authentication failed: {context.Exception.Message}");
                return Task.CompletedTask;
            },
            
            OnTokenValidated = context =>
            {
                var userId = context.Principal?.FindFirst("sub")?.Value;
                Console.WriteLine($"Token validated for user: {userId}");
                return Task.CompletedTask;
            }
        }
    };
});

---

​

追加リソース

SDKドキュメント

SDKの完全なドキュメントとAPIリファレンス

移行ガイド

JWT Bearer認証からの移行

コード例

豊富なコード例と実装パターン

DPoPドキュメント

Proof-of-Possessionセキュリティについて詳しく知る

Token Best Practices

トークンのセキュリティに関するベストプラクティス

コミュニティフォーラム

Auth0 Communityでサポートを受ける

---

​

よくある問題

401 Unauthorized - 無効な audience

問題: audience の不一致により、トークン検証 が失敗します。

解決策: appsettings.json の Audience が、Auth0 API の API 識別子と完全に一致していることを確認してください。token 内の audience claim もこの値と一致している必要があります。

{
  "Auth0": {
    "Audience": "https://my-api"  // Auth0 API 識別子と一致している必要があります
  }
}

401 Unauthorized - 無効な 発行者

問題: 発行者エラーにより、トークン検証 が失敗します。

解決策: Domain が正しく、https:// を含んでいないことを確認してください。library は https://{Domain} として authority を自動的に構築します。

{
  "Auth0": {
    "Domain": "your-tenant.auth0.com"  // https:// は含めません
  }
}

Configuration の値が見つかりません

問題: ArgumentNullException: Value cannot be null. (Parameter 'Domain') などのエラーが発生します。

解決策: appsettings.json に、Domain と audience の値を含む Auth0 セクションがあることを確認してください。Configuration が正しく読み込まれていることも確認してください。

builder.Services.AddAuth0ApiAuthentication(options =>
{
    options.Domain = builder.Configuration["Auth0:Domain"]
        ?? throw new InvalidOperationException("Auth0:Domain is required");
    options.JwtBearerOptions = new JwtBearerOptions
    {
        Audience = builder.Configuration["Auth0:Audience"]
            ?? throw new InvalidOperationException("Auth0:Audience is required")
    };
});

開発環境での HTTPS 証明書エラー

問題: ローカル実行時に SSL/TLS 証明書エラーが発生します。

解決策: 開発用証明書を信頼するよう設定してください。

dotnet dev-certs https --trust

または、新しい証明書を生成してください。

dotnet dev-certs https --clean
dotnet dev-certs https --trust

ミドルウェアの順序に関する問題

問題: 設定が正しいにもかかわらず、authentication が機能しません。

解決策: ミドルウェアの順序が正しいことを確認してください。UseAuthentication() は UseAuthorization() より前に配置する必要があります。

app.UseAuthentication();  // UseAuthorization より前である必要があります
app.UseAuthorization();
app.MapControllers();

認可ポリシー で スコープ が機能しない

問題: スコープ ベースの 認可ポリシー が常に失敗します。

解決策: access token に必要な スコープ が含まれていることを確認してください。token を request する際は、スコープ を指定してください。

curl --request POST \
  --url https://YOUR_DOMAIN/oauth/token \
  --data '{"client_id":"...","client_secret":"...","audience":"...","grant_type":"client_credentials","scope":"read:messages write:messages"}'

また、スコープ が Auth0 API の設定で定義されていることも確認してください (Auth0 Dashboard → APIs → Your API → Permissions) 。

---

​

サンプルアプリケーション

すべての機能を網羅した完全なサンプルアプリケーションを、SDK のリポジトリで利用できます。

プレイグラウンドアプリケーション

公開エンドポイントと保護されたエンドポイント、DPoP のサポート、Swagger UI 連携、Postman コレクションが含まれています

クローンして実行します。

git clone https://github.com/auth0/aspnetcore-api.git
cd aspnetcore-api/Auth0.AspNetCore.Authentication.Api.Playground
# appsettings.jsonをAuth0の設定で更新する
dotnet run