クイックスタート:Microsoft ID プラットフォームを使用して ASP.NET Core Web API を保護する

次のクイックスタートでは、ASP.NET Core Web API コード サンプルを使用して、承認されたアカウントへのリソース アクセスを制限する方法を示します。 このサンプルでは、個人用 Microsoft アカウントと Microsoft Entra 組織のアカウントの承認がサポートされています。

前提条件

• アクティブなサブスクリプションが含まれる Azure アカウント。 無料でアカウントを作成できます。
• Microsoft Entra テナント
• .NET 6.0 SDK の最小要件
• Visual Studio 2022 または Visual Studio Code

手順 1:アプリケーションを登録する

まず、Microsoft Entra テナントに Web API を登録し、次の手順に従ってスコープを追加します:

1. アプリケーション管理者以上の権限で Microsoft Entra 管理センターにサインインします。
2. [ID]>[アプリケーション]>[アプリの登録] を参照します。
3. [新規登録] を選択します。
4. [名前] にアプリケーションの名前を入力します。 たとえば、「AspNetCoreWebApi-Quickstart」と入力します。 アプリのユーザーには、この名前が表示されます。これは後で変更できます。
5. [登録] を選択します。
6. [管理] で、 [API の公開]>[スコープの追加] の順に選択します。 [アプリケーション ID URI] は既定値のままにして [保存して続行] を選択し、以下の詳細を入力します。

• スコープ名: access_as_user
• 同意できるのはだれですか? : 管理者とユーザー
• 管理者の同意の表示名: Access AspNetCoreWebApi-Quickstart
• 管理者の同意の説明: Allows the app to access AspNetCoreWebApi-Quickstart as the signed-in user.
• ユーザーの同意の表示名: Access AspNetCoreWebApi-Quickstart
• ユーザーの同意の説明: Allow the application to access AspNetCoreWebApi-Quickstart on your behalf.
• [状態] :有効

1. [スコープの追加] を選択してスコープの追加を完了します。

手順 2:ASP.NET Core プロジェクトをダウンロードする

GitHub から ASP.NET Core ソリューションをダウンロードします。

このコード サンプルは現在、ASP.NET Core 3.1 を対象にしています。 このサンプルは .NET Core 6.0 を使用するように更新でき、「サンプル コードを ASP.NET Core 6.0 に更新する」の手順で説明されています。 このクイックスタートは近い将来に非推奨となり、.NET 6.0 を使用するように更新される予定です。

手順 3:ASP.NET Core プロジェクトを構成する

この手順では、前に作成したアプリの登録を操作するようにサンプル コードが構成されます。

1. Windows のパスの長さ制限によって発生するエラーを回避するために、.zip ファイルをディスクのルートに近いローカル フォルダーに展開します。 たとえば、C:\Azure-Samples に展開します。

2. コード エディターで webapi フォルダーにあるソリューションを開きます。

3. appsettings.json で、ClientId、および TenantId の値を置き換えます。

   "ClientId": "Enter_the_Application_Id_here",
   "TenantId": "Enter_the_Tenant_Info_Here"
   

   • Enter_the_Application_Id_Here は、登録済みアプリケーションのアプリケーション (クライアント) ID です。
   • Enter_the_Tenant_Info_Here を、次のいずれかに置き換えます。
     • アプリケーションで [この組織のディレクトリ内のアカウントのみ] がサポートされている場合は、この値をディレクトリ (テナント) ID (GUID) またはテナント名 (例: contoso.onmicrosoft.com) に置き換えます。 ディレクトリ (テナント) ID は、アプリの [概要] ページで確認できます。
     • アプリケーションで "任意の組織のディレクトリ内のアカウント" がサポートされる場合は、この値を organizations に置き換えます。
     • アプリケーションで [すべての Microsoft アカウント ユーザー] がサポートされている場合は、この値を common のままにします。

このクイックスタートでは、appsettings.json ファイル内のその他の値は変更しないでください。

手順 4: サンプル コードを ASP.NET Core 6.0 に更新する

このコード サンプルをターゲットの ASP.NET Core 6.0 に更新するには、次の手順に従います。

1. webapi.csproj を開く
2. 次の行を削除します。

