設定 App Service 或 Azure Functions 應用程式以使用 Microsoft Entra 登入

選取另一個驗證提供者以跳至該提供者。

本文說明如何設定 Azure App 服務 或 Azure Functions 的驗證,讓您的應用程式以 Microsoft 身分識別平台 (Microsoft Entra ID) 作為驗證提供者登入使用者。

App Service 驗證功能可以自動使用 Microsoft 身分識別平台 建立應用程式註冊。 您也可以使用您或目錄管理員個別建立的註冊。

注意

自動建立新註冊的選項不適用於政府雲端,或使用 [Microsoft Entra ID for customers (Preview)] 時。 請改為個別定義註冊。

選項 1:自動建立新的應用程式註冊

除非您需要個別建立應用程式註冊,否則請使用此選項。 建立應用程式之後,您可以在 Microsoft Entra ID 中自定義應用程式註冊。

  1. 登入 Azure 入口網站,然後瀏覽至應用程式。

  2. 選取左側功能表中的 [驗證]。 選取 [新增識別提供者]

  3. 在 [識別提供者] 下拉式清單中選取 [Microsoft ]。 默認會選取建立新註冊的選項。 您可以變更註冊的名稱或支援的帳戶類型。

    將會建立客戶端密碼,並儲存為名為MICROSOFT_PROVIDER_AUTHENTICATION_SECRET的插槽黏性應用程式設定。 如果您想要管理 Azure Key Vault 中的祕密,稍後可以將該設定更新為使用 Key Vault 參考

  4. 如果這是為應用程式設定的第一個 識別提供者,您也會收到 App Service 驗證設定 一節的提示。 否則,您可以繼續下一個步驟。

    這些選項會決定您的應用程式如何回應未經驗證的要求,而默認選項會重新導向所有要求,以使用此新提供者登入。 您可以立即變更自訂此行為,或稍後從主要 [驗證] 畫面選擇 [驗證設定] 旁的 [編輯],以調整這些 [設定]。 若要深入了解這些選項,請參閱驗證流程

  5. (選擇性)選取 [下一步:許可權 ],並新增應用程式所需的任何 Microsoft Graph 許可權。 這些會新增至應用程式註冊,但您也可以稍後加以變更。

  6. 選取 [新增]。

您現在已準備好在應用程式中使用 Microsoft 身分識別平台 進行驗證。 [驗證] 畫面會列出提供者。 您可以從這裡編輯或刪除此提供者設定。

如需為可存取 Azure 儲存體 和 Microsoft Graph 的 Web 應用程式設定 Microsoft Entra 登入的範例,請參閱本教學課程

選項 2:使用個別建立的現有註冊

您可以設定 App Service 驗證以使用現有的應用程式註冊。 下列情況是使用現有應用程式註冊最常見的案例:

  • 您的帳戶沒有在 Microsoft Entra 租使用者中建立應用程式註冊的許可權。
  • 您想要使用與應用程式位於不同 Microsoft Entra 租使用者的應用程式註冊。
  • 建立新註冊的選項不適用於政府雲端。

步驟 1:在 App Service 應用程式的 Microsoft Entra 識別碼中建立應用程式註冊

在建立應用程式註冊期間,收集下列資訊,當您在 App Service 應用程式中設定驗證時,稍後需要此資訊:

  • 用戶端識別碼
  • 租用戶識別碼
  • 用戶端密碼(選擇性,但建議使用)
  • 應用程式識別碼 URI

建立應用程式註冊的指示取決於您使用的是 員工租 用戶或 客戶租使用者。 使用下方的索引標籤,為您的案例選取正確的指示集。

