チュートリアル: 関数と Microsoft Graph (プレビュー) を使用してカスタムロールを割り当てる

[アーティクル]
12/13/2024

この記事では、関数を使用して Microsoft Graph に対してクエリを実行し、Entra ID グループメンバーシップに基づいてユーザーにカスタムロールを割り当てる方法について説明します。

このチュートリアルで学習する内容は次のとおりです。

静的 Web アプリをデプロイする。
Microsoft Entra アプリの登録を作成します。
Microsoft Entra ID を使ってカスタム認証を設定します。
ユーザーの Entra ID グループメンバーシップに対するクエリを実行し、カスタムロールの一覧を返すサーバーレス関数を構成します。

Note

このチュートリアルでは、関数を使用してロールを割り当てる必要があります。関数ベースのロール管理は、現在プレビュー段階です。このチュートリアルを完了するために必要なアクセス許可レベルは、"User.Read.All" です。

アプリの API には GetRoles という名前の関数があります。この関数では、ユーザーのアクセストークンを使用して、Microsoft Graph から Entra ID に対するクエリが実行されます。ユーザーがアプリに定義されている任意のグループのメンバーである場合は、対応するカスタムロールがユーザーにマップされます。

前提条件

要件	コメント
アクティブな Azure アカウント	アカウントがない場合は、無料でアカウントを作成することができます。
Microsoft Entra アクセス許可	Microsoft Entra アプリケーションを作成できる十分なアクセス許可が必要です。

GitHub リポジトリを作成する

ロール関数テンプレートに基づいてリポジトリを生成します。新しいリポジトリを作成するために、次の場所に移動します。

https://github.com/staticwebdev/roles-function/generate
リポジトリに my-custom-roles-app という名前をつけます。
[Create repository from template](テンプレートからリポジトリを作成する) を選択します。

静的 Web アプリを Azure にデプロイする

新しい Web ブラウザーウィンドウで、Azure portal を開きます。
左上隅の [リソースの作成] を選択します。
検索ボックスに、「静的 Web アプリ」と入力します。
Static Web Apps を選択します。
［作成］ を選択します

次の情報を使用して静的 Web アプリを構成します。

設定	値	Notes
サブスクリプション	Azure サブスクリプションを選択します。
Resource group	my custom-roles-app-group という名前の新しいグループを作成します。
名前	my-custom-roles-app
プランの種類	Standard	認証のカスタマイズと関数を使用したロールの割り当てには、Standard プランが必要です。
API のリージョン	最も近いリージョンを選択します。

[デプロイの詳細] セクションで、以下のようにします。

設定	値
source	[GitHub] を選択します。
組織	リポジトリを生成した組織を選択します。
リポジトリ	my-custom-roles-app を選択します。
[Branch]\(ブランチ)	[main](メイン) を選択します。

[ビルドの詳細] セクションで、このアプリの構成の詳細を追加します。

設定	値	メモ
ビルドのプリセット	[カスタム] を選択します。
アプリの場所	「/frontend」と入力します。	このフォルダーには、フロントエンドアプリケーションが含まれています。
API の場所	/api	API 関数が含まれているリポジトリ内のフォルダー。
Output location (出力場所)	空白のままにします。	このアプリにはビルド出力はありません。

[Review + create](レビュー + 作成) を選択します。
[作成] を択して、最初のデプロイを開始します。
プロセスが完了したら、[リソースに移動] を選択して新しい静的 Web アプリを開きます。
[概要] セクションで、アプリケーションの URL を見つけます。この値をテキストエディターにコピーし、Entra 認証を設定する今後の手順で使用します。

Microsoft Entra アプリケーションを作成する

Azure portal で、[Microsoft Entra ID] を検索してそこに移動します。
[管理] メニューから [アプリの登録] を選択します。

[新規登録] を選択して、[アプリケーションの登録] ウィンドウを開きます。次の値を入力します。

設定	値	Notes
名前	「MyStaticWebApp」と入力します。
サポートされているアカウントの種類	[この組織のディレクトリ内のアカウントのみ] を選択します。
リダイレクト URI	[Web] を選び、静的 Web アプリの Microsoft Entra 認証コールバック URL を入力します。 `<YOUR_SITE_URL>/.auth/login/aad/callback` の `<YOUR_SITE_URL>` は、静的 Web アプリの URL に置き換えます。	この URL は、前の手順でテキストエディターにコピーしたものです。

