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

[アーティクル]
02/01/2023

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

また、この記事では、Windows Presentation Foundation (WPF) アプリを使って、Web API にアクセスするためのアクセストークンを要求するデモンストレーションを行います。

前提条件

アクティブなサブスクリプションが含まれる Azure アカウント。無料でアカウントを作成できます。
Visual Studio 2022。 Visual Studio を無料でダウンロードします。

サンプルをクローンまたはダウンロードする

コードサンプルは次の 2 つの方法で取得できます。

シェルまたはコマンドラインからクローンする

git clone https://github.com/AzureADQuickStarts/AppModelv2-NativeClient-DotNet.git

ZIP ファイルとしてダウンロードする

ヒント

Windows におけるパスの長さの制限に起因したエラーを防ぐため、ドライブのルートに近いディレクトリをアーカイブの展開先またはリポジトリのクローン先とすることをお勧めします。

Web API を登録する (TodoListService)

Azure portal の [アプリの登録] で Web API を登録します。

Azure portal にサインインします。
複数のテナントにアクセスできる場合は、トップメニューの [ディレクトリとサブスクリプション] フィルターを使用して、アプリケーションを登録するテナントを選択します。
Azure Active Directory を検索して選択します。
[管理] で [アプリの登録]>[新規登録] の順に選択します。
アプリケーションの名前を入力します (例: AppModelv2-NativeClient-DotNet-TodoListService)。この名前は、アプリのユーザーに表示される場合があります。また、後で変更することができます。
[サポートされているアカウントの種類] で、 [任意の組織のディレクトリ内のアカウント] を選択します。
[登録] を選択して、アプリケーションを作成します。
アプリの [概要] ページで、 [アプリケーション (クライアント) ID] の値を探し、後で使用するために記録します。これは、このプロジェクトの Visual Studio 構成ファイルを構成するために必要になります (つまり、TodoListService\Web.config ファイルの ClientId)。
[管理] で、 [API の公開]>[スコープの追加] の順に選択します。 [保存して続行] を選択して、提案されたアプリケーション ID URI (api://{clientId}) を受け入れ、次の情報を入力します。
1. [スコープ名] に「access_as_user」と入力します。
2. [同意できるユーザー] で [管理者とユーザー] オプションが選択されていることを確認します。
3. [管理者の同意の表示名] ボックスには、「Access TodoListService as a user」と入力します。
4. [管理者の同意の説明] ボックスには、「Accesses the TodoListService web API as a user」と入力します。
5. [ユーザーの同意の表示名] ボックスには、「Access TodoListService as a user」と入力します。
6. [ユーザーの同意の説明] ボックスには、「Accesses the TodoListService web API as a user」と入力します。
7. [状態] は [有効] のままにします。
[スコープの追加] を選択します。

サービスプロジェクトを構成する

登録されている Web API に一致するようにサービスプロジェクトを構成します。

Visual Studio でソリューションを開き、TodoListService プロジェクトのルートの下にある Web.config ファイルを開きます。
ida:ClientId パラメーターの値を、アプリの登録ポータルで登録したアプリケーションのクライアント ID (アプリケーション ID) に置き換えます。

新しいスコープを app.config ファイルに追加する

新しいスコープを TodoListClient app.config ファイルに追加するには、これらの手順を実行します。

TodoListClient プロジェクトのルートフォルダーで app.config ファイルを開きます。
TodoListServiceScope パラメーターで TodoListService プロジェクトに登録したアプリケーションのアプリケーション ID を貼り付け、{Enter the Application ID of your TodoListService from the app registration portal} 文字列を置き換えます。

注意

アプリケーション ID の形式が api://{TodoListService-Application-ID}/access_as_user になっていることを確認してください ({TodoListService-Application-ID} は TodoListService アプリのアプリケーション ID を表す GUID です)。

Web アプリを登録する (TodoListClient)

Azure portal のアプリの登録で TodoListClient アプリを登録し、TodoListClient プロジェクトでコードを設定します。クライアントとサーバーが同じアプリケーションと見なされる場合は、手順 2 で登録したアプリケーションを再利用できます。ユーザーが個人用 Microsoft アカウントでサインインできるようにするには、同じアプリケーションを使用します。

アプリを登録する

TodoListClient アプリを登録するには、これらの手順に従います。

開発者用の Microsoft ID プラットフォームのアプリの登録ポータルに移動します。
[新規登録] を選択します。
[アプリケーションの登録] ページが表示されたら、以下のアプリケーションの登録情報を入力します。
1. [名前] セクションに、アプリのユーザーに表示されるわかりやすいアプリケーション名を入力します (例: NativeClient-DotNet-TodoListClient)。
2. [サポートされているアカウントの種類] で、 [任意の組織のディレクトリ内のアカウント] を選択します。
3. [登録] を選択して、アプリケーションを作成します。
注意

TodoListClient プロジェクトの app.config ファイルで、ida:Tenant の既定値は common に設定されています。次の値を指定できます。
- common: 職場または学校アカウントを使用するか、個人用 Microsoft アカウントを使用してサインインできます (前の手順で [任意の組織のディレクトリ内のアカウント] を選択したため)。
- organizations:職場または学校アカウントを使用してサインインできます。
- consumers:Microsoft の個人用アカウントを使用してのみサインインできます。
アプリの概要ページで [認証] を選択し、これらの手順を実行してプラットフォームを追加します。
1. [プラットフォーム構成] で [プラットフォームを追加] ボタンを選択します。
2. [モバイルアプリケーションとデスクトップアプリケーション] で、 [モバイルアプリケーションとデスクトップアプリケーション] を選択します。
3. [リダイレクト URI] で、 https://login.microsoftonline.com/common/oauth2/nativeclient のチェックボックスをオンにします。
4. [構成] をクリックします。
[API のアクセス許可] を選択し、これらの手順を実行してアクセス許可を追加します。
1. [アクセス許可の追加] ボタンを選択します。
2. [自分の API] タブを選択します。
3. API のリストで [AppModelv2-NativeClient-DotNet-TodoListService API] または Web API に入力した名前を選択します。
4. まだ選択していない場合は、access_as_user アクセス許可のチェックボックスをオンにします。必要に応じて検索ボックスを使用します。
5. [アクセス許可の追加] ボタンを選択します

プロジェクトを構成する

アプリケーション ID を app.config ファイルに追加して、TodoListClient プロジェクトを構成します。

アプリの登録ポータルの [概要] ページで、 [アプリケーション (クライアント) ID] の値をコピーします。
TodoListClient プロジェクトのルートフォルダーで app.config ファイルを開き、アプリケーション ID の値を ida:ClientId パラメーターに貼り付けます。

プロジェクトの実行

両方のプロジェクトを開始します。 Visual Studio ユーザーの場合は次のとおりです。

Visual Studio ソリューションを右クリックし、[プロパティ] を選択します。
[共通プロパティ] で、[スタートアッププロジェクト]、[マルチスタートアッププロジェクト] の順に選択します。
両方のプロジェクトに対して、アクションとして [Start](開始) を選択します。
上向きの矢印を使用して TodoListService サービスを一覧の最初の位置に移動し、最初に開始されるようにします。

TodoListClient プロジェクトにサインインして実行します。

F5 キーを押して、プロジェクトを開始します。サービスのページと、デスクトップアプリケーションが開きます。
TodoListClient の右上にある [サインイン] を選択し、アプリケーションの登録に使用したのと同じ資格情報でサインインするか、同じディレクトリ内のユーザーとしてサインインします。

初めてサインインする場合は、TodoListService Web API に同意するように求められることがあります。

TodoListService Web API にアクセスし、To-Do リストを操作できるようにするために、このサインインでは access_as_user スコープへのアクセストークンも要求されます。

クライアントアプリケーションを事前承認する

Web API にアクセスするクライアントアプリケーションを事前承認することで、他のディレクトリのユーザーに Web API へのアクセスを許可することができます。これを行うには、クライアントアプリからのアプリケーション ID を Web API の事前承認済みアプリケーションのリストに追加します。事前承認されたクライアントを追加すると、ユーザーは同意しなくても Web API にアクセスできるようになります。

アプリの登録ポータルで、TodoListService アプリのプロパティを開きます。
[API の公開] セクションの [承認済みのクライアントアプリケーション] で [クライアントアプリケーションの追加] を選択します。
[クライアント ID] ボックスに、TodoListClient アプリのアプリケーション ID を貼り付けます。
[承認済みのスコープ] セクションで、api://<Application ID>/access_as_user Web API のスコープを選択します。
[アプリケーションの追加] をクリックします。

プロジェクトを実行する

F5 キーを押してプロジェクトを実行します。 TodoListClient アプリが開きます。
右上にある [サインイン] を選択して、live.com、hotmail.com などの Microsoft の個人用アカウント、または職場または学校アカウントを使用してサインインします。

既定では、outlook.com、live.com などの個人用アカウント、または Azure AD に統合されている組織の職場または学校アカウントはすべて、トークンを要求したり、Web API にアクセスしたりできます。

アプリケーションにサインインできるユーザーを指定するには、次のいずれかのオプションを使用します。

オプション 1: 単一の組織へのアクセスを制限する (シングルテナント)

単一の Azure AD テナントに属するユーザーアカウント (そのテナントのゲストアカウントを含む) に、アプリケーションへのサインインアクセスを制限できます。このシナリオは、基幹業務アプリケーションに共通です。

App_Start\Startup.Auth ファイルを開き、OpenIdConnectSecurityTokenProvider に渡されたメタデータの値を https://login.microsoftonline.com/{Tenant ID}/v2.0/.well-known/openid-configuration に変更します。 contoso.onmicrosoft.com などのテナント名を使用することもできます。
同じファイルで、TokenValidationParameters の ValidIssuer プロパティを https://sts.windows.net/{Tenant ID}/ に設定し、ValidateIssuer 引数を true に設定します。

オプション 2:カスタムメソッドを使用して発行者を検証する

IssuerValidator パラメーターを使用して、カスタムメソッドを実装して発行者を検証できます。このパラメーターの詳細については、TokenValidationParameters クラスに関するページを参照してください。

ヘルプとサポート

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

次のステップ

Microsoft ID プラットフォームでサポートされている保護された Web API のシナリオの詳細については、次を参照してください。

保護された Web API のシナリオ

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

前提条件

アクティブなサブスクリプションが含まれる Azure アカウント。無料でアカウントを作成できます。
Azure Active Directory テナント
.NET Core SDK 6.0 以降
Visual Studio 2022 または Visual Studio Code

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

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

Azure portal にサインインします。
複数のテナントにアクセスできる場合は、トップメニューの [ディレクトリとサブスクリプション] フィルターを使用して、アプリケーションを登録する先のテナントに切り替えます。
Azure Active Directory を検索して選択します。
[管理] で [アプリの登録]>[新規登録] の順に選択します。
[名前] にアプリケーションの名前を入力します。たとえば、「AspNetCoreWebApi-Quickstart」と入力します。アプリのユーザーには、この名前が表示されます。これは後で変更できます。
[登録] を選択します。
[管理] で、 [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.
- [状態] :有効
[スコープの追加] を選択してスコープの追加を完了します。

手順 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 プロジェクトを構成する

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

Windows のパスの長さ制限によって発生するエラーを回避するために、.zip ファイルをディスクのルートに近いローカルフォルダーに展開します。たとえば、C:\Azure-Samples に展開します。
コードエディターで webapi フォルダーにあるソリューションを開きます。
appsettings.json で、ClientId、TenantId の値を置き換えます。アプリケーション (クライアント) ID とディレクトリ (テナント) ID の値は、Azure portal のアプリの [概要] ページにあります。
```
"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 に更新するには、次の手順に従います。

webapi.csproj を開く

次の行を削除します。

<TargetFramework>netcoreapp3.1</TargetFramework>

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

<TargetFramework>netcoreapp6.0</TargetFramework>

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

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

ターミナルを開いて、ディレクトリをプロジェクトフォルダーに変更します。
```
cd webapi
```
次のコマンドを実行して、ソリューションをビルドします。
```
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.
...

このサンプルのしくみ

Web API はクライアントアプリケーションからトークンを受け取り、Web API のコードでそのトークンを検証します。このシナリオの詳細については、「シナリオ: 保護された Web API」を参照してください。

スタートアップクラス

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 プラットフォームによって発行されたアクセストークンを検証するよう構成されます。

appsettings.json のキー	説明
`ClientId`	Azure portal に登録されているアプリケーションのアプリケーション (クライアント) ID。
`Instance`	ユーザーが認証するためのセキュリティトークンサービス (STS) エンドポイント。通常、この値は、Azure パブリッククラウドを示す `https://login.microsoftonline.com/` です。
`TenantId`	テナントの名前またはテナント ID (GUID)。職場または学校アカウントあるいは Microsoft 個人アカウントを使ってユーザーのサインインを行う場合は `common`。

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 を呼び出す。

GitHub の ASP.NET Core Web API のチュートリアル

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

前提条件

サンプルをクローンまたはダウンロードする

Web API を登録する (TodoListService)

サービスプロジェクトを構成する

新しいスコープを app.config ファイルに追加する

Web アプリを登録する (TodoListClient)

アプリを登録する

プロジェクトを構成する

プロジェクトの実行

クライアントアプリケーションを事前承認する

プロジェクトを実行する

オプション 1: 単一の組織へのアクセスを制限する (シングルテナント)

オプション 2:カスタムメソッドを使用して発行者を検証する

ヘルプとサポート

次のステップ

前提条件

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

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

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

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

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

このサンプルのしくみ

スタートアップクラス

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

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

ヘルプとサポート

次のステップ

その他のリソース

その他のリソース

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

前提条件

サンプルをクローンまたはダウンロードする

Web API を登録する (TodoListService)

サービス プロジェクトを構成する

新しいスコープを app.config ファイルに追加する

Web アプリを登録する (TodoListClient)

アプリを登録する

プロジェクトを構成する

プロジェクトの実行

クライアント アプリケーションを事前承認する

プロジェクトを実行する

省略可能:サインイン アクセスを特定のユーザーに制限する

オプション 1: 単一の組織へのアクセスを制限する (シングル テナント)

オプション 2:カスタム メソッドを使用して発行者を検証する

ヘルプとサポート

次のステップ

前提条件

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

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

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

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

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

このサンプルのしくみ

スタートアップ クラス

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

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

ヘルプとサポート

次のステップ

その他のリソース

その他のリソース

サービスプロジェクトを構成する

クライアントアプリケーションを事前承認する

省略可能:サインインアクセスを特定のユーザーに制限する

オプション 1: 単一の組織へのアクセスを制限する (シングルテナント)

オプション 2:カスタムメソッドを使用して発行者を検証する

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

スタートアップクラス