若要註冊應用程式,請執行下列步驟:

  1. 登入 Azure 入口網站,搜尋並選取 [應用程式服務],然後選取您的應用程式。 記下應用程式的 URL。 您將使用它來設定 Microsoft Entra 應用程式註冊。

  2. 在入口網站中瀏覽至您的租使用者:

    從入口網站功能表中,選取 [Microsoft Entra ID]。 如果您使用的租使用者與您用來設定 App Service 應用程式的租使用者不同,您 必須先變更目錄

  3. 在 [概觀] 畫面上,記下 租使用者標識碼以及 主要網域

  4. 從左側導覽中,選取 [應用程式註冊][>新增註冊]。

  5. 在 [ 註冊應用程式] 頁面中,輸入 應用程式註冊的 [名稱 ]。

  6. [支持的帳戶類型] 中,選取可存取此應用程式的帳戶類型。

  7. 在 [ 重新導向 URI] 區段中,針對平台選取 [Web ],然後輸入 <app-url>/.auth/login/aad/callback。 例如: https://contoso.azurewebsites.net/.auth/login/aad/callback

  8. 選取註冊

  9. 建立應用程式註冊之後,請複製 應用程式 (用戶端) 識別碼目錄 (租使用者) 識別碼 以供稍後使用。

  10. 在 [隱含授與和混合式流程] 下,啟用標識符令牌,以允許從 App Service 連線 使用者登入。 選取 [儲存]。

  11. (選擇性)從左側導覽中,選取 [商標與屬性]。 在 [首頁 URL] 中,輸入 App Service 應用程式的 URL,然後選取 [ 儲存]。

  12. 從左側導覽中,選取 [公開 API>集合>儲存]。 當應用程式作為資源使用時,這個值會唯一識別應用程式,允許要求令牌授與存取權。 它會作為您所建立範圍的前置詞。

    對於單一租使用者應用程式,您可以使用預設值,其格式 api://<application-client-id>為 。 您也可以根據租使用者的其中一個已驗證網域來指定更可讀取的 URI https://contoso.com/api 。 針對多租使用者應用程式,您必須提供自定義 URI。 若要深入瞭解應用程式識別碼 URI 的已接受格式,請參閱 應用程式註冊最佳做法參考

  13. 選取新增範圍

    1. [範圍名稱] 中,輸入 user_impersonation
    2. 如果您想要允許使用者同意此範圍,請在 神秘 中選取 [管理員] 和 [使用者]。
    3. 在文字框中,輸入您想要使用者在同意頁面上看到的同意範圍名稱和描述。 例如,輸入 Access application-name>。<
    4. 選取新增範圍
  14. (選擇性)若要建立客戶端密碼:

    1. 從左側導覽中,選取 [憑證與秘密>] [客戶端密碼>] [新增客戶端密碼]。
    2. 輸入描述和到期日,然後選取 [ 新增]。
    3. 在 [ 值] 欄位中,複製客戶端密碼值。 一旦您離開此頁面,它就不會再次顯示。
  15. (選擇性)若要新增多個 回復 URL,請選取 [ 驗證]。

  16. 完成應用程式註冊的設定:

    員工租使用者不需要其他步驟。

步驟 2:在 App Service 應用程式中啟用 Microsoft Entra 識別碼

  1. 登入 Azure 入口網站,然後瀏覽至應用程式。

  2. 從左側導覽中,選取 [驗證>新增識別提供者>Microsoft]。

  3. 選取您所建立之應用程式註冊的 [租使用者類型]。

  4. 使用適當租使用者類型的指示,將應用程式設定為使用您所建立的註冊:

    針對 [ 應用程式註冊類型],選擇下列其中一項:

    • 在此目錄中挑選現有的應用程式註冊:從目前的租用戶選擇應用程式註冊,並自動收集必要的應用程式資訊。 系統會嘗試針對應用程式註冊建立新的客戶端密碼,並自動將您的應用程式設定為使用它。 默認簽發者 URL 是根據應用程式註冊中所設定的支持帳戶類型來設定。 如果您想要變更此預設值,請參閱下表。
    • 提供現有應用程式註冊的詳細數據:指定來自另一個租使用者的應用程式註冊詳細數據,或您的帳戶沒有目前租用戶的許可權可查詢註冊。 針對此選項,您必須根據下表手動填入組態值。

    員工租用戶的驗證端點應該是雲端環境特定的值。 例如,全域 Azure 中的員工員工租使用者會使用 “https://login.microsoftonline.com"作為其驗證端點。 請記下驗證端點值,因為它需要建構正確的 簽發者 URL

    直接填入組態詳細數據時,請使用您在應用程式註冊建立程式期間收集的值:

    欄位 描述
    應用程式 (用戶端) 識別碼 使用應用程式註冊的應用程式(用戶端)標識碼
    用戶端祕密 使用您在應用程式註冊中產生的客戶端密碼。 使用客戶端密碼時,會使用混合式流程,而 App Service 會傳回存取權和重新整理令牌。 未設定客戶端密碼時,會使用隱含流程,而且只會傳回標識元令牌。 這些令牌是由提供者傳送,並儲存在App Service驗證令牌存放區中。
    簽發者 URL 使用 <authentication-endpoint>/<tenant-id>/v2.0,並將驗證端點取代<為您在上一個步驟中針對租使用者類型和雲端環境所決定的驗證端點>,也會將租用戶標識元>取代<建立應用程式註冊所在的目錄(租使用者)標識符。 對於使用 Azure AD v1 的應用程式,請在 URL 中省略 /v2.0

    這個值可用來將使用者重新導向至正確的 Microsoft Entra 租使用者,以及下載適當的元數據,以判斷適當的令牌簽署密鑰和令牌簽發者宣告值,例如。 租使用者特定端點以外的任何設定都會被視為多租使用者。 在多租使用者組態中,系統不會執行簽發者或租使用者標識碼的驗證,而且應該在應用程式的授權邏輯完整處理這些檢查。
    允許的令牌物件 這是選用欄位。 設定的應用程式 (用戶端) 識別碼一律會隱含地視為允許的物件。 如果您的應用程式代表其他用戶端將呼叫的 API,您也應該新增 您在應用程式註冊上設定的應用程式識別碼 URI 。 允許物件清單中總共有 500 個字元的限制。

    用戶端密碼會儲存為名為MICROSOFT_PROVIDER_AUTHENTICATION_SECRET的插槽黏性應用程式設定。 如果您想要管理 Azure Key Vault 中的祕密,稍後可以將該設定更新為使用 Key Vault 參考

  5. 如果這是為應用程式設定的第一個 識別提供者,您也會收到 App Service 驗證設定 一節的提示。 否則,您可以繼續下一個步驟。

    這些選項會決定您的應用程式如何回應未經驗證的要求,而默認選項會重新導向所有要求,以使用此新提供者登入。 您可以立即變更自訂此行為,或稍後從主要 [驗證] 畫面選擇 [驗證設定] 旁的 [編輯],以調整這些 [設定]。 若要深入了解這些選項,請參閱驗證流程

  6. 選取 [新增]。

