Insomnia で ASP.NET Core の Web API を呼び出す

[アーティクル]
05/28/2024

この記事では、Insomnia を使用して保護された ASP.NET Core の Web API を呼び出す方法について説明します。 Insomnia は、Web API に HTTP 要求を送信して、その承認やアクセス制御 (認証) ポリシーをテストすることができるアプリケーションです。この記事では、テナントで Web アプリと Web API を登録します。 Web アプリは、Microsoft ID プラットフォームによって生成されたアクセストークンを取得するために使用します。次にこのトークンを使って、Insomniaで Web API に承認された呼び出しを行います。

この記事では、Insomnia を使用して保護された ASP.NET Core の Web API を呼び出す方法について説明します。 Insomnia は、Web API に HTTP 要求を送信して、その承認やアクセス制御 (認証) ポリシーをテストすることができるアプリケーションです。「チュートリアル: API に保護されたエンドポイントを実装する」では保護された API を作成しましたが、その後に Web アプリケーションを Microsoft ID プラットフォームに登録してアクセストークンを生成する必要があります。次にこのトークンを使って、Insomnia で API に承認された呼び出しを行います。

前提条件

アクティブなサブスクリプションが含まれる Azure アカウント。無料でアカウントを作成できます。
この Azure アカウントには、アプリケーションを管理するためのアクセス許可が必要です。以下のいずれの Microsoft Entra ロールにも、必要なアクセス許可が含まれています。
- アプリケーション管理者
- アプリケーション開発者
- クラウドアプリケーション管理者
Insomnia をダウンロードおよびインストールしておきます。 Insomnia で、API 要求に使用するアクセストークンを取得します。
.NET 8.0 SDK の最小要件。

アクティブなサブスクリプションが含まれる Azure アカウント。無料でアカウントを作成できます。
この Azure アカウントには、アプリケーションを管理するためのアクセス許可が必要です。以下のいずれの Microsoft Entra ロールにも、必要なアクセス許可が含まれています。
- アプリケーション管理者
- アプリケーション開発者
- クラウドアプリケーション管理者
チュートリアルシリーズの完了:
Insomnia をダウンロードおよびインストールしておきます。

アプリケーションの登録

Microsoft ID プラットフォームでは、ID およびアクセス管理サービスを利用する前に、アプリケーションを登録する必要があります。アプリケーションの登録では、アプリケーションの名前と種類とサインイン対象ユーザーを指定できます。サインイン対象ユーザーは、特定のアプリケーションにサインインできるユーザーアカウントの種類を指定します。

Web API を登録する

ヒント

この記事の手順は、開始するポータルによって若干異なる場合があります。

Web API の登録を作成するには、次の手順のようにします。

アプリケーション開発者以上として Microsoft Entra 管理センターにサインインします。
複数のテナントにアクセスできる場合は、上部のメニューの [設定] アイコンを使い、[ディレクトリとサブスクリプション] メニューからアプリケーションを登録するテナントに切り替えます。
[ID]>[アプリケーション]>[アプリの登録] を参照します。
[新規登録] を選択します。
アプリケーションの名前 (NewWebAPI1 など) を入力します。
[サポートされているアカウントの種類] で、 [この組織のディレクトリ内のアカウントのみ] を選択します。さまざまなアカウントの種類については、[選択に関するヘルプ] オプションを選択します。
[登録] を選択します。
登録が完了すると、アプリケーションの [概要] ペインが表示されます。 ディレクトリ (テナント) ID とアプリケーション (クライアント) ID は、後の手順で使用するので記録しておきます。

注意

サポートされているアカウントの種類は、「アプリケーションによってサポートされるアカウントを変更する」を参照して変更することができます。

API を公開する

API が登録されると、API がクライアントアプリケーションに公開するスコープを定義することで、そのアクセス許可を構成することができます。クライアントアプリケーションは、アクセストークンとその要求を保護された Web API に渡すことで、操作を実行するためのアクセス許可を要求します。 Web API が要求された操作を実行するのは、受け取ったアクセストークンが有効な場合だけに限られます。

