ASP.NET Core で JWT ベアラー認証を構成する

2025-06-21

JWT (JSON Web トークン) ベアラー認証は、一般的に API に使用されます。 ID プロバイダーは、cookie 認証と同様に動作しますが、認証が成功すると JWT またはトークンを発行します。これらのトークンは、発行ドメインにのみ送り返される Cookie とは異なり、他のサーバーに送信して認証に使用することができます。 JWT は、API リソースまたはクライアントの情報をカプセル化する自己完結型トークンです。 JWT を要求したクライアントは、Authorization ヘッダーとベアラートークンを使用して API リソースからデータを要求できます。

JWT ベアラー認証では、次の機能が提供されます。

認証: JwtBearerHandlerを使用する場合、ベアラートークンは認証に不可欠です。 JwtBearerHandler はトークンを検証し、その要求からユーザーの ID を抽出します。
承認: ベアラートークンは、 cookieと同様に、ユーザーまたはアプリケーションのアクセス許可を表すクレームのコレクションを提供することで承認を有効にします。
委任された承認: アプリケーション全体のアクセストークンではなく、ユーザー固有のアクセストークンを使用して API 間で認証を行う場合、このプロセスは 委任された承認と呼ばれます。

JWT ベアラー認証の概要については、JSON Web トークンに関するページを参照してください。サンプルコードを表示またはダウンロードする

この記事では、次の領域について説明します。

トークンの種類
JWT トークンを使用して API をセキュリティで保護する
OIDC/OAuth はこれにどう適合するのか
JWT ベアラートークン認証の実装
JWT を作成するための推奨される方法

トークンの種類

さまざまな種類のトークンと形式があります。テスト以外の目的で、独自のアクセストークンまたは ID トークンを生成することは推奨されません。確立された標準に準拠していない自己作成トークンの場合、次が該当します。

セキュリティの脆弱性につながる可能性があります。
クローズドシステムにのみ適しています。

API アクセスを目的としたアクセストークンを作成するには、 OpenID Connect 1.0 または OAuth 標準を使用することをお勧めします。

アクセストークン

アクセストークン:

API を実装するサーバーに要求を行うためにクライアントアプリによって使用される文字列です。
形式は異なる場合があります。 API によってトークンの形式が異なる場合があります。
暗号化できます。
アクセストークンを保持している Web クライアントまたは UI アプリによって読み取られたり解釈されたりしてはなりません。
API に要求することのみを目的としています。
通常、ベアラートークンとして Authorization 要求ヘッダーの API に送信されます。

OAuth 2.0 承認フレームワークを参照してください

アプリケーションアクセストークンと委任されたアクセストークン

アクセストークンには、 アプリケーションアクセストークン または 委任されたアクセストークンのいずれかを指定できます。トークンにはさまざまな要求が含まれ、異なる方法で管理および格納されます。 通常、アプリケーションアクセストークンは有効期限が切れるまでアプリに 1 回格納されますが、委任されたアクセストークンはユーザーごとに、cookieまたはセキュリティで保護されたサーバーキャッシュに格納されます。

ユーザーが関係する場合は常に、委任されたユーザーアクセストークンを使用することをお勧めします。ダウンストリーム API は認証済みユーザーに代わって、委任されたユーザーアクセストークンを要求できます。

センダーの制約付きアクセストークン

アクセストークンは、リソースにアクセスするためのベアラートークンまたは送信者の制約付きトークンとして使用できます。センダーの制約付きトークンでは、要求元クライアントはトークンを使用するために秘密キーの所有を証明する必要があります。秘密キーの所有を証明することで、トークンが単独で使用されないことが保証されます。センダーの制約付きトークンは、次の 2 つの方法で実装できます。

ID トークン

ID トークンは、ユーザーが認証に成功したことを確認するセキュリティトークンです。トークンを使用すると、クライアントはユーザーの ID を確認できます。 JWT トークンサーバーは、ユーザー情報を持つ要求を含んだ ID トークンを発行します。 ID トークンは常に JWT 形式です。

