サービス プリンシパルを使用したローカル開発時に Azure サービスに対して JavaScript アプリを認証する

クラウド アプリケーションを作成する場合、開発者はローカル ワークステーションでアプリケーションをデバッグおよびテストする必要があります。 ローカル開発時に開発者のワークステーションでアプリケーションを実行する場合でも、アプリで使用されるすべての Azure サービスに対して認証する必要があります。 この記事では、ローカル開発時に使用する専用のアプリケーション サービス プリンシパル オブジェクトを設定する方法について説明します。

ローカル開発用の専用アプリケーション サービス プリンシパルを使用すると、アプリ開発時に最小限の特権の原則に従うことができます。 アクセス許可のスコープは開発時にアプリに必要なものだけに設定されるため、別のアプリで使用することを目的とした Azure リソースにアプリ コードが誤ってアクセスすることはありません。 また、この方法では、開発環境でアプリが過剰な特権を持っていたために、アプリが運用環境に移動されたときにバグが発生するのを防ぐことができます。

アプリが Azure に登録されると、アプリケーション サービス プリンシパルがアプリ用に設定されます。 ローカル開発用にアプリを登録する場合は、次の手順を実行することをお勧めします。

• アプリで作業する開発者ごとに個別のアプリ登録を作成します。 この方法では、ローカル開発時に使用する各開発者に対して個別のアプリケーション サービス プリンシパルが作成され、開発者が 1 つのアプリケーション サービス プリンシパルの資格情報を共有する必要がなくなります。
• アプリごとに個別のアプリ登録を作成します。 これにより、アプリのアクセス許可のスコープがアプリに必要なものだけに設定されます。

ローカル開発時に、環境変数はアプリケーション サービス プリンシパルの ID で設定されます。 Azure SDK for JavaScript では、これらの環境変数を読み取り、この情報を使用して、必要な Azure リソースに対してアプリが認証されます。

1 - Azure にアプリケーションを登録する

アプリケーション サービス プリンシパル オブジェクトは、Azure でアプリの登録を使用して作成されます。 サービス プリンシパルは、Azure portal または Azure CLI を使用して作成できます。

Azure Portal

Azure portal にサインインして、次の手順を実行します。

手順	Screenshot
Azure portal で、次の操作を行います。 Azure portal の上部にある検索バーに「アプリの登録」と入力します。 検索バーの下に表示されるメニューの [サービス] の下にある [アプリの登録] と書かれた項目を選択します。
[アプリの登録] ページで、[+ 新規登録] を選択します。
[アプリケーションの登録] ページで、次のようにフォームに入力します。 名前 → Azure でのアプリ登録の名前を入力します。 この名前には、アプリ名、アプリ登録の対象となるユーザー、このアプリの登録がローカル開発で使用されることを示す識別子 ("dev" など) を含めるようにすることをお勧めします。 サポートされているアカウントの種類 → この組織のディレクトリ内のアカウントのみ。 [登録] を選択してアプリを登録し、アプリケーション サービス プリンシパルを作成します。
お使いのアプリの [アプリの登録] ページで、次の操作を行います。 アプリケーション (クライアント) ID → ローカル開発時にアプリが Azure にアクセスするために使用するアプリ ID です。 この値は、後の手順で必要になるので、テキスト エディターで一時的な場所にコピーします。 ディレクトリ (テナント) ID → この値は、Azure に対して認証するときにもアプリで必要になります。 この値も後の手順で必要になるので、テキスト エディターで一時的な場所にコピーします。 クライアント資格情報 → アプリが Azure に対して認証して Azure サービスを使用する前に、アプリのクライアント資格情報を設定する必要があります。 [証明書またはシークレットの追加] を選択して、アプリの資格情報を追加します。
[証明書とシークレット] ページで、[+ 新しいクライアント シークレット] を選びます。
[クライアント シークレットの追加] ダイアログがページの右側から表示されます。 このダイアログで、次の操作を行います。 説明 → 現在の値を入力します。 有効期限 → "24 か月"の値を選択します。 [追加] を選択してシークレットを追加します。
[証明書とシークレット] ページに、クライアント シークレットの値が表示されます。 この値は、後の手順で必要になるので、テキスト エディターで一時的な場所にコピーします。 重要: この値が表示されるのはこのタイミングだけです。 このページを終了または更新すると、この値を再度表示できなくなります。 このクライアント シークレットを無効にすることなく、さらにクライアント シークレットを追加できますが、この値は再度表示されません。