您現在已準備好在應用程式中使用 Microsoft 身分識別平台 進行驗證。 [驗證] 畫面會列出提供者。 您可以從這裡編輯或刪除此提供者設定。

授權要求

根據預設,App Service 驗證只會處理驗證,判斷呼叫端是否為他們所說的身分。 授權,判斷該呼叫端是否應該具有某些資源的存取權,是驗證以外的額外步驟。 您可以從 Microsoft 身分識別平台 授權基本概念深入了解這些概念

您的應用程式可以在 程式代碼中做出授權決策。 App Service 驗證確實提供一些 內建檢查,可協助,但可能不足以涵蓋您應用程式的授權需求。

提示

多租使用者應用程式應該在此程式中驗證要求的簽發者和租使用者標識碼,以確保允許這些值。 當 App Service 驗證設定為多租使用者案例時,它不會驗證要求的來源租使用者。 例如,根據組織是否已註冊服務,應用程式可能需要限制為特定租使用者。 請參閱 Microsoft 身分識別平台 多租使用者指引

從應用程式程式代碼執行驗證

當您在應用程式程式代碼中執行授權檢查時,可以利用 App Service驗證所提供的宣告資訊。 插入的 x-ms-client-principal 標頭包含Base64編碼的 JSON 物件,其中包含有關呼叫端的宣告。 根據預設,這些宣告會經過宣告對應,因此宣告名稱不一定符合您在令牌中看到的內容。 例如, tid 宣告會改為對應至 http://schemas.microsoft.com/identity/claims/tenantid

您也可以直接從插入的 x-ms-token-aad-access-token 標頭使用基礎存取令牌。

使用內建授權原則

建立的應用程式註冊會驗證 Microsoft Entra 租使用者的連入要求。 根據預設,它也會讓租使用者內的任何人存取應用程式,這適用於許多應用程式。 不過,某些應用程式需要藉由做出授權決策來進一步限制存取。 您的應用程式程式代碼通常是處理自訂授權邏輯的最佳位置。 不過,針對常見案例,Microsoft 身分識別平台 提供內建檢查,讓您可用來限制存取。

本節說明如何使用App Service驗證 V2 API 來啟用內建檢查。 目前,設定這些內建檢查的唯一方式是透過 Azure Resource Manager 範本REST API

在 API 物件中,Microsoft Entra 識別提供者組態有一個 validation 區段,該區段可以包含 defaultAuthorizationPolicy 物件,如下列結構所示:

{
    "validation": {
        "defaultAuthorizationPolicy": {
            "allowedApplications": [],
            "allowedPrincipals": {
                "identities": []
            }
        }
    }
}
屬性 說明
defaultAuthorizationPolicy 必須符合才能存取應用程式的需求群組。 存取權會根據每個設定的屬性來授與邏輯 AND 。 設定 和 allowedPrincipalsallowedApplications,傳入要求必須滿足這兩個需求才能接受。
allowedApplications 字串應用程式 用戶端識別碼的允許清單, 代表呼叫應用程式的客戶端資源。 當此屬性設定為無空陣列時,只會接受清單中指定之應用程式的令牌。