API へのアクセスには ID トークンを使用 しないでください 。

その他のトークン

OpenID Connect および OAuth 標準で指定されているアクセストークンや ID トークンなど、さまざまな種類のトークンがあります。更新トークンを使用すると、ユーザーを再認証せずに UI アプリを更新できます。 OAuth JAR トークンは、承認要求を安全に送信できます。検証可能な資格情報フローでは、資格情報の発行または検証に JWT の種類が使用されます。仕様に従ってトークンを使用することが重要です。詳細については、この記事で後述する標準リンクを参照してください。

JWT トークンを使用して API をセキュリティで保護する

API 承認に JWT アクセストークンを使用する場合、API は指定されたトークンに基づいてアクセスを許可または拒否します。要求が承認されていない場合は、401 応答または 403 応答が返されます。 API は、新しいトークンを取得したり追加のアクセス許可を要求したりするために、ユーザーを ID プロバイダーにリダイレクトすべきではありません。 API を使用するアプリは、適切なトークンを取得する必要があります。これにより、API (承認) と使用するクライアントアプリ (認証) の間で懸念事項が明確に分離されます。

メモ

HTTP では、承認されていないクライアントにリソースの存在に関する情報が漏洩しないように、404 を返すこともできます。

401 権限がありません

401 未承認の応答は、指定されたアクセストークンが必要な標準を満たしていないことを示します。これには、次のような理由がいくつか考えられます。

無効な署名: トークンの署名が一致せず、改ざんの可能性が示唆されます。
有効期限: トークンの有効期限が切れており、有効ではなくなりました。
不正な要求: 対象ユーザー (aud) や発行者 (iss) など、トークン内の重要な要求が見つからないか無効です。

メモ

HTTP セマンティクス RFC 9110 から: 401 応答を生成するサーバーは、ターゲットリソースに適用できる少なくとも 1 つのチャレンジを含む WWW-Authenticate ヘッダーフィールド (セクション 11.6.1) を送信する必要があります。

OAuth 仕様では、必要な要求とその検証に関する詳細なガイドラインが提供されます。

403 許可されていません

通常、403 Forbidden 応答は、認証されたユーザーに、要求されたリソースにアクセスするために必要なアクセス許可がないことを示します。これは認証の問題 (無効なトークンなど) とは異なり、アクセストークン内の標準要求とは無関係です。

ASP.NET Core では、次を使用して承認を適用できます。

要件とポリシー: カスタム要件 ("管理者である必要があります" など) を定義し、ポリシーに関連付けます。ロールベースの承認: "管理者"、"エディター" などのロールにユーザーを割り当て、それらのロールに基づいてアクセスを制限します。

ベアラートークンの使用時に OIDC や OAuth が果たす役割とは

API が承認に JWT アクセストークンを使用する場合、API はアクセストークンのみを検証し、トークンの取得方法は検証しません。

OpenID Connect (OIDC) と OAuth 2.0 では、トークン取得用のセキュリティで保護された標準化フレームワークを使用できます。トークンの取得は、アプリの種類によって異なります。セキュリティで保護されたトークンの取得は複雑なため、次の標準に依存することを強くお勧めします。

ユーザーとアプリケーションの代わりに動作するアプリの場合: OIDC が優先される選択肢であり、委任されたユーザーアクセスを有効にします。 Web アプリでは、セキュリティを強化するために、 Proof Key for Code Exchange (PKCE) を使用した機密コードフローが推奨されます。
- 呼び出し元のアプリがサーバー側 OIDC 認証を使用する ASP.NET Core アプリの場合は、 SaveTokens オプションを使用してアクセストークンを cookie に格納し、後で HttpContext.GetTokenAsync("access_token") 経由で使用できます。
アプリにユーザーがいない場合: OAuth 2.0 クライアント資格情報フローは、アプリケーションアクセストークンの取得に適しています。

JWT ベアラートークン認証の実装

Microsoft.AspNetCore.Authentication.JwtBearer Nuget パッケージを使用して、JWT ベアラートークンを検証できます。