Azure CLI

Azure CLI コマンドは、Azure Cloud Shell で、または Azure CLI がインストールされているワークステーション上で実行できます。

まず、az ad sp create-for-rbac コマンドを使用して、アプリの新しいサービス プリンシパルを作成します。 これは、アプリのアプリ登録を同時に作成します。

az ad sp create-for-rbac --name {service-principal-name}

このコマンドの出力は、次の JSON オブジェクトのようになります。 サービス プリンシパルのクライアント シークレット (パスワード) が表示されるのはこの場所だけで、今後の手順でこれらの値が必要になるので、テキスト エディターでこの出力を一時ファイルにコピーすることをお勧めします。 ただし必要に応じて、サービス プリンシパルや既存のパスワードを無効にせずに、後で新しいパスワードを追加できます。

{
  "appId": "00000000-0000-0000-0000-000000000000",
  "displayName": "{service-principal-name}",
  "password": "abcdefghijklmnopqrstuvwxyz",
  "tenant": "11111111-1111-1111-1111-111111111111"
}

2 - ローカル開発用の Microsoft Entra セキュリティ グループを作成する

通常、アプリケーションで作業する開発者は複数いるため、個々のサービス プリンシパル オブジェクトにロールを割り当てるのではなく、Microsoft Entra グループを作成して、アプリがローカル開発で必要とするロール (アクセス許可) をカプセル化することをお勧めします。 これには次のような利点があります。

• ロールはグループ レベルで割り当てられるため、すべての開発者に同じロールが割り当てられることが保証されます。
• アプリに新しいロールが必要な場合は、アプリの Microsoft Entra グループに追加するだけで済みます。
• 新しい開発者がチームに参加する場合は、アプリで作業するための適切なアクセス許可が開発者に与えられるように、その開発者用に新しいアプリケーション サービス プリンシパルを作成してグループに追加します。

Azure Portal

手順	Screenshot
ページの上部にある検索ボックスに「Microsoft Entra ID」と入力し、サービスの下から Microsoft Entra ID を選択して、Azure Portal の [Microsoft Entra ID] ページに移動します。
[Microsoft Entra ID] ページで、左側のメニューから [グループ] を選択します。
[すべてグループ] ページで、[新しいグループ] を選択します。
[新しいグループ] ページで、次の操作を行います。 グループの種類 → セキュリティ グループ名 →通常はアプリケーション名から作成される、セキュリティ グループの名前です。 また、グループの名前に "local-dev" のような文字列を含め、グループの目的も示すと便利です。 グループの説明 → グループの目的の説明。 [メンバー] の下の [メンバーが選択されていません] リンクを選択して、グループにメンバーを追加します。
[メンバーの追加] ダイアログ ボックスで、次の操作を行います。 検索ボックスを使用して、一覧で、プリンシパル名の一覧をフィルター処理します。 このアプリのローカル開発用のアプリケーション サービス プリンシパルを選択します。 オブジェクトを選択すると、灰色表示され、ダイアログの下部にある [選択された項目] リストに移動します。 終わったら、[選択] ボタンを選択します。
[新規グループ] ページに戻り、[作成] を選択して、グループを作成します。 グループが作成され、[すべてのグループ] ページに戻ります。 グループが表示されるまでに最大 30 秒かかる場合があり、Azure portal でのキャッシュのためにページの更新が必要になる場合があります。

Azure CLI

Microsoft Entra ID でグループを作成するには、az ad group create コマンドを使用します。 --display-name パラメーターと --main-nickname パラメーターは必須です。 グループに指定する名前は、アプリケーションの名前に基づく必要があります。 また、グループの名前に "local-dev" のような語句を含め、グループの目的も示すと便利です。

az ad group create \
    --display-name MyDisplay \
    --mail-nickname MyDisplay  \
    --description \<group-description>

グループにメンバーを追加するには、アプリケーション サービス プリンシパルのオブジェクト ID が必要です。これは、アプリケーション ID とは異なります。 az ad sp list を使って、使用可能なサービス プリンシパルを一覧表示します。 --filter パラメーター コマンドは OData スタイル フィルターを受け取り、表示されているリストをフィルター処理するために使用できます。 --query パラメーターでは、必要な列のみに制限されます。

