教學課程：使用函式和 Microsoft Graph 指派自訂角色 (預覽)

本文示範如何使用函式來查詢 Microsoft Graph，並根據其 Entra ID 群組成員資格將自訂角色指派給使用者。

您會在本教學課程中學到：

部署靜態 Web 應用程式。
建立 Microsoft Entra 應用程式註冊。
使用 Microsoft Entra ID 設定自訂驗證。
設定無伺服器函式，查詢使用者的 Entra ID 群組成員資格，並傳回自訂角色的清單。

附註

本教學課程會要求您使用函式來指派角色。函式型角色管理目前為預覽狀態。完成本教學課程所需的權限等級為 "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。
選取 [從範本建立存放庫]。

將靜態 Web 應用程式部署至 Azure

在新的瀏覽器視窗中，開啟 Azure 入口網站。
從左上角選取 [建立資源]。
在搜尋方塊中，輸入靜態 Web 應用程式。
選取 [Static Web Apps]。
選取 [建立]。

使用下列資訊設定靜態 Web 應用程式：

設定	值	注意
訂用帳戶	選取 Azure 訂用帳戶。
資源群組	建立名為 my-custom-roles-app-group 的新群組。
名稱	my-custom-roles-app
方案類型	Standard	使用函式自訂驗證和指派角色需要標準方案。
API 的區域	選取最靠近您的區域。

在 [部署詳細資料] 區段中：

設定值

來源選取 [GitHub]。

組織選取您產生存放庫的組織。

Repository 選取 my-custom-roles-app。

分支選取 [主要]。

設定	值
來源	選取 [GitHub]。
組織	選取您產生存放庫的組織。
Repository	選取 my-custom-roles-app。
分支	選取 [主要]。

在 [組建詳細資料] 區段中，新增此應用程式的設定詳細資料。

設定	值	注意
組建預設	選取 [自訂]。
應用程式位置	輸入 /frontend。	此資料夾包含前端應用程式。
API 位置	/api	包含 API 函式之存放庫中的資料夾。
輸出位置	保留空白。	此應用程式沒有組建輸出。

選取 [檢閱 + 建立]。
選取 [建立] 起始第一個部署。
程序完成後，請選取 [移至資源] 以開啟新的靜態 Web 應用程式。
在 [概觀] 區段中，找出應用程式的 URL。將此值複製到文字編輯器，以在後續步驟中用來設定 Entra 驗證。

建立 Microsoft Entra 應用程式

在 Azure 入口網站中，搜尋並移至 Microsoft Entra ID。
從 [管理] 功能表中，選取 [應用程式註冊]。

選取 [新增註冊] 以開啟 [註冊應用程式] 視窗。輸入下列值：

設定	值	注意
名稱	輸入 MyStaticWebApp。
支援的帳戶類型	選取 [僅此組織目錄中的帳戶]。
重新導向 URI	選取 [Web]，然後輸入靜態 Web 應用程式的 Microsoft Entra 驗證回呼 URL。將 `<YOUR_SITE_URL>` 中的 `<YOUR_SITE_URL>/.auth/login/aad/callback` 取代為靜態 Web 應用程式的 URL。	此 URL 是您在先前步驟中複製到文字編輯器的內容。

建立應用程式註冊

選取 [註冊]。
建立應用程式註冊之後，將 [基本資訊] 區段中的 [應用程式 (用戶端) 識別碼] 和 [目錄 (租用戶) 識別碼] 複製到文字編輯器。

您需要這些值，才能在靜態 Web 應用程式中設定 Entra ID 驗證。

啟用識別碼權杖

從應用程式註冊設定中，選取 [管理] 底下的 [驗證]。
在 [隱含授與和混合式流程] 區段中，選取 [識別碼權杖 (用於隱含和混合式流程)]。

Static Web Apps 執行階段需要此設定來驗證您的使用者。
選取 [儲存]。

建立用戶端密碼

在應用程式註冊設定中，選取 [管理] 底下的 [憑證與祕密]。
在 [用戶端密碼] 區段中，選取 [新增用戶端密碼]。
針對 [描述] 欄位，輸入 MyStaticWebApp。
針對 [到期] 欄位，保留預設值 [6 個月]。

附註

您必須在到期日之前輪替祕密，方法是產生新的祕密，並使用其值更新您的應用程式。
選取 [新增]。
將您建立的客戶端密碼值複製到文字編輯器。

您需要此值，才能在靜態 Web 應用程式中設定 Entra ID 驗證。

設定 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"
        ]
      }
    }
  }
},

此組態是由下列設定所組成：

