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

[アーティクル]
10/15/2024

この記事では、Client URL (cURL) を使用して保護された ASP.NET Core の Web API を呼び出す方法について説明します。 cURLは、開発者がサーバーとの間でデータを転送するために使用するコマンドラインツールです。この記事では、テナントで Web アプリと Web API を登録します。 Web アプリは、Microsoft ID プラットフォームによって生成されたアクセストークンを取得するために使用します。次にこのトークンを使って、cURL を使用して Web API に承認された呼び出しを行います。

この記事では、Client URL (cURL) を使用して保護された ASP.NET Core の Web API を呼び出す方法について説明します。 cURLは、開発者がサーバーとの間でデータを転送するために使用するコマンドラインツールです。「チュートリアル: API に保護されたエンドポイントを実装する」では保護された API を作成しましたが、その後に Web アプリケーションを Microsoft ID プラットフォームに登録してアクセストークンを生成する必要があります。次にこのトークンを使って、cURL を使用して API に承認された呼び出しを行います。

前提条件

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

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

Microsoft ID プラットフォームにアプリケーションを登録する

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 API にアクセスするためのアクセストークンを取得する Web アプリも必要です。

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

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

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

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

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

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

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

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

Web API へのアクセスを許可するアプリケーションのアクセス許可を追加する

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

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

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

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

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

Web 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 です。
次のコマンドを実行して、アプリを起動します。
- .NET 6.0
- .NET 7.0
```
dotnet run
```
```
dotnet run --launch-profile https
```
次のような出力が表示されます。ポート番号を https://localhost:{port} URL に記録します。
```
... 
info: Microsoft.Hosting.Lifetime[14]
      Now listening on: https://localhost:{port}
...
```

Web API をテストする

「チュートリアル: ASP.NET Core プロジェクトを作成し、API を構成する」で作成した Web API (たとえば NewWebAPILocal) に移動し、フォルダーを開きます。
新しいターミナルウィンドウを開き、Web API プロジェクトが置いてあるフォルダーに移動します。

.NET 6.0
.NET 7.0

次のコマンドを実行して、アプリを起動します。
```
dotnet run
```

次のような出力が表示されます。ポート番号を https://localhost:{port} URL に記録します。
```
... 
info: Microsoft.Hosting.Lifetime[14]
      Now listening on: https://localhost:{port}
...
```

承認コードを要求する

承認コードフローは、クライアントがユーザーを /authorize エンドポイントにリダイレクトさせることから始まります。この要求では、クライアントは、ユーザーからの Forecast.Read のアクセス許可を要求します。

https://login.microsoftonline.com/{tenant_id}/oauth2/v2.0/authorize?client_id={web-app-calls-web-api_application_client_id}&response_type=code&redirect_uri=http://localhost&response_mode=query&scope=api://{web_API_application_client_id}/Forecast.Read

URL をコピーし、次のパラメーターを置き換えてブラウザーに貼り付けます。
- {tenant_id} は Web アプリ Directory (tenant) ID です。
- {web-app-calls-web-api_application_client_id} は、Web アプリの (web-app-calls-web-api) [概要] ペインのアプリケーション (クライアント) ID です。
- {web_API_application_client_id} は、Web API の (NewWebAPI1) [概要] ペインのアプリケーション (クライアント) ID です。
アプリが登録されている Microsoft Entra テナントでユーザーとしてサインインします。必要に応じて、アクセス時に求められる事項に同意します。
ブラウザーが http://localhost/ にリダイレクトされます。ブラウザーのナビゲーションバーを参照し、次の手順で使用する {authorization_code} をコピーします。 URL は、次のスニペットの形式になります。
```
http://localhost/?code={authorization_code}
```

承認コードと cURL を使用してアクセストークンを取得する

cURL を使用して、Microsoft ID プラットフォームからアクセストークンを要求できるようになりました。