<TargetFramework>netcoreapp3.1</TargetFramework>

1. その場所に次の行を追加します。

<TargetFramework>netcoreapp6.0</TargetFramework>

この手順により、サンプルが .NET Core 6.0 フレームワークを対象とするようにします。

手順 5: サンプルを実行する

1. ターミナルを開いて、ディレクトリをプロジェクト フォルダーに変更します。

   cd webapi
   

2. 次のコマンドを実行して、ソリューションをビルドします。

dotnet run

ビルドが成功した場合は、次の出力が表示されます。

Building...
info: Microsoft.Hosting.Lifetime[0]
    Now listening on: https://localhost:{port}
info: Microsoft.Hosting.Lifetime[0]
    Now listening on: http://localhost:{port}
info: Microsoft.Hosting.Lifetime[0]
    Application started. Press Ctrl+C to shut down.
...

このサンプルのしくみ

スタートアップ クラス

Microsoft.AspNetCore.Authentication ミドルウェアは、ホスティング プロセスの開始時に実行される Startup クラスを使用します。 その ConfigureServices メソッドでは、Microsoft.Identity.Web によって提供される AddMicrosoftIdentityWebApi 拡張メソッドが呼び出されます。

    public void ConfigureServices(IServiceCollection services)
    {
        services.AddAuthentication(JwtBearerDefaults.AuthenticationScheme)
                .AddMicrosoftIdentityWebApi(Configuration, "AzureAd");
    }

AddAuthentication() メソッドは、JwtBearer ベースの認証を追加するようサービスを構成します。

.AddMicrosoftIdentityWebApi を含む行によって、Microsoft ID プラットフォームの認可が Web API に追加されます。 その後、appsettings.json 構成ファイルの AzureAD セクションの情報に基づいて、Microsoft ID プラットフォームによって発行されたアクセス トークンを検証するよう構成されます。

Configure() メソッドには、app.UseAuthentication() と app.UseAuthorization() という 2 つの重要なメソッドが含まれており、それらの名前付き機能を有効にします。

// The runtime calls this method. Use this method to configure the HTTP request pipeline.
public void Configure(IApplicationBuilder app, IHostingEnvironment env)
{
    // more code
    app.UseAuthentication();
    app.UseAuthorization();
    // more code
}

コントローラー、コントローラーのメソッド、Razor ページを保護する

[Authorize] 属性を使って、コントローラーまたはコントローラーのメソッドを保護できます。 この属性は、認証されたユーザーのみを許可することで、コントローラーまたはメソッドへのアクセスを制限します。 ユーザーが認証されていない場合、コントローラーにアクセスするための認証チャレンジを開始することができます。

namespace webapi.Controllers
{
    [Authorize]
    [ApiController]
    [Route("[controller]")]
    public class WeatherForecastController : ControllerBase

コントローラー内のスコープの検証

API のコードでは、HttpContext.VerifyUserHasAnyAcceptedScope> (scopeRequiredByApi); を使用して、必要なスコープがトークンに含まれていることを確認します。

namespace webapi.Controllers
{
    [Authorize]
    [ApiController]
    [Route("[controller]")]
    public class WeatherForecastController : ControllerBase
    {
        // The web API will only accept tokens 1) for users, and 2) having the "access_as_user" scope for this API
        static readonly string[] scopeRequiredByApi = new string[] { "access_as_user" };

        [HttpGet]
        public IEnumerable<WeatherForecast> Get()
        {
            HttpContext.VerifyUserHasAnyAcceptedScope(scopeRequiredByApi);

            // some code here
        }
    }
}

ヘルプとサポート

サポートが必要な場合、問題をレポートする場合、またはサポート オプションについて知りたい場合は、開発者向けのヘルプとサポートに関するページを参照してください。

次のステップ

次の GitHub リポジトリには、ASP.NET Core Web API コード サンプルの手順と、次の実現方法を示すその他のサンプルが含まれています。

• 新しい ASP.NET Core Web API に認証を追加する。
• デスクトップ アプリケーションから Web API を呼び出す。
• Microsoft Graph やその他の Microsoft API のようなダウンストリーム API を呼び出す。