保護された Web API: コード構成

ASP.NET Core で Web API を開発する場合は、Microsoft.Identity.Web NuGet パッケージを使用することをお勧めします。

Microsoft.Identity.Web を使用すると、ASP.NET Core、認証ミドルウェア、および .NET 用の Microsoft Authentication Library (MSAL) 間を結び付けることができます。 これにより、より明確で堅牢な開発者エクスペリエンスが可能になり、Microsoft ID プラットフォームと Azure AD B2C の機能を活用できます。

.NET 6.0 用 ASP.NET

Microsoft.Identity.Web を使う新しい Web API プロジェクトを作成するには、.NET 6.0 CLI または Visual Studio でプロジェクト テンプレートを使います。

.NET Core CLI

# Create new web API that uses Microsoft.Identity.Web
dotnet new webapi --auth SingleOrg

Visual Studio - Visual Studio で Web API プロジェクトを作成するには、[ファイル]>[新規作成]>[プロジェクト]>[ASP.NET Core Web API] を選択します。

.NET CLI と Visual Studio の両方のプロジェクト テンプレートで、このコード スニペットのような Program.cs ファイルが作成されます。 Microsoft.Identity.Web using ディレクティブと、認証と承認を含む行に注目してください。

using Microsoft.AspNetCore.Authentication;
using Microsoft.AspNetCore.Authentication.JwtBearer;
using Microsoft.Identity.Web;

var builder = WebApplication.CreateBuilder(args);

// Add services to the container.
builder.Services.AddAuthentication(JwtBearerDefaults.AuthenticationScheme)
    .AddMicrosoftIdentityWebApi(builder.Configuration.GetSection("AzureAd"));

builder.Services.AddControllers();
// Learn more about configuring Swagger/OpenAPI at https://aka.ms/aspnetcore/swashbuckle
builder.Services.AddEndpointsApiExplorer();
builder.Services.AddSwaggerGen();

var app = builder.Build();

// Configure the HTTP request pipeline.
if (app.Environment.IsDevelopment())
{
    app.UseSwagger();
    app.UseSwaggerUI();
}

app.UseHttpsRedirection();

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

app.MapControllers();

app.Run();

ASP.NET で Web API を開発するときは、Microsoft.Identity.Web.OWIN NuGet パッケージを使用することをお勧めします。

"Microsoft.Identity.Web.OWIN" を使用すると、ASP.NET、ASP.NET 認証ミドルウェア、および .NET 用の Microsoft Authentication Library (MSAL) 間を結び付けることができます。 これにより、より明確で堅牢な開発者エクスペリエンスが可能になり、Microsoft ID プラットフォームと Azure AD B2C の機能を活用できます。

ASP.NET Core (appsettings.json) と同じ構成ファイルを使用するため、このファイルがプロジェクトの出力とともにコピーされていることを確認する必要があります (プロパティのコピーは、常に Visual Studio または .csproj のファイルのプロパティにあります)

"Microsoft.Identity.Web.OWIN" は、 という名前の拡張メソッドを IAppBuilder に追加します。AddMicrosoftIdentityWebApi これらのメソッドは、OwinTokenAcquirerFactory のインスタンスをパラメーターとして受け取って、OwinTokenAcquirerFactory.GetDefaultInstance<OwinTokenAcquirerFactory>() を呼び出し、IServiceCollection のインスタンスを表示します。このインスタンスに対して、ダウンストリーム API の呼び出しや、トークン キャッシュの構成を行う多くのサービスを追加できます。

Startup.Auth.cs のサンプル コードを次に示します。 詳細なコードは tests/DevApps/aspnet-mvc/OwinWebApp から入手できます

using Microsoft.Owin.Security;
using Microsoft.Owin.Security.Cookies;
using Owin;
using Microsoft.Identity.Web;
using Microsoft.Identity.Web.TokenCacheProviders.InMemory;
using Microsoft.Extensions.DependencyInjection;
using Microsoft.Identity.Client;
using Microsoft.Identity.Abstractions;
using Microsoft.Identity.Web.OWIN;
using System.Web.Services.Description;