az ad sp list \
    --filter "startswith(displayName, 'msdocs')" \
    --query "[].{objectId:objectId, displayName:displayName}" \
    --output table

その後、az ad group member add コマンドを使用して、グループにメンバーを追加できます。

az ad group member add \
    --group \<group-name> \
    --member-id \<object-id>  \

3 - アプリケーションにロールを割り当てる

次に、アプリで必要なリソースに対して必要なロール (アクセス許可) を決定し、それらのロールをアプリに割り当てる必要があります。 この例では、手順 2 で作成した Microsoft Entra グループにロールが割り当てられます。 ロールは、リソース、リソース グループ、またはサブスクリプション スコープで割り当てることができます。 次に、ほとんどのアプリケーションがすべてのAzureリソースを1つのリソースグループにグループ化するため、リソースグループスコープでロールを割り当てる例を示します。

Azure Portal

手順	Screenshot
Azure portal の上部にある検索ボックスを使用してリソース グループ名を検索し、アプリケーションのリソース グループを見つけます。 ダイアログ ボックスの [リソース グループ] 見出しの下にあるリソース グループ名を選択して、リソース グループに移動します。
リソース グループのページで、左側のメニューから [アクセス制御 (IAM)] を選択します。
[アクセス制御 (IAM)] ページで、次の操作を行います。 [ロールの割り当て] タブを選択します。 上部のメニューから [+ 追加] を選択し、次に結果のドロップダウン メニューから [ロールの割り当ての追加] を選択します。
[ロールの割り当ての追加] ページには、リソース グループで割り当てることができるすべてのロールが一覧表示されます。 検索ボックスを使用して、より管理しやすいサイズにリストをフィルター処理します。 この例では、Storage BLOB ロールをフィルター処理する方法を示します。 割り当てるロールを選択します。 [次へ] を選択して、次の画面に進みます。
次の [ロールの割り当ての追加] ページでは、ロールを割り当てるユーザーを指定できます。 [アクセスの割り当て先] で、[ユーザー、グループ、またはサービス プリンシパル] を選択します。 [メンバー] で [+ メンバーの選択] を選択する Azure portal の右側でダイアログ ボックスが開きます。
[メンバーの選択] ダイアログで、次の操作を行います。 [選択] テキスト ボックスを使用して、サブスクリプション内のユーザーとグループの一覧をフィルター処理できます。 必要に応じて、アプリ用に作成したローカル開発 Microsoft Entra グループの最初の数文字を入力します。 アプリケーションに関連付けられているローカル開発 Microsoft Entra グループを選択します。 ダイアログの下部にある [選択] を選択して続行します。
Microsoft Entra グループが、[ロールの割り当ての追加] 画面に選択済みとして表示されます。 [レビューと割り当て] を選択して最終ページに移動し、もう一度レビューと割り当てを行ってプロセスを完了します。

Azure CLI

アプリケーション サービス プリンシパルには、az role assignment create コマンドを使用して Azure のロールが割り当てられます。

az role assignment create --assignee "{appId}" \
    --scope /subscriptions/"{subscriptionName}" \
    --role "{roleName}" \
    --resource-group "{resourceGroupName}"

サービス プリンシパルを割り当てることができるロール名を取得するには、az role definition list コマンドを使用します。

az role definition list \
    --query "sort_by([].{roleName:roleName, description:description}, &roleName)" \
    --output table

たとえば、msdocs-sdk-auth-example リソース グループ内のすべてのストレージ アカウントに対する Azure Storage の BLOB コンテナーおよびデータの読み取り、書き込み、削除のアクセス権を、appId が 00000000-0000-0000-0000-000000000000 のアプリケーション サービス プリンシパルに許可するには、次のコマンドを使用して、アプリケーション サービス プリンシパルを Storage BLOB データ共同作成者ロールに割り当てます。

az role assignment create --assignee "00000000-0000-0000-0000-000000000000" \
    --scope /subscriptions/"Storage Blob Data Subscriber" \
    --role "Storage Blob Data Contributor" \
    --resource-group "msdocs-sdk-auth-example"

Azure CLI を使用してリソースまたはサブスクリプション レベルでアクセス許可を割り当てる方法については、「Azure CLI を使用して Azure ロールを割り当てる」を参照してください。