アプリの登録を作成する

[登録] を選択します。
アプリの登録が作成されたら、 [Essentials](要点) セクションの [アプリケーション (クライアント) ID] と [ディレクトリ (テナント) ID] をテキストエディターにコピーします。

これらの値は、静的 Web アプリで Entra ID 認証を構成するために必要です。

ID トークンを有効にする

アプリの登録設定で、[管理] の [認証] を選択します。
[暗黙的な許可およびハイブリッドフロー] セクションで [ID トークン (暗黙的およびハイブリッドフローに使用)] を選択します。

Static Web Apps ランタイムでは、ユーザーを認証するためにこの構成が必要です。
[保存] を選択します。

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

アプリ登録の設定で、[管理] の下にある [証明書とシークレット] を選びます。
[クライアントシークレット] セクションで、 [新しいクライアントシークレット] を選択します。
[説明] フィールドに「MyStaticWebApp」と入力します。
[有効期限] フィールドは、既定値の [6 か月] のままにします。

注意

有効期限が切れる前に、新しいシークレットを生成し、その値でアプリを更新して、シークレットをローテーションする必要があります。
[追加] を選択します。
作成したクライアントシークレットの [値] をテキストエディターにコピーします。

この値は、静的 Web アプリで Entra ID 認証を構成するために必要です。

Microsoft Entra ID 認証を構成する

ブラウザーで、デプロイした静的 Web アプリが含まれた GitHub リポジトリを開きます。

アプリの構成ファイル (frontend/staticwebapp.config.json) に移動します。このファイルには次のセクションがあります。

"auth": {
  "rolesSource": "/api/GetRoles",
  "identityProviders": {
    "azureActiveDirectory": {
      "userDetailsClaim": "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name",
      "registration": {
        "openIdIssuer": "https://login.microsoftonline.com/<YOUR_ENTRA_TENANT_ID>",
        "clientIdSettingName": "ENTRA_CLIENT_ID",
        "clientSecretSettingName": "ENTRA_CLIENT_SECRET"
      },
      "login": {
        "loginParameters": [
          "resource=https://graph.microsoft.com"
        ]
      }
    }
  }
},

この構成は、次の設定で構成されています。

Properties	説明
`rolesSource`	ログインプロセスが使用可能なロールの一覧を取得する URL。サンプルアプリケーションの場合、URL は `/api/GetRoles` です。
`userDetailsClaim`	ログイン要求の検証に使用されるスキーマの URL。
`openIdIssuer`	テナント ID を追加した Microsoft Entra ログインルート。
`clientIdSettingName`	ご使用の Microsoft Entra クライアント ID。
`clientSecretSettingName`	Microsoft Entra クライアントシークレット値。
`loginParameters`	Microsoft Graph のアクセストークンを取得するには、`loginParameters` フィールドが `resource=https://graph.microsoft.com` を使用して構成されている必要があります。

ファイルを更新するために [編集] を選びます。
<YOUR_ENTRA_TENANT_ID> を Microsoft Entra ID のディレクトリ (テナント) ID に置き換えて、https://login.microsoftonline.com/<YOUR_ENTRA_TENANT_ID> の openIdIssuer 値を更新します。
[変更をコミットする] を選択します。
コミットメッセージを入力し、[変更をコミットする] を選択します。

これらの変更をコミットすると、静的 Web アプリを更新する GitHub Actions の実行が開始されます。
Azure portal で、お使いの静的 Web アプリリソースに移動します。
メニューバーで [構成] を選択します。
[アプリケーションの設定] セクションで、次の設定を追加します。

名前値

ENTRA_CLIENT_ID Entra ID アプリケーション (クライアント) ID。

ENTRA_CLIENT_SECRET Entra アプリケーションクライアントシークレットの値。
[保存] を選択します。

名前	値
`ENTRA_CLIENT_ID`	Entra ID アプリケーション (クライアント) ID。
`ENTRA_CLIENT_SECRET`	Entra アプリケーションクライアントシークレットの値。

ロールを作成する

Azure portal で Entra ID アプリの登録を開きます。
[管理] で、[アプリロール] を選択します。

[アプリロールの作成] を選択し、次の値を入力します。

設定	値
表示名	「admin」と入力します。
Allowed member types (許可されるメンバーの種類)	[ユーザー/グループ] を選択します。
値	「admin」と入力します。
説明	「Administrator」と入力します。

