Share via

サンプル Node.js デーモン アプリケーションで API を呼び出す

  • [アーティクル]

このガイドでは、サンプル Node.js デーモン アプリケーションを使用して、デーモン アプリで Web API を呼び出すためのトークンを取得する方法を示します。 Microsoft Entra で Web API を保護します。

デーモン アプリケーションは (ユーザーの代わりではなく) 自身の代わりにトークンを取得します。 デーモン アプリケーションには独自の ID が必要なため、ユーザーが対話することはできません。 この種のアプリケーションは、アプリケーション ID を使用し、アプリケーション ID、資格情報 (パスワードまたは証明書)、アプリケーション ID の URI を外部 ID に提示して、アクセス トークンを要求します。

デーモン アプリでは、標準の OAuth 2.0 クライアント資格情報付与が使用されます。 トークンを取得するプロセスを簡略化するために、この記事で使用するサンプルでは Microsoft Authentication Library for Node (MSAL Node) を使用します。

前提条件

デーモン アプリケーションと Web API を登録する

この手順では、デーモンと Web API アプリケーションの登録を作成し、Web API のスコープを指定します。

Web API アプリケーションを登録する

  1. アプリケーション開発者以上として Microsoft Entra 管理センターにサインインします。

  2. 複数のテナントにアクセスできる場合、上部のメニューの [設定] アイコン を使用し、[ディレクトリとサブスクリプション] メニューから外部テナントに切り替えます。

  3. [ID]>[アプリケーション]>[アプリの登録] を参照します。

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

  5. 表示される [アプリケーションの登録] ページで、アプリケーションの登録情報を入力します。

    1. [名前] セクションで、アプリのユーザーに表示されるわかりやすいアプリケーション名 (ciam-ToDoList-api など) を入力します。

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

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

  7. 登録が完了すると、アプリケーションの [概要] ペインが表示されます。 アプリケーションのソース コードで使用するディレクトリ (テナント) ID とアプリケーション (クライアント) ID を記録します。

アプリ ロールを構成する

API は、クライアント アプリが自身としてアクセス トークンを取得できるように、アプリケーションに対して少なくとも 1 つのアプリ ロール (アプリケーションのアクセス許可とも呼ばれます) を発行する必要があります。 アプリケーションのアクセス許可は、クライアント アプリケーションが自身として正常に認証できるようにして、ユーザーをサインインさせる必要がないようにする場合に、API が発行するアクセス許可の種類です。 アプリケーションのアクセス許可を発行するには、次の手順に従います。

  1. [アプリの登録] ページから、作成したアプリケーション (ciam-ToDoList-api など) を選択して、その [概要] ページを開きます。

  2. [管理] で、[アプリ ロール] を選択します。

  3. [アプリ ロールの作成] を選択し、次の値を入力し、[適用] を選択して変更を保存します:

    プロパティ 先頭値
    表示名 ToDoList.Read.All
    Allowed member types (許可されるメンバーの種類) アプリケーション
    値 ToDoList.Read.All
    説明 'ToDoListApi' を使用して、アプリがすべてのユーザーの ToDo リストを読むことができるようにする

  4. もう一度 [アプリ ロールの作成] を選択し、2 番目のアプリ ロールに次の値を入力し、[適用] を選択して変更を保存します:

    プロパティ 先頭値
    表示名 ToDoList.ReadWrite.All
    Allowed member types (許可されるメンバーの種類) アプリケーション
    値 ToDoList.ReadWrite.All
    説明 'ToDoListApi' を使用して、アプリがすべてのユーザーの ToDo リストを読み書きできるようにする

省略可能な要求の構成

Microsoft ID によって返されるトークンは、要求するクライアントによる最適なパフォーマンスを確保するために、小さく維持されます。 その結果、一部の要求が規定ではトークンに存在しなくなり、アプリケーションごとに特定して要求する必要があります。 このアプリには、トークンがアプリ トークンなのかアプリ + ユーザー トークンなのかを Web API が判断できるようにする、オプションの idtyp クレームを含めます。 scp およびロール要求の組み合わせは同じ目的に使用できますが、idtyp 要求の使用は、アプリ トークンとアプリ+ユーザー トークンを区別する最も簡単な方法です。 たとえば、トークンがアプリ専用トークンの場合、この要求の値は app です。

idtyp の省略可能な要求を構成するには、次の手順に従います:

  1. ciam-client-app などのオプションの要求を構成したい [アプリの登録] ページから、その [概要] ページを開きます。

  2. [管理] で、 [トークン構成] を選択します。

  3. [省略可能な要求を追加] を選択します。

  4. [トークンの種類] で、[アクセス] を選択します。

  5. オプションの要求 [idtyp] を選択します。

  6. [追加] を選択して変更を保存します。

デーモン アプリを登録する

Microsoft Entra を使用してアプリケーションでユーザーをサインインできるようにするには、作成するアプリケーションを Microsoft Entra 外部 ID に認識させる必要があります。 アプリの登録によって、アプリと Microsoft Entra の間に信頼関係が確立されます。 アプリケーションを登録すると、外部 ID によって、アプリケーション (クライアント) ID と呼ばれる一意識別子が生成されます。これは、認証要求を作成するときにアプリを識別するために使用される値です。