次のスニペットで cURL コマンドをコピーします。かっこ内の値を、ターミナルに合わせて次のパラメーターに置き換えます。かっこは必ず削除してください。
- Bash
- Windows コマンドプロンプト
```
curl -X POST https://login.microsoftonline.com/{tenant_id}/oauth2/v2.0/token \
-d 'client_id={web-app-calls-web-api_application_client_id}' \
-d 'api://{web_API_application_client_id}/Forecast.Read' \
-d 'code={authorization_code}&session_state={web-app-calls-web-api_application_client_id}' \
-d 'redirect_uri=http://localhost' \
-d 'grant_type=authorization_code' \
-d 'client_secret={client_secret}'
```
```
curl -X POST https://login.microsoftonline.com/{tenant_id}/oauth2/v2.0/token ^
 -d "client_id={web-app-calls-web-api_application_client_id}" ^
 -d "api://{web_API_application_client_id}/Forecast.Read" ^
 -d "code={authorization_code}&session_state={web-app-calls-web-api_application_client_id}" ^
 -d "redirect_uri=http://localhost" ^
 -d "grant_type=authorization_code" ^
 -d "client_secret={client_secret}"
```
- {tenant_id} は Web アプリ Directory (tenant) ID です。
- client_id={web-app-calls-web-api_application_client_id} と session_state={web-app-calls-web-api_application_client_id} は、Web アプリの (web-app-calls-web-api) [概要] ペインのアプリケーション (クライアント) ID です。
- api://{web_API_application_client_id}/Forecast.Read は、Web API の (NewWebAPI1) [概要] ペインのアプリケーション (クライアント) ID です。
- code={authorization_code} は、「承認コードを要求する」で受信した承認コードです。これにより、cURL ツールはアクセストークンを要求できます。
- client_secret={client_secret} は、「クライアントシークレットを追加する」で記録したクライアントシークレットの値です。

cURL コマンドを実行します。正しく入力すると、次の出力のような JSON 応答が表示されます。

{
   "token_type": "Bearer",
   "scope": "api://{web_API_application_client_id}/Forecast.Read",
   "expires_in": 3600,
   "ext_expires_in": 3600,
   "access_token": "{access_token}"
}

アクセストークンを使用して Web API を呼び出す

前の cURL コマンドを実行すると、Microsoft ID プラットフォームによってアクセストークンが提供されました。取得したトークンを HTTP 要求のベアラーとして使用して、Web API を呼び出せるようになりました。

Web API を呼び出すには、次の cURL コマンドをコピーし、かっこ内の次の値を置き換えて、ターミナルに貼り付けます。
```
curl -X GET https://localhost:{port}/weatherforecast -ki \
-H 'Content-Type: application/json' \
-H "Authorization: Bearer {access_token}"
```
- {access_token} 前のセクションの JSON 出力から記録されたアクセストークン値。
- {port} ターミナルで API を実行するときに記録された Web API からのポート番号。 https ポート番号であることを確認します。

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

HTTP/2 200
content-type: application/json; charset=utf-8
date: Day, DD Month YYYY HH:MM:SS
server: Kestrel
[{"date":"YYYY-MM-DDTHH:MM:SS","temperatureC":36,"summary":"Hot","temperatureF":96},{"date":"YYYY-MM-DDTHH:MM:SS","temperatureC":43,"summary":"Warm","temperatureF":109},{"date":"YYYY-MM-DDTHH:MM:SS","temperatureC":18,"summary":"Warm","temperatureF":64},{"date":"YYYY-MM-DDTHH:MM:SS","temperatureC":50,"summary":"Chilly","temperatureF":121},{"date":"YYYY-MM-DDTHH:MM:SS","temperatureC":3,"summary":"Bracing","temperatureF":37}]

次の手順

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

次の方法で共有

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

前提条件

Microsoft ID プラットフォームにアプリケーションを登録する

Web API を登録する

API を公開する

Web アプリを登録する

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

Web API へのアクセスを許可するアプリケーションのアクセス許可を追加する

Web API をテストする

Web API をテストする

承認コードを要求する

承認コードと cURL を使用してアクセストークンを取得する

アクセストークンを使用して Web API を呼び出す

次の手順

フィードバック

その他のリソース

次の方法で共有

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

前提条件

Microsoft ID プラットフォームにアプリケーションを登録する

Web API を登録する

API を公開する

Web アプリを登録する

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

Web API へのアクセスを許可するアプリケーションのアクセス許可を追加する

Web API をテストする

Web API をテストする

承認コードを要求する

承認コードと cURL を使用してアクセス トークンを取得する

アクセス トークンを使用して Web API を呼び出す

次の手順

フィードバック

その他のリソース

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

承認コードと cURL を使用してアクセストークンを取得する

アクセストークンを使用して Web API を呼び出す