[このアプリロールを有効にしますか?] チェックボックスをオンにします。
[適用] を選択します。
次に、reader という名前のロールに対して同じプロセスを繰り返します。
各ロールの ID 値をコピーし、テキストエディターに保存します。

カスタムロールを検証する

サンプルアプリケーションには、ユーザーが定義済みグループに含まれているかどうかを判断するために Microsoft Graph に対してクエリを実行する API 関数 (api/GetRoles/index.js) が含まれています。

ユーザーのグループメンバーシップに基づき、関数によってカスタムロールがユーザーに割り当てられます。アプリケーションは、これらのカスタムロールに基づいて特定のルートを制限するように構成されます。

GitHub リポジトリで、api/GetRoles/index.js にある GetRoles 関数に移動します。

上部には、カスタムユーザーロールを Microsoft Entra グループにマップする roleGroupMappings オブジェクトがあります。
[編集] を選択します。
Microsoft Entra テナントのグループ ID でオブジェクトを更新します。

たとえば、6b0b2fff-53e9-4cff-914f-dd97a13bfbd6 と b6059db5-9cef-4b27-9434-bb793aa31805 の ID のグループがある場合は、次のようにオブジェクトを更新します。
```
const roleGroupMappings = {
  'admin': '6b0b2fff-53e9-4cff-914f-dd97a13bfbd6',
  'reader': 'b6059db5-9cef-4b27-9434-bb793aa31805'
};
```
ユーザーが Microsoft Entra ID で正常に認証されるたびに GetRoles 関数が呼び出されます。この関数では、ユーザーのアクセストークンを使用して、Microsoft Graph から Entra グループメンバーシップに対するクエリが実行されます。ユーザーが roleGroupMappings オブジェクトに定義されている任意のグループのメンバーである場合は、対応するカスタムロールが返されます。

上の例では、ユーザーが b6059db5-9cef-4b27-9434-bb793aa31805 の ID を持つ Entra ID グループのメンバーである場合は、reader ロールが付与されます。
[変更をコミットする] を選択します。
コミットメッセージを追加し、[変更をコミットする] を選択します。

これらの変更を行うと、静的 Web アプリを更新するためのビルドが開始されます。
デプロイが完了したら、アプリの URL に移動して変更を確認できます。
Microsoft Entra ID を使って静的 Web アプリにサインインします。
ログインすると、ユーザーの ID の Entra ID グループメンバーシップに基づいて、割り当てられているロール一覧がサンプルアプリに表示されます。

これらのロールに応じて、アプリ内の一部のルートへのアクセスが許可または禁止されます。

Note

Microsoft Graph に対する一部のクエリでは、複数のページのデータが返されます。複数のクエリ要求が必要な場合、Microsoft Graph は、結果の次のページへの URL を含む @odata.nextLink プロパティを応答で返します。詳細については、アプリでの Microsoft Graph データのページングに関する記事を参照してください。

リソースをクリーンアップする

リソースグループを削除して、デプロイしたリソースをクリーンアップします。

Azure portal で、左側のメニューから [リソースグループ] を選択します。
[名前でフィルター] フィールドに、リソースグループ名を入力します。
このチュートリアルで使用したリソースグループ名を選択します。
トップメニューから [リソースグループの削除] を選択します。

次のステップ

認証と権限承認

次の方法で共有

チュートリアル: 関数と Microsoft Graph (プレビュー) を使用してカスタムロールを割り当てる

前提条件

GitHub リポジトリを作成する

静的 Web アプリを Azure にデプロイする

Microsoft Entra アプリケーションを作成する

ID トークンを有効にする

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

Microsoft Entra ID 認証を構成する

ロールを作成する

カスタムロールを検証する

リソースをクリーンアップする

次のステップ

フィードバック

その他のリソース

次の方法で共有

チュートリアル: 関数と Microsoft Graph (プレビュー) を使用してカスタム ロールを割り当てる

前提条件

GitHub リポジトリを作成する

静的 Web アプリを Azure にデプロイする

Microsoft Entra アプリケーションを作成する

ID トークンを有効にする

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

Microsoft Entra ID 認証を構成する

ロールを作成する

カスタム ロールを検証する

リソースをクリーンアップする

次のステップ

フィードバック

その他のリソース

チュートリアル: 関数と Microsoft Graph (プレビュー) を使用してカスタムロールを割り当てる

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

カスタムロールを検証する