教學課程：使用函式和 Microsoft Graph 指派自定義角色
本文示範如何使用函式來查詢 Microsoft Graph ，並根據使用者的 Active Directory 群組成員資格，將自定義角色指派給使用者。
在本教學課程中，您將了解：
- 部署靜態 Web 應用程式。
- 建立 Microsoft Entra 應用程式註冊。
- 使用 Microsoft Entra ID 設定自訂驗證。
- 設定無伺服器函式，以查詢使用者的 Active Directory 群組成員資格，並傳回自定義角色的清單。
注意
本教學課程 會要求您使用函式來指派角色。 函式角色管理目前為預覽狀態。 完成本教學課程所需的許可權等級為 “User.Read.All”。
應用程式 API 中有一 個名為 GetRoles 的函式。 此函式會使用使用者的存取令牌，從 Microsoft Graph 查詢 Active Directory。 如果使用者是應用程式中定義之任何群組的成員，則對應的自定義角色會對應至使用者。
必要條件
| 需求 | 註解 |
|---|---|
| 有效的 Azure 帳戶 | 如果您沒有帳戶，您可以 免費建立帳戶。 |
| Microsoft Entra 權限 | 您必須有足夠的許可權才能建立 Microsoft Entra 應用程式。 |
建立 GitHub 存放庫
根據角色函式範本產生存放庫。 移至下列位置以建立新的存放庫。
將您的存放庫 命名為 my-custom-roles-app。
選取 [從範本建立存放庫]。
將靜態 Web 應用程式部署至 Azure
在新瀏覽器視窗中，開啟 Azure 入口網站。
從左上角選取 [建立資源]。
在搜尋方塊中，輸入 靜態 Web 應用程式。
選取 [Static Web Apps]。
選取 建立。
使用下列資訊設定靜態 Web 應用程式：
設定 值 備註 訂用帳戶 選取 Azure 訂閱。 資源群組 建立名為 my-custom-roles-app-group 的新群組。 名稱 my-custom-roles-app 方案類型 標準 使用函式自定義驗證和指派角色需要 標準 方案。 API 的區域 選取最靠近您的區域。 在 [部署詳細資料] 區段中：
設定 值 來源 選取 [GitHub]。 Organization 選取您產生存放庫的組織。 存放庫 選取 my-custom-roles-app。 分支 選取 main。 在 [ 建置詳細數據] 區段中，新增此應用程式的組態詳細數據。
設定 值 備註 建置預設 選取自訂。 應用程式位置 輸入 /frontend。 此資料夾包含前端應用程式。 API 位置 /Api 存放庫中包含 API 函式的資料夾。 輸出位置 保留空白。 此應用程式沒有組建輸出。 選取 [檢閱 + 建立]。
選取 [ 建立 ] 起始第一個部署。
程式完成後，請選取 [移至資源 ] 以開啟新的靜態 Web 應用程式。
在 [概觀] 區段中，找出應用程式的 URL。 將此值複製到文本編輯器，以在後續步驟中用來設定 Active Directory 驗證。
建立 Microsoft Entra 應用程式
在 Azure 入口網站 中，搜尋並移至 Microsoft Entra ID。
從 [管理] 功能表中，選取 [應用程式註冊]。
選取 [新增註冊 ] 以開啟 [註冊應用程式 ] 視窗。 輸入下列值：
設定 值 注意 名稱 輸入 MyStaticWebApp。 支援的帳戶類型 僅選取此組織目錄中的 [帳戶]。 重新導向 URI 選取 [Web ]，然後輸入靜態 Web 應用程式的 Microsoft Entra 驗證回呼 URL。 <YOUR_SITE_URL>/.auth/login/aad/callback將取代<YOUR_SITE_URL>為靜態 Web 應用程式的 URL。此 URL 是您先前步驟中複製到文字編輯器的內容。 
選取註冊。
建立應用程式註冊之後，將 [基本資訊] 區段中的應用程式 （用戶端） 識別碼和目錄 （租使用者） 識別碼複製到文字編輯器。
您需要這些值，才能在靜態 Web 應用程式中設定 Active Directory 驗證。
啟用標識碼令牌
從應用程式註冊設定中，選取 [管理] 底下的 [驗證]。
在 [隱含授與和混合式流程] 區段中，選取 [識別碼權杖] \(用於隱含和混合式流程\)。
Static Web Apps 執行時間需要此設定來驗證您的使用者。
選取 [儲存]。
建立用戶端密碼
在應用程式註冊設定中，選取 [管理] 底下的 [憑證和秘密]。
在用戶端密碼區段底下，選取新增用戶端密碼。
針對 [ 描述] 欄位，輸入 MyStaticWebApp。
針對 [ 到期] 欄位，保留預設值 6 個月。
注意
您必須在到期日之前輪替秘密，方法是產生新的秘密，並使用其值更新您的應用程式。
選取新增。
將您建立的客戶端密碼值複製到文字編輯器。
您需要此值，才能在靜態 Web 應用程式中設定 Active Directory 驗證。
設定 Active Directory 驗證
在瀏覽器中，開啟包含您所部署靜態 Web 應用程式的 GitHub 存放庫。
移至前端/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_AAD_TENANT_ID>", "clientIdSettingName": "AAD_CLIENT_ID", "clientSecretSettingName": "AAD_CLIENT_SECRET" }, "login": { "loginParameters": [ "resource=https://graph.microsoft.com" ] } } } },此組態是由下列設定所組成：
屬性 描述 rolesSource登入程式取得可用角色清單的 URL。 針對範例應用程式，URL 為 /api/GetRoles。userDetailsClaim用來驗證登入要求的架構 URL。 openIdIssuerMicrosoft Entra 登入路由，附加您的租用戶標識碼。 clientIdSettingName您的 Microsoft Entra 用戶端識別碼。 clientSecretSettingName您的 Microsoft Entra 用戶端秘密值。 loginParameters若要取得 Microsoft Graph 的存取權杖， loginParameters欄位必須設定為resource=https://graph.microsoft.com。選取 [ 編輯 ] 以更新檔案。
將 取代
<YOUR_AAD_TENANT_ID>為您 Microsoft Entra ID 的目錄（租使用者）標識碼，以更新的 openIdIssuer 值https://login.microsoftonline.com/<YOUR_AAD_TENANT_ID>。選取 [ 認可變更...]。
輸入認可訊息，然後選取 [ 認可變更]。
認可這些變更會起始 GitHub Actions 執行以更新靜態 Web 應用程式。
移至 Azure 入口網站 中的靜態 Web 應用程式資源。
選取選單 列中的 [設定 ]。
在 [ 應用程式設定] 區段中，新增下列設定：
名稱 值 AAD_CLIENT_ID您的 Active Directory 應用程式 （用戶端） 識別碼。 AAD_CLIENT_SECRET您的 Active Directory 應用程式用戶端密碼值。 選取 [儲存]。
建立角色
在 Azure 入口網站 中開啟 Active Directory 應用程式註冊。
在 [管理] 底下，選取 [應用程式角色]。
選取 [ 建立應用程式角色 ]，然後輸入下列值：
設定 值 Display name 輸入 admin。 允許的成員類型 選取 [ 使用者/群組]。 值 輸入 admin。 描述 輸入 管理員 istrator。 核取您要啟用此應用程式角色的方塊 嗎？
選取套用。
現在，針對名為 讀取者的角色重複相同的程式。
複製每個角色的識別碼值，並將其放在文本編輯器中。
確認自定義角色
範例應用程式包含 API 函式 （api/GetRoles/index.js），可查詢 Microsoft Graph 以判斷使用者是否在預先定義的群組中。
根據使用者的群組成員資格，函式會將自定義角色指派給使用者。 應用程式已設定為根據這些自定義角色來限制特定路由。
在您的 GitHub 存放庫中，移至位於 api/GetRoles/index.js的 GetRoles 函式。
在頂端附近，有一個
roleGroupMappings物件會將自定義使用者角色對應至 Microsoft Entra 群組。選取編輯。
使用 Microsoft Entra 租使用者的群組標識碼來更新 物件。
例如，如果您有具有標識符和
b6059db5-9cef-4b27-9434-bb793aa31805的6b0b2fff-53e9-4cff-914f-dd97a13bfbd6群組，您會將 物件更新為：const roleGroupMappings = { 'admin': '6b0b2fff-53e9-4cff-914f-dd97a13bfbd6', 'reader': 'b6059db5-9cef-4b27-9434-bb793aa31805' };每當使用者以 Microsoft Entra ID 成功驗證時，就會呼叫 GetRoles 函式。 函式會使用使用者的存取令牌，從 Microsoft Graph 查詢其 Active Directory 群組成員資格。 如果使用者是 對象中
roleGroupMappings定義之任何群組的成員，則會傳回對應的自定義角色。在上述範例中，如果使用者是標識符
b6059db5-9cef-4b27-9434-bb793aa31805為 Active Directory 群組的成員，則會獲授與reader角色。選取 [ 認可變更...]。
新增認可訊息，然後選取 [ 認可變更]。
進行這些變更會起始 組建，以更新靜態 Web 應用程式。
部署完成時，您可以瀏覽至應用程式的 URL 來驗證變更。
使用 Microsoft Entra ID 登入靜態 Web 應用程式。
當您登入時，範例應用程式會顯示您根據身分識別的 Active Directory 群組成員資格指派的角色清單。
視這些角色而定，您被允許或禁止存取應用程式中的某些路由。
注意
某些對 Microsoft Graph 的查詢會傳回多個頁面的數據。 需要多個查詢要求時，Microsoft Graph 會在響應中傳回 @odata.nextLink 屬性，其中包含結果下一頁的 URL。 如需詳細資訊，請參閱 在應用程式中分頁 Microsoft Graph 數據
清除資源
刪除資源群組來清除您部署的資源。
在 Azure 入口網站中，選取左側功能表中的 [資源群組]。
在 [依名稱篩選] 欄位中輸入資源群組名稱。
選取您在本教學課程中使用的資源組名。
從頂端功能表中選取 [刪除資源群組]。