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

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

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

前提条件

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

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

ヒント

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

Web API を登録する (TodoListService)

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

  1. Azure portal にサインインします。

  2. 複数のテナントにアクセスできる場合は、トップ メニューの [ディレクトリとサブスクリプション] フィルターを使用して、アプリケーションを登録するテナントを選択します。

  3. Azure Active Directory を検索して選択します。

  4. [管理][アプリの登録]>[新規登録] の順に選択します。

  5. アプリケーションの名前を入力します (例: AppModelv2-NativeClient-DotNet-TodoListService)。 この名前は、アプリのユーザーに表示される場合があります。また、後で変更することができます。

  6. [サポートされているアカウントの種類] で、 [任意の組織のディレクトリ内のアカウント] を選択します。

  7. [登録] を選択して、アプリケーションを作成します。

  8. アプリの [概要] ページで、 [アプリケーション (クライアント) ID] の値を探し、後で使用するために記録します。 これは、このプロジェクトの Visual Studio 構成ファイルを構成するために必要になります (つまり、TodoListService\Web.config ファイルの ClientId)。

  9. [管理] で、 [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. [状態][有効] のままにします。
  10. [スコープの追加] を選択します。

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

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

  1. Visual Studio でソリューションを開き、TodoListService プロジェクトのルートの下にある Web.config ファイルを開きます。

  2. ida:ClientId パラメーターの値を、アプリの登録ポータルで登録したアプリケーションのクライアント ID (アプリケーション ID) に置き換えます。

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

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

  1. TodoListClient プロジェクトのルート フォルダーで app.config ファイルを開きます。

  2. 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 アプリを登録するには、これらの手順に従います。

  1. 開発者用の Microsoft ID プラットフォームのアプリの登録ポータルに移動します。

  2. [新規登録] を選択します。

  3. [アプリケーションの登録] ページが表示されたら、以下のアプリケーションの登録情報を入力します。

    1. [名前] セクションに、アプリのユーザーに表示されるわかりやすいアプリケーション名を入力します (例: NativeClient-DotNet-TodoListClient)。
    2. [サポートされているアカウントの種類] で、 [任意の組織のディレクトリ内のアカウント] を選択します。
    3. [登録] を選択して、アプリケーションを作成します。

    注意

    TodoListClient プロジェクトの app.config ファイルで、ida:Tenant の既定値は common に設定されています。 次の値を指定できます。

    • common: 職場または学校アカウントを使用するか、個人用 Microsoft アカウントを使用してサインインできます (前の手順で [任意の組織のディレクトリ内のアカウント] を選択したため)。
    • organizations:職場または学校アカウントを使用してサインインできます。
    • consumers:Microsoft の個人用アカウントを使用してのみサインインできます。
  4. アプリの概要ページで [認証] を選択し、これらの手順を実行してプラットフォームを追加します。

    1. [プラットフォーム構成][プラットフォームを追加] ボタンを選択します。
    2. [モバイル アプリケーションとデスクトップ アプリケーション] で、 [モバイル アプリケーションとデスクトップ アプリケーション] を選択します。
    3. [リダイレクト URI] で、 https://login.microsoftonline.com/common/oauth2/nativeclient のチェック ボックスをオンにします。
    4. [構成] をクリックします。
  5. [API のアクセス許可] を選択し、これらの手順を実行してアクセス許可を追加します。

    1. [アクセス許可の追加] ボタンを選択します。
    2. [自分の API] タブを選択します。
    3. API のリストで [AppModelv2-NativeClient-DotNet-TodoListService API] または Web API に入力した名前を選択します。
    4. まだ選択していない場合は、access_as_user アクセス許可のチェック ボックスをオンにします。 必要に応じて検索ボックスを使用します。
    5. [アクセス許可の追加] ボタンを選択します

プロジェクトを構成する

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

  1. アプリの登録ポータルの [概要] ページで、 [アプリケーション (クライアント) ID] の値をコピーします。

  2. TodoListClient プロジェクトのルート フォルダーで app.config ファイルを開き、アプリケーション ID の値を ida:ClientId パラメーターに貼り付けます。

プロジェクトの実行

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

  1. Visual Studio ソリューションを右クリックし、[プロパティ] を選択します。

  2. [共通プロパティ] で、[スタートアップ プロジェクト][マルチ スタートアップ プロジェクト] の順に選択します。

  3. 両方のプロジェクトに対して、アクションとして [Start](開始) を選択します。

  4. 上向きの矢印を使用して TodoListService サービスを一覧の最初の位置に移動し、最初に開始されるようにします。

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

  1. F5 キーを押して、プロジェクトを開始します。 サービスのページと、デスクトップ アプリケーションが開きます。

  2. TodoListClient の右上にある [サインイン] を選択し、アプリケーションの登録に使用したのと同じ資格情報でサインインするか、同じディレクトリ内のユーザーとしてサインインします。

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

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

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

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

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

プロジェクトを実行する

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

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

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

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

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

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

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

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

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

ヘルプとサポート

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

次のステップ

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

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

前提条件

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

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

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

手順 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 で、ClientIdTenantId の値を置き換えます。 アプリケーション (クライアント) 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 に更新するには、次の手順に従います。

  1. webapi.csproj を開く

  2. 次の行を削除します。

    <TargetFramework>netcoreapp3.1</TargetFramework>
    
  3. その場所に次の行を追加します。

    <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.
...

このサンプルのしくみ

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