JWT ベアラートークンは、API で完全に検証する必要があります。次を検証する必要があります。

信頼と整合性を確保するための署名。これにより、指定されたセキュリティで保護されたトークンサービスによってトークンが作成され、改ざんされていないことが保証されます。
有効な値を持つ発行者クレーム。
有効な値を持つオーディエンスクレーム。
トークンの有効期限。

OAuth 2.0 アクセストークンには、iss、exp、aud、sub、client_id、iat、jti の各要求が必要です。

これらの要求または値のいずれかが正しくない場合、API は 401 応答を返します。

JWT ベアラートークンの基本的な検証

AddJwtBearer の基本的な実装では、対象ユーザーと発行者のみを検証できます。トークンを信頼できること、改ざんされていないことを確認する必要があります。

builder.Services.AddAuthentication(JwtBearerDefaults.AuthenticationScheme)
.AddJwtBearer(jwtOptions =>
{
	jwtOptions.Authority = "https://{--your-authority--}";
	jwtOptions.Audience = "https://{--your-audience--}";
});

JWT ベアラートークンの明示的な検証

AddJwtBearer メソッドは、複数の構成を提供します。セキュリティで保護されたトークンプロバイダーの一部では、標準以外のメタデータアドレスが使用され、パラメーターを明示的に設定できます。 API は、複数の発行者または対象ユーザーを受け入れることができます。

パラメーターを明示的に定義する必要はありません。定義は、アクセストークン要求の値と、アクセストークンの検証に使用されるセキュリティで保護されたトークンサーバーによって異なります。可能であれば、既定値を使用する必要があります。

マッピング要求 MapInboundClaims の詳細を参照してください。

builder.Services.AddAuthentication()
.AddJwtBearer("some-scheme", jwtOptions =>
{
	jwtOptions.MetadataAddress = builder.Configuration["Api:MetadataAddress"];
	// Optional if the MetadataAddress is specified
	jwtOptions.Authority = builder.Configuration["Api:Authority"];
	jwtOptions.Audience = builder.Configuration["Api:Audience"];
	jwtOptions.TokenValidationParameters = new TokenValidationParameters
	{
		ValidateIssuer = true,
		ValidateAudience = true,
		ValidateIssuerSigningKey = true,
		ValidAudiences = builder.Configuration.GetSection("Api:ValidAudiences").Get<string[]>(),
		ValidIssuers = builder.Configuration.GetSection("Api:ValidIssuers").Get<string[]>()
	};

	jwtOptions.MapInboundClaims = false;
});

複数のスキームを持つ JWT

API は、多くの場合、さまざまな発行者からのアクセストークンに対応する必要があります。 API で複数のトークン発行者をサポートするには、次の方法があります。

個別の API: 発行者ごとに専用の認証スキームを使用して個別の API を作成します。
AddPolicyScheme この方法では、複数の認証スキームを定義し、トークンのプロパティ (発行者、クレームなど) に基づいて適切なスキームを選択するロジックを実装できます。このアプローチにより、1 つの API 内で柔軟性が向上します。

ベアラー認証の強制

SetDefaultPolicy を使用すると、[Authorize] 属性を持たないエンドポイントにも、すべての要求に対して認証を要求できます。 SetDefaultPolicy は、[Authorize] 属性を持つエンドポイントに使用されるポリシーを構成し、既に既定で認証済みユーザーを要求するように設定されています。詳細については、「認証されたユーザーを要求する」を参照してください。

var requireAuthPolicy = new AuthorizationPolicyBuilder()
	.RequireAuthenticatedUser()
	.Build();

builder.Services.AddAuthorizationBuilder()
	.SetDefaultPolicy(requireAuthPolicy);

Authorize 属性を使用して認証を強制することもできます。複数のスキームを使用する場合は、通常、ベアラースキームを既定の認証スキームとして設定するか、[Authorize(AuthenticationSchemes = JwtBearerDefaults.AuthenticationScheme]) を使用して指定する必要があります。