此原則會 appid 評估傳入令牌的 或 azp 宣告,該令牌必須是存取令牌。 請參閱 Microsoft 身分識別平台 宣告參考
allowedPrincipals 一組檢查,判斷傳入要求所代表的主體是否可以存取應用程式。 的 allowedPrincipals 滿意度是根據其設定屬性的邏輯 OR
identities (下 allowedPrincipals 字串 物件識別碼的允許清單, 代表具有存取權的使用者或應用程式。 當此屬性設定為無空陣列時,如果清單中指定了要求所代表的使用者或應用程式, allowedPrincipals 就可以滿足需求。 身分識別清單中總共有 500 個字元的限制。

此原則會 oid 評估傳入令牌的宣告。 請參閱 Microsoft 身分識別平台 宣告參考

此外,不論所使用的 API 版本為何,都可以透過 應用程式設定來設定某些檢查。 WEBSITE_AUTH_AAD_ALLOWED_TENANTS應用程式設定可以使用最多 10 個租使用者標識符的逗號分隔清單來設定 (例如, “559a2f9c-c6f2-4d31-b8d6-5ad1a13f8330,5693f64a-3ad5-4be7-b846-e9d1141bcebc”) 要求傳入令牌來自其中一個指定的租使用者,如宣告所tid指定。 WEBSITE_AUTH_AAD_REQUIRE_CLIENT_SERVICE_PRINCIPAL應用程式設定可設定為 「true」 或 「1」 ,以要求傳入令牌包含oid宣告。 如果 allowedPrincipals.identities 已設定此設定,則會忽略此設定並視為 true(因為 oid 已針對此提供的身分識別清單檢查宣告)。

這些內建檢查失敗的要求會得到 HTTP 403 Forbidden 回應。

設定用戶端應用程式以存取您的App Service

在先前各節中,您已註冊 App Service 或 Azure 函式來驗證使用者。 本節說明如何在 Microsoft Entra ID 中註冊原生用戶端或精靈應用程式,讓他們可以代表使用者或本身要求存取 App Service 所公開的 API,例如在多層式架構中。 如果您只想要驗證使用者,就不需要完成本節中的步驟。

原生用戶端應用程式

您可以註冊原生用戶端,以代表登入的使用者要求存取 App Service 應用程式的 API。

  1. 從入口網站功能表中,選取 [Microsoft Entra ID]。

  2. 從左側導覽中,選取 [應用程式註冊>[新增註冊]。

  3. 在 [ 註冊應用程式] 頁面中,輸入 應用程式註冊的 [名稱 ]。

  4. 在 [ 重新導向 URI] 中,選取 [公用用戶端] [行動裝置和桌面], 然後輸入 URL <app-url>/.auth/login/aad/callback。 例如: https://contoso.azurewebsites.net/.auth/login/aad/callback

  5. 選取註冊

  6. 建立應用程式註冊之後,複製應用程式 (用戶端) 識別碼的值

    注意

    針對 Microsoft Store 應用程式,請改用 套件 SID 作為 URI。

  7. 從左側導覽中,選取 [API 許可權>] [新增許可權>我的 API]。

  8. 選取您稍早為 App Service 應用程式建立的應用程式註冊。 如果您沒有看到應用程式註冊,請確定您已在App Service 應用程式的 Microsoft Entra 識別碼中建立應用程式註冊中新增user_impersonation範圍。

  9. 在 [委派的許可權] 下,選取 [user_impersonation],然後選取 [新增許可權]。

您現在已設定原生用戶端應用程式,可代表使用者要求存取 App Service 應用程式。

精靈用戶端應用程式 (服務對服務話叫)

在多層式架構中,用戶端應用程式可以取得令牌,代表用戶端應用程式本身呼叫 App Service 或函式應用程式(而非代表使用者)。 此案例適用於執行沒有登入使用者之工作的非互動式精靈應用程式。 它會使用標準 OAuth 2.0 用戶端認證 授與。

  1. 從入口網站功能表中,選取 [Microsoft Entra ID]。
  2. 從左側導覽中,選取 [應用程式註冊>[新增註冊]。
  3. 在 [ 註冊應用程式] 頁面中,輸入 應用程式註冊的 [名稱 ]。
  4. 針對精靈應用程式,您不需要重新導向 URI,因此您可以保留空白。
  5. 選取註冊
  6. 建立應用程式註冊之後,複製應用程式 (用戶端) 識別碼的值
  7. 從左側導覽中,選取 [憑證與秘密>] [客戶端密碼>] [新增客戶端密碼]。
  8. 輸入描述和到期日,然後選取 [ 新增]。
  9. 在 [ 值] 欄位中,複製客戶端密碼值。 一旦您離開此頁面,它就不會再次顯示。

您現在 可以使用用戶端識別碼和客戶端密碼 來要求存取令牌,方法是將 參數設定 resource目標應用程式的應用程式識別碼 URI 。 接著,您可以使用標準 OAuth 2.0 授權標頭向目標應用程式呈現產生的存取令牌,而 App Service 驗證會如往常驗證並使用令牌,現在表示呼叫者(在此案例中不是使用者的應用程式)已經過驗證。

目前,這可讓 Microsoft Entra 租使用者中的任何用戶端應用程式要求存取令牌,並驗證目標應用程式。 如果您也想要強制 授權 只允許特定用戶端應用程式,則必須執行一些額外的設定。

  1. 在應用程式註冊指令清單中定義應用程式角色 ,此指令清單代表您想要保護的App Service或函式應用程式。
  2. 在代表需要授權之用戶端的應用程式註冊上,選取 [API 許可權>] [新增許可權>我的 API]。
  3. 選取您稍早建立的應用程式註冊。 如果您沒有看到應用程式註冊,請確定您已 新增應用程式角色
  4. 在 [應用程式許可權] 底下,選取您稍早建立的應用程式角色,然後選取 [新增許可權]。
  5. 請務必選取 [授與系統管理員同意 ] 以授權用戶端應用程式要求許可權。
  6. 類似於先前的案例(新增任何角色之前),您現在可以要求相同目標的resource存取令牌,而存取令牌會包含roles包含用戶端應用程式授權的應用程式角色的宣告。
  7. 在目標 App Service 或函式應用程式程式代碼中,您現在可以驗證令牌中是否有預期的角色(這不是由 App Service 驗證執行)。 如需詳細資訊,請參閱 存取使用者宣告

您現在已設定精靈用戶端應用程式,其可以使用自己的身分識別來存取 App Service 應用程式。

最佳作法

無論您使用何種設定來設定驗證,下列最佳做法都會讓您的租用戶和應用程式更安全:

  • 在 Microsoft Entra ID 中,以自己的應用程式註冊來設定每個 App Service 應用程式。
  • 為每個 App Service 應用程式提供自己的權限和同意。
  • 針對不同的部署位置使用個別的應用程式註冊,避免在環境之間共享權限。 測試新的程式碼時,這種做法有助於防止問題影響生產應用程式。

遷移至 Microsoft Graph

某些較舊的應用程式可能也已設定為相依於已淘汰的 Azure AD Graph,其已排程為完整淘汰。 例如,您的應用程式程式代碼可能已呼叫 Azure AD Graph,以在中間件管線中檢查群組成員資格作為授權篩選的一部分。 應用程式應遵循 Microsoft Entra ID 提供的指引,作為 Azure AD Graph 淘汰程式的一部分,移至 Microsoft Graph。 在遵循這些指示中,您可能需要對 App Service 驗證的設定進行一些變更。 將 Microsoft Graph 許可權新增至應用程式註冊之後,您可以.

  1. 如果簽發者 URL 尚未包含 「/v2.0」 後綴,請更新簽發者 URL

  2. 從您的登入組態中移除 Azure AD Graph 許可權的要求。 要變更的屬性取決於您 所使用的管理 API 版本:

    • 如果您使用 V1 API (/authsettings),這會在陣列中 additionalLoginParams
    • 如果您使用 V2 API (/authsettingsV2),這會在陣列中 loginParameters

    例如,您必須移除 “https://graph.windows.net"” 的任何參考。 這包括 resource 參數(“/v2.0” 端點不支援此參數),或您特別要求從 Azure AD Graph 要求的任何範圍。

    您也需要更新組態,以要求您為應用程式註冊設定的新 Microsoft Graph 許可權。 在許多情況下,您可以使用 .default 範圍 來簡化此設定。 若要這樣做,請新增登入參數 scope=openid profile email https://graph.microsoft.com/.default

使用這些變更時,當 App Service 驗證嘗試登入時,它將不再要求 Azure AD Graph 的許可權,而是會取得 Microsoft Graph 的令牌。 根據 Microsoft Entra ID 所提供的指引,您也必須更新應用程式程式代碼中使用該令牌的任何用法。

後續步驟