4 - ローカル開発の環境変数を設定する

DefaultAzureCredential オブジェクトは、一連の環境変数ランタイムでサービス プリンシパル情報を検索します。 ほとんどの開発者は複数のアプリケーションで作業するため、dotenv などのパッケージを使用して、開発時にアプリケーションのディレクトリに格納されている .env ファイルから環境にアクセスすることをお勧めします。 このようにすると、Azure に対してアプリケーションを認証するために使用される環境変数のスコープが設定され、このアプリケーションのみで使用できます。

.env ファイルには Azure のアプリケーション シークレット キーが含まれているので、ソース管理にチェックインされることはありません。 JavaScript 用の標準の .gitignore ファイルでは、チェックインから .env ファイルが自動的に除外されます。

dotenv パッケージを使用するには、まずアプリケーションにパッケージをインストールします。

npm install dotenv

次に、アプリケーションのルート ディレクトリに .env ファイルを作成します。 次のように、アプリ登録プロセスから取得した値を使用して環境変数の値を設定します。

• AZURE_CLIENT_ID → アプリ ID の値です。
• AZURE_TENANT_ID → テナント ID の値です。
• AZURE_CLIENT_SECRET →アプリ用に生成されたパスワード/資格情報。

AZURE_CLIENT_ID=00000000-0000-0000-0000-000000000000
AZURE_TENANT_ID=11111111-1111-1111-1111-111111111111
AZURE_CLIENT_SECRET=abcdefghijklmnopqrstuvwxyz

最後に、アプリケーションのスタートアップ コードで、dotenv ライブラリを使用して、起動時に .env ファイルから環境変数を読み取ります。

import 'dotenv/config'

5 - アプリケーションに DefaultAzureCredential を実装する

Azure SDK クライアント オブジェクトを Azure に対して認証するには、アプリケーションで DefaultAzureCredential パッケージから @azure/identity クラスを使用する必要があります。 このシナリオでは、DefaultAzureCredential が環境変数AZURE_CLIENT_ID、AZURE_TENANT_ID を検出し、AZURE_CLIENT_SECRET が設定され、これら変数を読み取り Azure に接続するためのアプリケーション サービス プリンシパル情報を取得します。

まず、@azure/identity パッケージを アプリケーションに追加します。

npm install @azure/identity

次に、アプリで Azure SDK クライアント オブジェクトを作成する JavaScript コードの場合、次のことが必要になります。

1. DefaultAzureCredential モジュールから @azure/identity クラスをインポートします。
2. DefaultAzureCredential オブジェクトを作成します。
3. Azure SDK クライアント オブジェクト コンストラクターに DefaultAzureCredential オブジェクトを渡します。

この例を次のコード セグメントに示します。

// Azure authentication dependency
import { DefaultAzureCredential } from '@azure/identity';

// Azure resource management dependency
import { SubscriptionClient } from "@azure/arm-subscriptions";

// Acquire credential
const tokenCredential = new DefaultAzureCredential();

async function listSubscriptions() {
  try {

    // use credential to authenticate with Azure SDKs
    const client = new SubscriptionClient(tokenCredential);

    // get details of each subscription
    for await (const item of client.subscriptions.list()) {
      const subscriptionDetails = await client.subscriptions.get(
        item.subscriptionId
      );
      /* 
        Each item looks like:
      
        {
          id: '/subscriptions/123456',
          subscriptionId: '123456',
          displayName: 'YOUR-SUBSCRIPTION-NAME',
          state: 'Enabled',
          subscriptionPolicies: {
            locationPlacementId: 'Internal_2014-09-01',
            quotaId: 'Internal_2014-09-01',
            spendingLimit: 'Off'
          },
          authorizationSource: 'RoleBased'
        },
    */
      console.log(subscriptionDetails);
    }
  } catch (err) {
    console.error(JSON.stringify(err));
  }
}

listSubscriptions()
  .then(() => {
    console.log("done");
  })
  .catch((ex) => {
    console.log(ex);
  });

DefaultAzureCredential では、アプリ用に構成された認証メカニズムを自動的に検出し、Azure に対してアプリを認証するために必要なトークンを取得します。 アプリケーションで複数の SDK クライアントを使用する場合は、各 SDK クライアント オブジェクトで同じ資格情報オブジェクトを使用できます。