コントローラーでの承認:

[Authorize]
[ApiController]
[Route("[controller]")]
public class WeatherForecastController : ControllerBase
{

最小 API での承認:

app.MapGet("/hello", [Authorize] () => "Hi");

JWT を作成するための推奨される方法

アクセストークンの不適切な取り扱い (脆弱な認証や、脆弱なクライアント側ストレージにトークンを保存することなど) は、重大なセキュリティの脆弱性につながる可能性があります。例えば、アクセストークンをローカルストレージ、セッションストレージ、または Web worker を使用してブラウザーに直接格納することです。次のセクションでは、アクセストークンを使用および作成するアプリのベストプラクティスについて説明します。

標準を使用する

アクセストークンの作成時は必ず、OpenID Connect や OAuth などの標準を使用する必要があります。この記事で説明されているセキュリティ上の予防措置を遵守せずに、運用アプリでアクセストークンを作成しないでください。アクセストークンの作成は、テストシナリオに限定する必要があります。

非対称キーを使用する

アクセストークンを作成するときは、必ず非対称キーを使用する必要があります。公開キーは既知のエンドポイントで使用でき、API クライアントは公開キーを使用してアクセストークンの署名を検証できます。

ユーザー名/パスワード要求からアクセストークンを作成しない

ユーザー名/パスワード要求からアクセストークンを作成しないでください。ユーザー名/パスワード要求は、なりすましやフィッシング攻撃に対して脆弱であり、認証されません。アクセストークンは、OpenID Connect フローまたは OAuth 標準フローのみを使用して作成する必要があります。これらの標準から逸脱すると、アプリが安全でなくなる可能性があります。

Cookie を使用する

セキュリティで保護された Web アプリの場合、信頼されたサーバーにアクセストークンを格納するにはバックエンドが必要です。クライアントブラウザーで共有されるのは、セキュリティで保護された HTTP 専用 cookie のみです。 ASP.NET Core Web アプリでこれを行う方法については、 OIDC 認証のドキュメントを参照してください。

ダウンストリームAPI

API では時折、呼び出し元アプリの認証済みユーザーの代わりにダウンストリーム API からユーザーデータにアクセスする必要があります。 OAuth クライアント資格情報フローの実装はオプションですが、2 つの API アプリ間の完全な信頼が必要になります。より安全なアプローチは、委任されたユーザーアクセストークンを使用するゼロトラスト戦略を採用することです。この方法の特徴は次のとおりです。

特定のユーザーに必要なアクセス許可のみを API に付与することでセキュリティを強化します。
アプリと API を呼び出すユーザーに新しいアクセストークンを API で作成する必要があります。

委任されたユーザーアクセストークンを使用してゼロトラスト戦略を実装するには、いくつかの方法があります。

OAuth 2.0 Token Exchange を使用して新しい委任されたアクセストークンを要求する

これは、この要件を実装する良い方法ですが、OAuth フローを実装する必要がある場合は複雑です。

OAuth 2.0 トークン交換を参照してください

フローの代わりに Microsoft Identity Web を使用して、新しい委任されたアクセストークンを要求する

Microsoft Identity Web 認証ライブラリの使用は、最も簡単で安全な方法です。 Microsoft Entra ID、Microsoft Entra External ID でのみ機能します。

詳細については、「Microsoft ID プラットフォームと OAuth 2.0 On-Behalf-Of フローを参照してください。

API に送信されたのと同じ委任されたアクセストークンを使用する

このアプローチを実装することは難しくありませんが、アクセストークンはすべてのダウンストリーム API にアクセスできます。この実装には、Yarp リバースプロキシを使用できます。

OAuth クライアント資格情報フローを使用し、アプリケーションアクセストークンを使用する

これは簡単に実装できますが、クライアントアプリケーションには、委任されたアクセストークンではなく、完全なアプリケーションアクセスが含まれます。トークンはクライアント API アプリケーションにキャッシュする必要があります。

メモ

アプリ間のセキュリティも正常に機能しています。証明書認証、または Azure ではマネージド ID を使用できます。

アクセストークンの処理

クライアントアプリケーションでアクセストークンを使用する場合、アクセストークンをローテーションし、永続化して、サーバー上のどこかに格納する必要があります。 Web アプリケーションでは、Cookie はセッションをセキュリティで保護するために使用され、 SaveTokens オプションを使用してトークンを格納するために使用できます。

現在のところ、SaveTokens ではアクセストークンは自動的に更新されませんが、この機能は .NET 10 用に計画されています。更新プログラムについては、https://github.com/dotnet/aspnetcore/issues/8175 に従ってください。それまでの間、 OIDC ドキュメントを使用して Blazor Web App で示されているように、アクセストークンを手動で更新するか、 Duende.AccessTokenManagement.OpenIdConnect などのサードパーティの NuGet パッケージを使用して、クライアントアプリでのアクセストークンの処理と管理を行うことができます。詳細については、「 Duende トークン管理」を参照してください。

メモ

運用環境にデプロイする場合、キャッシュはマルチインスタンスデプロイで機能する必要があります。通常、永続キャッシュが必要です。

セキュリティで保護されたトークンサーバーの中には、アクセストークンを暗号化するものもあります。アクセストークンには形式は必要ありません。 OAuth イントロスペクションを使用する場合は、アクセストークンの代わりに参照トークンが使用されます。アクセストークンはそういう目的のものではないため、クライアント (UI) アプリケーションでアクセストークンを開かないでください。アクセストークンが作成された API のみでアクセストークンを開く必要があります。

UI アプリケーションでアクセストークンを開かない
ID トークンを API に送信しない
アクセストークンには任意の形式を使用できる
アクセストークンは暗号化できる
アクセストークンの有効期限が切れ、ローテーションする必要がある
アクセストークンは、セキュリティで保護されたバックエンドサーバーに保持される

YARP (さらに別のリバースプロキシ)

YARP (さらに別のリバースプロキシ) は、HTTP 要求を処理し、要求を他の API に転送するために役立つテクノロジです。 YARP は、新しいアクセス資格情報を取得するためのセキュリティロジックを実装できます。 YARP は、フロントエンド (BFF) セキュリティアーキテクチャのバックエンドを採用するときによく使用されます。

YARP を使用して BFF パターンを実装する Blazor 例については、次の記事を参照してください。

YARP を使用して BFF パターンを実装する Blazor 例については、「 OpenID Connect (OIDC) を使用して ASP.NET Core Blazor Web App をセキュリティで保護する」を参照してください。

詳細については、「 auth0: フロントエンドパターンのバックエンド」を参照してください。

API のテスト

統合テストと、アクセストークンを持つコンテナーを使用して、セキュリティで保護された API をテストできます。アクセストークンは、 dotnet user-jwts ツールを使用して作成できます。

警告

テスト目的で API にセキュリティ上の問題が取り込まれないようにしてください。委任されたアクセストークンを使用する場合、テストはより困難になります。これらのトークンは UI と OpenID Connect フローを介してのみ作成できるためです。テストツールを使用して委任されたアクセストークンを作成する場合は、テストのためにセキュリティ機能を無効にする必要があります。これらの機能をテスト環境でのみ無効にすることが重要です。

セキュリティ機能を安全に無効または変更できる、専用の分離されたテスト環境を作成します。これらの変更がテスト環境のみに厳密に限定されていることを確認してください。

Swagger UI、Curl、およびその他の API UI ツールを使用する

Swagger UI と Curl は、API をテストするための優れた UI ツールです。ツールを機能させるには、API で OpenAPI ドキュメントを生成し、クライアントテストツールに読み込むことができます。新しいアクセストークンを取得するためのセキュリティフローを API OpenAPI ファイルに追加できます。

警告

セキュリティで保護されていないテストフローを運用環境にデプロイしないでください。

API 用の Swagger UI を実装する場合、これを機能させるにはセキュリティを弱める必要があるため、通常は UI を運用環境にデプロイしないでください。