Microsoft Entra 管理センターにアプリを登録する方法を次の手順に示します。

  1. アプリケーション開発者以上として Microsoft Entra 管理センターにサインインします。

  2. 複数のテナントにアクセスできる場合、上部のメニューの [設定] アイコン を使用し、[ディレクトリとサブスクリプション] メニューから外部テナントに切り替えます。

  3. [ID]>[アプリケーション]>[アプリの登録] を参照します。

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

  5. 表示される [アプリケーションの登録] ページで、次のようにします。

    1. アプリのユーザーに表示されるわかりやすいアプリケーションの [名前] を入力します (例: ciam-client-app)。
    2. [サポートされているアカウントの種類] で、 [この組織のディレクトリ内のアカウントのみ] を選択します。

  6. [登録] を選択します。

  7. 登録が成功すると、アプリケーションの [概要] ペインが表示されます。 アプリケーションのソース コードで使用するアプリケーション (クライアント) ID を記録します。

クライアント シークレットの作成

登録したアプリケーションに対してクライアント シークレットを作成します。 Web アプリケーションでは、トークンを要求するときに、このクライアント シークレットを使って自身の ID を証明します。

  1. [アプリの登録] ページで、作成したアプリケーション ("ciam-client-app" など) を選択して、その [概要] ページを開きます。
  2. [管理] で、[証明書とシークレット] を選択します。
  3. [新しいクライアント シークレット] を選択します。
  4. [説明] ボックスにクライアント シークレットの説明を入力します (例、ciam app client secret)。
  5. [有効期限] で、シークレットが (組織のセキュリティ規則に基づいて) 有効な期間を選択してから、[追加] を選択します。
  6. シークレットの値を記録します。 この値は、後の手順での構成に使用します。 シークレットの値は再表示されず、[証明書とシークレット] から移動した後はどのような手段でも取得できません。 必ず記録しておくようにしてください。

デーモン アプリに API のアクセス許可を付与する

  1. [アプリの登録] ページから、作成したアプリケーション (ciam-client-app など) を選択します。

  2. [管理] の下にある [API のアクセス許可] を選択します。

  3. [構成されたアクセス許可] の下で [アクセス許可の追加] を選択します。

  4. [所属する組織で使用している API] タブを選択します。

  5. API の一覧で、API (ciam-ToDoList-api など) を選択します。

  6. [アプリケーションのアクセス許可] オプションを選択します。 このオプションを選択するのは、アプリがユーザーではなく、それ自身としてサインインするためです。

  7. アクセス許可の一覧から、TodoList.Read.All と ToDoList.ReadWrite.All を選択します (必要に応じて検索ボックスを使用してください)。

  8. [アクセス許可の追加] ボタンを選択します

  9. この時点で、アクセス許可が正しく割り当てられます。 ただし、デーモン アプリはユーザーが対話することを許可しないため、ユーザー自身がこれらのアクセス許可に同意することはできません。 この問題に対処するには、管理者が次のように、テナント内のすべてのユーザーに代わってこれらのアクセス許可に同意する必要があります。

    1. [<ご使用のテナント名> に管理者の同意を与えます] を選択してから、[はい] を選択します。
    2. [最新の情報に更新] を選択し、両方のアクセス許可の [状態] に "<テナント名> に付与されました" と表示されていることを確認します。

サンプル デーモン アプリケーションと Web API を複製またはダウンロードする

サンプル アプリケーションを取得するには、GitHub から複製するか、.zip ファイルとしてダウンロードします。

  • サンプルをクローンするには、コマンド プロンプトを開き、プロジェクトを作成する場所に移動し、次のコマンドを入力します。

    git clone https://github.com/Azure-Samples/ms-identity-ciam-javascript-tutorial.git

  • .zip ファイルをダウンロードします。 名前の長さが 260 文字未満のファイル パスに抽出します。

プロジェクトの依存関係をインストールする

  1. コンソール ウィンドウを開き、Node.js サンプル アプリが含まれるディレクトリに移動します。

    cd 2-Authorization\3-call-api-node-daemon\App

  2. 次のコマンドを実行してアプリの依存関係をインストールします。

    npm install && npm update

サンプル デーモン アプリと API を構成する

クライアント Web アプリのサンプルでアプリの登録を使用するには、次の手順を実行します。

  1. コード エディターで、App\authConfig.js ファイルを開きます。

  2. 次のプレースホルダーを見つけ、対応する操作を行います。

    • 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 サンプルでアプリの登録を使用するには:

  1. コード エディターで、API\ToDoListAPI\appsettings.json ファイルを開きます。

  2. 次のプレースホルダーを見つけます。

    • Enter_the_Application_Id_Here を、コピーした Web API のアプリケーション (クライアント) ID に置き換えます。

    • Enter_the_Tenant_Id_Here を、先ほどコピーしたディレクトリ (テナント) ID に置き換えます。

    • Enter_the_Tenant_Subdomain_Here を、ディレクトリ (テナント) サブドメインに置き換えます。 たとえば、テナントのプライマリ ドメインが contoso.onmicrosoft.com の場合は、contoso を使用します。 テナント名がない場合は、テナントの詳細を読み取る方法を確認してください。

サンプル デーモン アプリと API を実行およびテストする

  1. コンソール ウィンドウを開き、次のコマンドを使用して Web API を実行します。

    cd 2-Authorization\3-call-api-node-daemon\API\ToDoListAPI
dotnet run

  2. 次のコマンドを使用して 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 リスト全体を受信する可能性があります。 ただし、この記事では、アプリケーションの呼び出ししか行っていないため、委任されたアクセス許可またはスコープを構成する必要はありません。

関連するコンテンツ