サンプル Node.js デーモン アプリケーションで API を呼び出す
このガイドでは、サンプルの Node.js デーモン アプリケーションを使用して、デーモン アプリが Web API を呼び出すためのアクセス トークンを取得する方法を示します。
デーモン アプリケーションは (ユーザーの代わりではなく) 自身の代わりにトークンを取得します。 デーモン アプリケーションには独自の ID が必要なため、ユーザーが対話することはできません。 この種のアプリケーションは、アプリケーション ID を使用し、アプリケーション ID、資格情報 (パスワードまたは証明書)、アプリケーション ID の URI を外部 ID に提示して、アクセス トークンを要求します。
デーモン アプリでは、標準の OAuth 2.0 クライアント資格情報付与が使用されます。 トークンを取得するプロセスを簡略化するために、この記事で使用するサンプルでは Microsoft Authentication Library for Node (MSAL Node) を使用します。
前提条件
- Visual Studio Code、または別のコード エディター。
- Node.js。
- .NET 7.0 以降。
- 外部テナント。 作成するには、次のいずれかの方法を選択します。
- (推奨) Microsoft Entra 外部 ID 拡張機能を使用して、Visual Studio Code 内で直接外部テナントを設定します。
- Microsoft Entra 管理センターで新しい外部テナントを作成します。
デーモン アプリケーションと Web API を登録する
この手順では、デーモンと Web API アプリケーションの登録を作成し、Web API のスコープを指定します。
Web API アプリケーションを登録する
アプリケーション開発者以上として Microsoft Entra 管理センターにサインインします。
複数のテナントにアクセスできる場合、上部のメニューの [設定] アイコン を使用し、[ディレクトリとサブスクリプション] メニューから外部テナントに切り替えます。
[ID]>[アプリケーション]>[アプリの登録] を参照します。
[+ 新規登録] を選択します。
表示される [アプリケーションの登録] ページで、アプリケーションの登録情報を入力します。
[名前] セクションで、アプリのユーザーに表示されるわかりやすいアプリケーション名 (ciam-ToDoList-api など) を入力します。
[サポートされているアカウントの種類] で、 [この組織のディレクトリ内のアカウントのみ] を選択します。
[登録] を選択して、アプリケーションを作成します。
登録が完了すると、アプリケーションの [概要] ペインが表示されます。 アプリケーションのソース コードで使用するディレクトリ (テナント) ID とアプリケーション (クライアント) ID を記録します。
アプリ ロールを構成する
API は、クライアント アプリが自身としてアクセス トークンを取得できるように、アプリケーションに対して少なくとも 1 つのアプリ ロール (アプリケーションのアクセス許可とも呼ばれます) を発行する必要があります。 アプリケーションのアクセス許可は、クライアント アプリケーションが自身として正常に認証できるようにして、ユーザーをサインインさせる必要がないようにする場合に、API が発行するアクセス許可の種類です。 アプリケーションのアクセス許可を発行するには、次の手順に従います。
[アプリの登録] ページから、作成したアプリケーション (ciam-ToDoList-api など) を選択して、その [概要] ページを開きます。
[管理] で、[アプリ ロール] を選択します。
[アプリ ロールの作成] を選択し、次の値を入力し、[適用] を選択して変更を保存します:
プロパティ 先頭値 表示名 ToDoList.Read.All Allowed member types (許可されるメンバーの種類) アプリケーション 値 ToDoList.Read.All 説明 'ToDoListApi' を使用して、アプリがすべてのユーザーの ToDo リストを読むことができるようにする もう一度 [アプリ ロールの作成] を選択し、2 番目のアプリ ロールに次の値を入力し、[適用] を選択して変更を保存します:
プロパティ 先頭値 表示名 ToDoList.ReadWrite.All Allowed member types (許可されるメンバーの種類) アプリケーション 値 ToDoList.ReadWrite.All 説明 'ToDoListApi' を使用して、アプリがすべてのユーザーの ToDo リストを読み書きできるようにする
省略可能な要求の構成
オプションの idtyp 要求を使用すると、Web API がトークンがアプリ トークンなのかアプリ + ユーザー トークンなのかを判別しやすくなります。 scp および roles 要求の組み合わせは同じ目的に使用できますが、idtyp 要求の使用は、アプリ トークンとアプリ + ユーザー トークンを区別する最も簡単な方法です。 たとえば、トークンがアプリ専用トークンの場合、この要求の値は app です。
デーモン アプリを登録する
Microsoft Entra を使用してアプリケーションでユーザーをサインインできるようにするには、作成するアプリケーションを Microsoft Entra 外部 ID に認識させる必要があります。 アプリの登録によって、アプリと Microsoft Entra の間に信頼関係が確立されます。 アプリケーションを登録すると、外部 ID によって、アプリケーション (クライアント) ID と呼ばれる一意識別子が生成されます。これは、認証要求を作成するときにアプリを識別するために使用される値です。
Microsoft Entra 管理センターにアプリを登録する方法を次の手順に示します。
アプリケーション開発者以上として Microsoft Entra 管理センターにサインインします。
複数のテナントにアクセスできる場合、上部のメニューの [設定] アイコン を使用し、[ディレクトリとサブスクリプション] メニューから外部テナントに切り替えます。
[ID]>[アプリケーション]>[アプリの登録] を参照します。
[+ 新規登録] を選択します。
表示される [アプリケーションの登録] ページで、次のようにします。
- アプリのユーザーに表示されるわかりやすいアプリケーションの [名前] を入力します (例: ciam-client-app)。
- [サポートされているアカウントの種類] で、 [この組織のディレクトリ内のアカウントのみ] を選択します。
[登録] を選択します。
登録が成功すると、アプリケーションの [概要] ペインが表示されます。 アプリケーションのソース コードで使用するアプリケーション (クライアント) ID を記録します。
クライアント シークレットの作成
登録したアプリケーションに対してクライアント シークレットを作成します。 Web アプリケーションでは、トークンを要求するときに、このクライアント シークレットを使って自身の ID を証明します。
- [アプリの登録] ページで、作成したアプリケーション ("ciam-client-app" など) を選択して、その [概要] ページを開きます。
- [管理] で、[証明書とシークレット] を選択します。
- [新しいクライアント シークレット] を選択します。
- [説明] ボックスにクライアント シークレットの説明を入力します (例、ciam app client secret)。
- [有効期限] で、シークレットが (組織のセキュリティ規則に基づいて) 有効な期間を選択してから、[追加] を選択します。
- シークレットの値を記録します。 この値は、後の手順での構成に使用します。 シークレットの値は再表示されず、[証明書とシークレット] から移動した後はどのような手段でも取得できません。 必ず記録しておくようにしてください。
デーモン アプリに API のアクセス許可を付与する
[アプリの登録] ページから、作成したアプリケーション (ciam-client-app など) を選択します。
[管理] の下にある [API のアクセス許可] を選択します。
[構成されたアクセス許可] の下で [アクセス許可の追加] を選択します。
[所属する組織で使用している API] タブを選択します。
API の一覧で、API (ciam-ToDoList-api など) を選択します。
[アプリケーションのアクセス許可] オプションを選択します。 このアプリは、ユーザーの代理としてではなくそれ自体がサインインするものであるため、このオプションを選びます。
アクセス許可の一覧から、TodoList.Read.All と ToDoList.ReadWrite.All を選択します (必要に応じて検索ボックスを使用してください)。
[アクセス許可の追加] ボタンを選択します
この時点で、アクセス許可が正しく割り当てられます。 ただし、デーモン アプリはユーザーが対話することを許可しないため、ユーザー自身がこれらのアクセス許可に同意することはできません。 この問題に対処するには、管理者が次のように、テナント内のすべてのユーザーに代わってこれらのアクセス許可に同意する必要があります。
- [<ご使用のテナント名> に管理者の同意を与えます] を選択してから、[はい] を選択します。
- [最新の情報に更新] を選択し、両方のアクセス許可の [状態] に "<テナント名> に付与されました" と表示されていることを確認します。
サンプル デーモン アプリケーションと Web API を複製またはダウンロードする
サンプル アプリケーションを取得するには、GitHub から複製するか、.zip ファイルとしてダウンロードします。
サンプルをクローンするには、コマンド プロンプトを開き、プロジェクトを作成する場所に移動し、次のコマンドを入力します。
git clone https://github.com/Azure-Samples/ms-identity-ciam-javascript-tutorial.git
または、サンプルの .zip ファイルをダウンロードした後、名前の長さが 260 文字未満となるファイル パスへそれを展開します。
プロジェクトの依存関係をインストールする
コンソール ウィンドウを開き、Node.js サンプル アプリが含まれるディレクトリに移動します。
cd 2-Authorization\3-call-api-node-daemon\App
次のコマンドを実行してアプリの依存関係をインストールします。
npm install && npm update
サンプル デーモン アプリと API を構成する
クライアント Web アプリのサンプルでアプリの登録を使用するには、次の手順を実行します。
コード エディターで、
App\authConfig.js
ファイルを開きます。次のプレースホルダーを見つけ、対応する操作を行います。
Enter_the_Application_Id_Here
。これを、前に登録したデーモン アプリのアプリケーション (クライアント) ID に置き換えます。Enter_the_Tenant_Subdomain_Here
。これを、ディレクトリ (テナント) サブドメインに置き換えます。 たとえば、テナントのプライマリ ドメインがcontoso.onmicrosoft.com
の場合は、contoso
を使用します。 テナント名がない場合は、テナントの詳細を読み取る方法を確認してください。Enter_the_Client_Secret_Here
。これを、前にコピーしたデーモン アプリのシークレット値に置き換えます。Enter_the_Web_Api_Application_Id_Here
。これを、前にコピーした Web API のアプリケーション (クライアント) ID に置き換えます。
Web API サンプルでアプリの登録を使用するには:
コード エディターで、
API\ToDoListAPI\appsettings.json
ファイルを開きます。次のプレースホルダーを見つけます。
Enter_the_Application_Id_Here
を、コピーした Web API のアプリケーション (クライアント) ID に置き換えます。Enter_the_Tenant_Id_Here
を、先ほどコピーしたディレクトリ (テナント) ID に置き換えます。Enter_the_Tenant_Subdomain_Here
を、ディレクトリ (テナント) サブドメインに置き換えます。 たとえば、テナントのプライマリ ドメインがcontoso.onmicrosoft.com
の場合は、contoso
を使用します。 テナント名がない場合は、テナントの詳細を読み取る方法を確認してください。
サンプル デーモン アプリと API を実行およびテストする
コンソール ウィンドウを開き、次のコマンドを使用して Web API を実行します。
cd 2-Authorization\3-call-api-node-daemon\API\ToDoListAPI dotnet run
次のコマンドを使用して Web アプリ クライアントを実行します。
2-Authorization\3-call-api-node-daemon\App node . --op getToDos
デーモン アプリと Web API が正常に実行された場合は、コンソール ウィンドウに次のような JSON 配列が表示されます。
{ "id": 1, "owner": "3e8....-db63-43a2-a767-5d7db...", "description": "Pick up grocery" }, { "id": 2, "owner": "c3cc....-c4ec-4531-a197-cb919ed.....", "description": "Finish invoice report" }, { "id": 3, "owner": "a35e....-3b8a-4632-8c4f-ffb840d.....", "description": "Water plants" }
しくみ
Node.js アプリでは、OAuth 2.0 クライアント資格情報付与を使用して、ユーザーではなく、自身のためのアクセス トークンを取得します。 アプリが要求するアクセス トークンには、ロールとして表されたアクセス許可が含まれています。 クライアント資格情報フローは、アプリケーション トークンに対するユーザー スコープの代わりにこのアクセス許可のセットを使用します。 ここまでで、Web API にこれらのアプリケーションのアクセス許可を公開し、デーモン アプリにそれらを付与しました。
API 側では、Web API は、アクセス トークンに必要なアクセス許可 (アプリケーションのアクセス許可) が含まれていることを確認する必要があります。 Web API は、必要なアクセス許可が含まれていないアクセス トークンを受け付けることはできません。
データへのアクセス
Web API エンドポイントは、ユーザーとアプリケーションの両方からの呼び出しを受け付けるように準備されている必要があります。 そのため、それに応じて各要求に応答する方法が存在する必要があります。 たとえば、委任されたアクセス許可またはスコープによるユーザーからの呼び出しでは、ユーザーのデータ Todo リストを受信します。 これに対して、アプリケーションのアクセス許可またはロールによるアプリケーションからの呼び出しでは、Todo リスト全体を受信する可能性があります。 ただし、この記事では、アプリケーションの呼び出ししか行っていないため、委任されたアクセス許可またはスコープを構成する必要はありません。