屬性	描述
`rolesSource`	登入程序取得可用角色清單的 URL。針對範例應用程式，URL 為 `/api/GetRoles`。
`userDetailsClaim`	用來驗證登入要求的結構描述 URL。
`openIdIssuer`	Microsoft Entra 登入路由，並附加您的租用戶識別碼。
`clientIdSettingName`	您的 Microsoft Entra 用戶端識別碼。
`clientSecretSettingName`	您的 Microsoft Entra 用戶端密碼值。
`loginParameters`	若要取得 Microsoft Graph 的存取權杖，`loginParameters` 欄位必須設定為 `resource=https://graph.microsoft.com`。

選取 [編輯] 以更新檔案。
藉由將取代為您的 Microsoft Entra ID 的目錄 (租用戶) 識別碼，更新 https://login.microsoftonline.com/<YOUR_ENTRA_TENANT_ID> 的 <YOUR_ENTRA_TENANT_ID> 值。
選取 [認可變更]。
輸入認可訊息，然後選取 [認可變更]。

認可這些變更會起始 GitHub Actions 執行以更新靜態 Web 應用程式。
在 Azure 入口網站中移至靜態 Web 應用程式資源。
選取功能表列中的 [設定]。
在 [應用程式設定] 區段中，新增下列設定：

名稱值

ENTRA_CLIENT_ID 您的 Entra ID 應用程式 (用戶端) 識別碼。

ENTRA_CLIENT_SECRET 您的 Entra 應用程式用戶端密碼值。
選取 [儲存]。

名稱	值
`ENTRA_CLIENT_ID`	您的 Entra ID 應用程式 (用戶端) 識別碼。
`ENTRA_CLIENT_SECRET`	您的 Entra 應用程式用戶端密碼值。

建立角色

在 Azure 入口網站中開啟您的 Entra ID 應用程式註冊。
在 [管理] 下方，選取 [應用程式角色]。
選取 [建立應用程式角色]，然後輸入下列值：

設定值

顯示名稱輸入管理員。

允許的成員類型選取 [使用者/群組]。

值輸入管理員。

描述輸入系統管理員。
核取 [要啟用此應用程式角色嗎？] 方塊
選取 [套用]。
現在，針對名為讀者的角色重複相同的程序。
複製每個角色的識別碼值，並將其放在文字編輯器中。

設定	值
顯示名稱	輸入管理員。
允許的成員類型	選取 [使用者/群組]。
值	輸入管理員。
描述	輸入系統管理員。

確認自訂角色

範例應用程式包含 API 函式 (api/GetRoles/index.js)，可查詢 Microsoft Graph，以判斷使用者是否在預先定義的群組中。

根據使用者的群組成員資格，函式會將自訂角色指派給使用者。應用程式已設定為根據這些自訂角色來限制特定路由。

在您的 GitHub 存放庫中，移至位於 api/GetRoles/index.js 的 GetRoles 函式。

在頂端附近，有一個 roleGroupMappings 物件會將自訂使用者角色對應至 Microsoft Entra 群組。
選取 [編輯]。
使用您的 Microsoft Entra 租用戶的群組識別碼來更新物件。

例如，如果您有識別碼為 6b0b2fff-53e9-4cff-914f-dd97a13bfbd6 和 b6059db5-9cef-4b27-9434-bb793aa31805 的群組，您會將物件更新為：
```
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 之 Entra ID 群組的成員，則會獲授與 reader 角色。
選取 [認可變更]。
新增認可訊息，然後選取 [認可變更]。

進行這些變更會起始組建，以更新靜態 Web 應用程式。
部署完成時，您可以瀏覽至應用程式的 URL 來驗證變更。
使用 Microsoft Entra ID 登入靜態 Web 應用程式。
登入時，範例應用程式會顯示您根據身分識別的 Entra ID 群組成員資格獲指派的角色清單。

視這些角色而定，您被允許或禁止存取應用程式中的某些路由。

附註

某些針對 Microsoft Graph 的查詢會傳回多個頁面的資料。需要多個查詢要求時，Microsoft Graph 會在回應中傳回 @odata.nextLink 屬性，其中包含結果下一頁的 URL。如需詳細資訊，請參閱在應用程式中分頁 Microsoft Graph 資料

清除資源

您可以藉由刪除資源群組來清除您所部署的資源。

在 Azure 入口網站中，選取左側功能表中的 [資源群組]。
在 [依名稱篩選] 欄位中輸入資源群組名稱。
選取在本教學課程中使用的資源群組名稱。
從頂端功能表中選取 [刪除資源群組]。

後續步驟

驗證和授權

意見反應

此頁面對您有幫助嗎？

Last updated on 2025-10-10