[管理] で、[API の公開] > [スコープの追加] の順に選択します。提案されたアプリケーション ID URI (api://{clientId}) を受け入れるには、[保存して続行] を選択します。 {clientId} は、[概要] ページから記録した値です。そして、次の情報を入力します。
1. [スコープ名] に「Forecast.Read」と入力します。
2. [同意できるユーザー] で [管理者とユーザー] オプションが選択されていることを確認します。
3. [管理者の同意の表示名] ボックスには、「Read forecast data」と入力します。
4. [管理者の同意の説明] ボックスには、「Allows the application to read weather forecast data」と入力します。
5. [ユーザーの同意の表示名] ボックスには、「Read forecast data」と入力します。
6. [ユーザーの同意の説明] ボックスには、「Allows the application to read weather forecast data」と入力します。
7. [状態] が [有効] に設定されていることを確認します。
[スコープの追加] を選択します。スコープが正しく入力されている場合は、[API の公開] ペインに表示されます。

Web アプリを登録する

Web API を用意するだけでは不十分です。アクセストークンを取得するための Web アプリも入手して、Web API にアクセスする必要があります。

Web アプリの登録を作成するには、次の手順のようにします。

[ホーム] を選択してホームページに戻ります。 [ID]>[アプリケーション]>[アプリの登録] を参照します。
[新規登録] を選択します。
[名前] に、アプリケーションの名前を identity-client-web-app などと入力します。
[サポートされているアカウントの種類] で、 [この組織のディレクトリ内のアカウントのみ] を選択します。さまざまなアカウントの種類の詳細については、[選択に関するヘルプ] オプションを選択します。
[リダイレクト URI (省略可能)] で、[Web] を選択し、URL テキストボックスに「http://localhost」と入力します。
[登録] を選択します。

アプリケーション開発者以上として Microsoft Entra 管理センターにサインインします。
複数のテナントにアクセスできる場合は、上部のメニューの [設定] アイコンを使い、[ディレクトリとサブスクリプション] メニューからアプリケーションを登録するテナントに切り替えます。
[ID]>[アプリケーション]>[アプリの登録] を参照します。
[新規登録] を選択します。
[名前] に、アプリケーションの名前を identity-client-web-app などと入力します。
[サポートされているアカウントの種類] で、 [この組織のディレクトリ内のアカウントのみ] を選択します。さまざまなアカウントの種類の詳細については、[選択に関するヘルプ] オプションを選択します。
[リダイレクト URI (省略可能)] で、[Web] を選択し、URL テキストボックスに「http://localhost」と入力します。
[登録] を選択します。

登録が完了すると、アプリケーションの [概要] ペインが表示されます。 ディレクトリ (テナント) ID とアプリケーション (クライアント) ID は、後の手順で使用するので記録しておきます。

クライアントシークレットの追加

クライアントシークレットは、アプリが自分自身を識別するために使用できる文字列値であり、" アプリケーションパスワード"と呼ばれることもあります。 Web アプリは、トークンを要求するときに、このクライアントシークレットを使用してその ID を証明します。

次の手順に従って、クライアントシークレットを構成します。

[概要] ペインの [管理] で、[証明書とシークレット]>[クライアントシークレット]>[新しいクライアントシークレット] の順に選択します。
クライアントシークレットの説明 (例: 自分のクライアントシークレット) を追加します。
シークレットの有効期限を選択するか、カスタムの有効期間を指定します。
- クライアントシークレットの有効期間は、2 年間 (24 か月) 以内に制限されています。 24 か月を超えるカスタムの有効期間を指定することはできません。
- Microsoft では、有効期限の値は 12 か月未満に設定することをお勧めしています。
[追加] を選択します。
クライアントシークレットの値は必ず記録しておいてください。このページからの移動後は、このシークレットの値は "二度と表示されません"。

クライアントシークレットを安全に格納する方法の詳細については、「Key Vault でのシークレットの管理に関するベストプラクティス」を参照してください。

Web API にアクセスするためのアクセス許可を追加する

Web API のスコープを指定することにより、Web アプリは Microsoft ID プラットフォームが提供するスコープを含むアクセストークンを取得することができます。次にコード内で、Web API はアクセストークンに含まれるスコープに基づいて、リソースに対するアクセス許可ベースのアクセスを提供することができます。

次の手順に従って、Web API に対するクライアントのアクセス許可を構成します。

アプリケーションの [概要] ペインの [管理] で、[API のアクセス許可]>[アクセス許可の追加]>[所属する組織で使用している API] の順に選択します。
NewWebAPI1 またはアクセス許可を追加したい API を選択します。
[アクセス許可を選択] で、Forecast.Read の横にあるボックスをチェックします。 [アクセス許可] の一覧を展開する必要があるかもしれません。これにより、サインインしているユーザーに代わってクライアントアプリがもつべきアクセス許可が選択されます。
[アクセス許可の追加] を選択してプロセスを完了します。

これらのアクセス許可をご自身の API に追加した後、選択したアクセス許可が [構成されたアクセス許可] に表示されます。

Microsoft Graph API に対する User.Read アクセス許可も表示されています。このアクセス許可は、アプリを登録すると自動的に追加されます。

Web API をテストする

API が動作し、要求を処理する準備ができていることを確認するには、次の手順に従います。

ms-identity-docs-code-dotnet リポジトリを複製します。

git clone https://github.com/Azure-Samples/ms-identity-docs-code-dotnet.git

ms-identity-docs-code-dotnet/web-api に移動して appsettings.json を開き、{APPLICATION_CLIENT_ID} と {DIRECTORY_TENANT_ID} を次の値に置き換えます。
- {APPLICATION_CLIENT_ID} は、アプリの [概要] ウィンドウにある Web API アプリケーション (クライアント) ID です。
- {DIRECTORY_TENANT_ID} は、アプリの [概要] ウィンドウにある Web API ディレクトリ (テナント) ID です。
次のコマンドを実行して、アプリを起動します。
```
dotnet run
```
次のような出力が表示されます。ポート番号を https://localhost:{port} URL に記録します。
```
...
info: Microsoft.Hosting.Lifetime[14]
      Now listening on: https://localhost:{port}
...
```

Web API をテストする

API が動作し、要求を処理する準備ができていることを確認するには、次の手順に従います。

「チュートリアル: ASP.NET Core プロジェクトを作成し、API を構成する」で作成した Web API (たとえば NewWebAPILocal) に移動し、フォルダーを開きます。
新しいターミナルウィンドウを開き、Web API プロジェクトが置いてあるフォルダーに移動します。
- .NET 6.0
- .NET 7.0
1. 次のコマンドを実行して、アプリを起動します。
```
dotnet run
```
1. 新しいターミナルを開き、次のコマンドを実行してアプリを https プロファイルで起動します。
```
dotnet run -launch-profile https`
```
次のような出力が表示されます。ポート番号を https://localhost:{port} URL に記録します。
```
...
info: Microsoft.Hosting.Lifetime[14]
      Now listening on: https://localhost:{port}
...
```

Insomnia で Web API に対する承認済み要求を構成する

API 要求に使用するアクセストークンを取得するには、次の手順に従います。

Insomnia アプリケーションを起動します。
[新しい HTTP 要求] を選択するか、"Ctrl + N" を使用して新しい HTTP 要求を作成できます。
[新しい要求] モーダルで、ドロップダウンから GET メソッドを選択します。
要求 URL に、Web API によって公開されるエンドポイントの URL、https://localhost:{port}/weatherforecast を入力します。
[認証] ドロップダウンメニューから、[OAuth 2.0] を選択します。これで、OAuth 2.0 フォームが表示されます。

OAuth 2.0 フォームに、次の値を入力します。

設定	Value
付与タイプ	[Authorization Code] (認可コード) を選びます
承認 URL	`https://login.microsoftonline.com/{tenantId}/oauth2/v2.0/authorize` `{tenantId}` をディレクトリ (テナント) ID に置き換えます
アクセストークン URL	`https://login.microsoftonline.com/{tenantId}/oauth2/v2.0/token` `{tenantId}` をディレクトリ (テナント) ID に置き換えます
クライアント ID	Web アプリ登録のアプリケーション (クライアント) ID 値
クライアントシークレット	Web アプリ登録のクライアントシークレットの値
リダイレクト URL	「`http://localhost`」と入力すると、リダイレクト URL が、Microsoft Entra ID に登録されているリダイレクト URI に設定されます。
[詳細オプション]>[スコープ]	`api://{application_client_id}/Forecast.Read` Web アプリ登録に移動し、[管理] で、[API のアクセス許可] を選択し、Forecast.Read を選択しますテキストボックス内の、[スコープ] 値を含む値をコピーします

アクセストークンを取得し、Web API に要求を送信する

値を入力したら、フォームの末尾で [トークンをフェッチする] を選択します。これにより Insomnia のブラウザーウィンドウが起動し、ユーザー資格情報での認証が行われます。必ず、ブラウザーで Insomnia アプリケーションからのポップアップを許可してください。
認証後、[送信] を選択して、要求を保護された Web API エンドポイントに送信します。

要求に有効なアクセストークンが含まれている場合、期待される応答は 200 OK で、出力は次のようになります。

[
  {
    "date": "YYYY-MM-DDTHH:MM:SS",
    "temperatureC": -16,
    "summary": "Scorching",
    "temperatureF": 4
  },
  {
    "date": "YYYY-MM-DDTHH:MM:SS",
    "temperatureC": 1,
    "summary": "Sweltering",
    "temperatureF": 33
  },
  {
    "date": "YYYY-MM-DDTHH:MM:SS",
    "temperatureC": 26,
    "summary": "Freezing",
    "temperatureF": 78
  },
  {
    "date": "YYYY-MM-DDTHH:MM:SS",
    "temperatureC": 54,
    "summary": "Mild",
    "temperatureF": 129
  },
  {
    "date": "YYYY-MM-DDTHH:MM:SS",
    "temperatureC": 11,
    "summary": "Bracing",
    "temperatureF": 51
  }
]

OAuth 2.0 の承認コードフローとアプリケーションの種類の詳細については、以下を参照してください。

次の方法で共有

Insomnia で ASP.NET Core の Web API を呼び出す

前提条件