namespace OwinWebApp
{
    public partial class Startup
    {
        public void ConfigureAuth(IAppBuilder app)
        {
            app.SetDefaultSignInAsAuthenticationType(CookieAuthenticationDefaults.AuthenticationType);
            app.UseCookieAuthentication(new CookieAuthenticationOptions());

            OwinTokenAcquirerFactory factory = TokenAcquirerFactory.GetDefaultInstance<OwinTokenAcquirerFactory>();

            app.AddMicrosoftIdentityWebApp(factory);
            factory.Services
                .Configure<ConfidentialClientApplicationOptions>(options => { options.RedirectUri = "https://localhost:44386/"; })
                .AddMicrosoftGraph()
                .AddDownstreamApi("DownstreamAPI1", factory.Configuration.GetSection("DownstreamAPI"))
                .AddInMemoryTokenCaches();
            factory.Build();
        }
    }
}

--

トークンの検証

前のスニペットでは、Web アプリの OpenID Connect ミドルウェアと同様に、JwtBearer ミドルウェアによって TokenValidationParameters の値に基づいてトークンが検証されます。 トークンは必要に応じて暗号化が解除され、要求が抽出され、署名が検証されます。 その後、ミドルウェアでは、このデータを調べてトークンを確認します。

• Audience:トークンが Web API のターゲットとなっていること。
• サブ:Web API の呼び出しが許可されているアプリに対して発行されたこと。
• 発行者:信頼できるセキュリティ トークン サービス (STS) によって発行されたこと。
• 有効期限:有効期間が範囲内であること。
• 署名:改ざんされていないこと。

特別な検証もできます。 たとえば、署名キー (トークンに埋め込まれている場合) が信頼されていること、およびトークンが再生されていないことを確認することができます。 最後に、一部のプロトコルでは、特定の検証が必要です。

検証コントロール

確認手順は、検証コントロールでキャプチャされます。これらは Microsoft IdentityModel Extensions for .NET のオープン ソース ライブラリで提供されています。 検証コントロールは、ライブラリ ソース ファイル Microsoft.IdentityModel.Tokens/Validators.cs で定義されています。

次の表では、検証コントロールについて説明します。

トークンの検証のカスタマイズ

検証コントロールは、TokenValidationParameters クラスのプロパティに関連付けられています。 このプロパティは、ASP.NET と ASP.NET Core の構成から初期化されます。

ほとんどの場合、パラメーターを変更する必要はありません。 シングル テナントではないアプリは例外です。 これらの Web アプリでは、任意の組織から、または個人用 Microsoft アカウントからのユーザーを受け入れます。 この場合、発行者を検証する必要があります。 Microsoft.Identity.Web では発行者の検証も行われます。

ASP.NET Core で、トークン検証パラメーターをカスタマイズする場合は、Startup.cs で次のスニペットを使用します。

services.AddAuthentication(JwtBearerDefaults.AuthenticationScheme)
        .AddMicrosoftIdentityWebApi(Configuration);
services.Configure<JwtBearerOptions>(JwtBearerDefaults.AuthenticationScheme, options =>
{
  options.TokenValidationParameters.ValidAudiences = new[] { /* list of valid audiences */};
});

ASP.NET MVC の場合、次のコード サンプルにカスタム トークンの検証を行う方法が示されています。

https://github.com/azure-samples/active-directory-dotnet-webapi-manual-jwt-validation

Azure Functions でのトークンの検証

Azure Functions では、受信アクセス トークンを検証することもできます。 このような検証の例については、GitHub の次のコード サンプルを参照してください。

• .NET:Azure-Samples/ms-identity-dotnet-webapi-azurefunctions
• Node.js:Azure-Samples/ms-identity-nodejs-webapi-azurefunctions
• Python: Azure-Samples/ms-identity-python-webapi-azurefunctions)

次のステップ

このシナリオの次の記事である「コードでスコープとアプリのロールを検証する」に進みます。