共用方式為

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

  • 發行項

注意

從 2024 年 6 月 1 日起，新建立的 App Service 應用程式可以產生使用命名慣例 <app-name>-<random-hash>.<region>.azurewebsites.net的唯一默認主機名。 現有的應用程式名稱保持不變。 例如：

myapp-ds27dh7271aah175.westus-01.azurewebsites.net

如需詳細資訊，請參閱 App Service 資源的唯一預設主機名。

選取以跳至其他驗證提供者。

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

為您的應用程式及其使用者選擇租用戶

您必須先在員工或外部租用戶中註冊應用程式，應用程式才能登入使用者。 如果要將應用程式提供給員工或商務來賓使用，請在員工租用戶中註冊應用程式。 如果應用程式要給消費者和商務客戶使用，請在外部租用戶中註冊應用程式。

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

  2. 在應用程式的左側功能表上，選取 [設定>驗證]，然後選取 [新增識別提供者]。

  3. 在 [新增識別提供者] 頁面中，選取 [Microsoft] 作為 [識別提供者]，以登入 Microsoft 和 Microsoft Entra 識別。

  4. 在 [為您的應用程式及其用戶選擇租使用者] 下，選取 [員工和商務來賓的員工設定][目前租使用者]，或選取 [消費者和商務客戶的外部設定]。

選擇應用程式註冊

App Service 驗證功能可以自動為您建立應用程式註冊，或者您可以使用您或目錄管理員個別建立的註冊。

若不需要個別建立應用程式註冊，請自動建立新的應用程式註冊。 您想要的話，可以在 Microsoft Entra 系統管理中心自訂應用程式註冊。

下列情況是使用現有應用程式註冊的最常見案例：

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

您可以建立和使用新的應用程式註冊（選項 1）或使用個別建立的現有註冊（選項 2）。

選項 1：建立並使用新的應用程式註冊

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

注意

自動建立新註冊的選項不適用於政府雲端。 反之，請個別定義註冊。

  1. 選取 [ 建立新的應用程式註冊]。

  2. 輸入新應用程式註冊的 [名稱]。

  3. 選取 [支援的帳戶類型]：

    • 目前租用戶 - 單一租用戶。 僅此組織目錄中的帳戶。 您目錄中的所有使用者及來賓帳戶都能使用您的應用程式或 API。 若您的目標對象是組織內部的人員，請使用此選項。
    • 任何 Microsoft Entra 目錄 - 多租用戶。 任何組織目錄中的帳戶。 所有使用者只要具備 Microsoft 提供的公司或學校帳戶，都能使用您的應用程式或 API。 這些帳戶包括使用 Office 365 的學校和企業。 若目標對象是商務界或教育界的客戶，且要啟用多租用戶的話，請使用此選項。
    • 任何 Microsoft Entra 目錄和個人 Microsoft 帳戶。 任何組織目錄中的帳戶和個人 Microsoft 帳戶 (例如 Skype、Xbox)。 具有公司、學校或個人 Microsoft 帳戶 Microsoft 帳戶的使用者可以使用您的應用程式或 API。 這也包括了使用 Office 365 的學校和公司，以及用來登入例如 Xbox 和 Skype 服務的個人帳戶。 若要涵蓋最多種類的 Microsoft 識別，且要啟用多租用戶的話，請使用此選項。
    • 僅限個人 Microsoft 帳戶。 用於登入 Xbox 及 Skype 等服務的個人帳戶。 使用此選項可涵蓋最多種類的 Microsoft 身分識別。

您要的話，可以稍後再變更註冊的名稱或支援的帳戶類型。

用戶端密碼會建立為名為 MICROSOFT_PROVIDER_AUTHENTICATION_SECRET 的插槽黏性應用程式設定。 如果您想要在 Azure 金鑰保存庫 中管理秘密，您可以稍後更新該設定，以使用 金鑰保存庫 參考。

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

選取任一個選項：

  • 在此目錄中 挑選現有的應用程式註冊，然後從下拉式清單中選取應用程式註冊。

  • 提供現有應用程式註冊 的詳細數據，並提供：

    • 應用程式 （用戶端） 識別碼。
    • 用戶端密碼 （建議） 。 應用程式在要求權杖時用來證明其身分識別的祕密值。 此值會在應用程式的設定中儲存為名為 MICROSOFT_PROVIDER_AUTHENTICATION_SECRET 的插槽黏性應用程式設定。 如果未設定客戶端密碼，則來自服務的登入作業會使用 OAuth 2.0 隱含授與流程，不建議這麼做。
    • 簽發者 URL，其格式為 <authentication-endpoint>/<tenant-id>/v2.0。 將 <authentication-endpoint> 取代為雲端環境專屬的驗證端點值。 例如，全域 Azure 中的員工租用戶會使用 "https://sts.windows.net" 做為其驗證端點。

如果您需要在員工租使用者中手動建立應用程式註冊，請參閱使用 Microsoft 身分識別平台 註冊應用程式。 完成註冊程序後，請務必記下應用程式 (用戶端) 識別碼和用戶端密碼值。

在註冊程序期間，在 [重新導向 URI] 區段中選取 [Web] 作為平台，並輸入 <app-url>/.auth/login/aad/callback。 例如： https://contoso.azurewebsites.net/.auth/login/aad/callback 。

在建立之後，修改應用程式註冊：

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

    針對單一租用戶應用程式，您可以使用預設值，其格式為 api://<application-client-id>。 您也可以根據租用戶的其中一個已驗證網域來指定更具可讀性的 URI (例如 https://contoso.com/api)。 對於多租用戶應用程式，您必須提供自訂 URI。 如需應用程式識別碼 URI 接受格式的詳細資訊，請參閱 Microsoft Entra ID 中應用程式屬性的安全性最佳做法。

  2. 選取新增範圍。

    1. 在 [範圍名稱] 中，輸入 user_impersonation。
    2. 在 [有權同意者]，如果您想要允許使用者同意此範圍，請選取 [管理員和使用者]。
    3. 輸入同意範圍名稱。 輸入您希望使用者在同意頁面上看到的描述。 例如，輸入 Access <application-name>。
    4. 選取新增範圍。

  3. (建議) 若要建立用戶端密碼：

    1. 從左側導覽，選取 [憑證與秘密]> [用戶端密碼]> [新增用戶端密碼]。
    2. 輸入描述和到期日，然後選取 [新增]。
    3. 在 [值] 欄位，複製用戶端密碼值。 在您離開此頁面之後，它就不會再次出現。

  4. (選擇性) 若要新增多個 [回覆 URL]，請選取 [驗證]。

設定其他檢查

其他檢查 會決定允許哪些要求存取您的應用程式。 您可以立即自訂此行為，或稍後從主要 [驗證] 畫面調整這些 [設定]，方法是選擇 [驗證設定] 旁的 [編輯]。

針對 [用戶端應用程式需求]，請選擇是否要：

  • 僅允許來自此應用程式本身的要求
  • 允許來自特定用戶端應用程式的要求
  • 允許來自任何應用程式的要求 (不建議使用)

針對 [身分識別需求]，請選擇是否要：

  • 允許來自任何身分識別的要求
  • 允許來自特定身分識別的要求

針對 [租用戶需求]，請選擇是否要：

  • 僅允許來自簽發者租用戶的要求
  • 允許來自特定租用戶的要求
  • 根據簽發者使用預設限制

您的應用程式可能仍然需要在程式碼中做出其他授權決策。 如需詳細資訊，請參閱使用內建授權原則。

設定驗證設定

這些選項決定應用程式如何回應未經驗證的要求。 預設選項會將所有要求改為使用此新的提供者登入。 您可以立即變更自訂此行為，或稍後從主要 [驗證] 畫面選擇 [驗證設定] 旁的 [編輯]，以調整這些 [設定]。 如需詳細資訊，請參閱驗證流程。

針對 [限制存取]，請決定是否要：

  • 要求驗證
  • 允許未驗證的存取

針對未驗證的要求

  • HTTP 302 找到重新導向：建議用於網站
  • HTTP 401 未經授權：建議用於 API
  • HTTP 403 禁止
  • HTTP 404 找不到

選取 [權杖存放區] (建議使用)。 權杖存放區會收集、儲存及重新整理應用程式的權杖。 如果您的應用程式不需要令牌，或需要優化效能，您可以稍後停用此行為。

新增識別提供者

如果您選取了員工設定，您可以選取 [下一步：權限]，新增應用程式所需的任何 Microsoft Graph 權限。 這些許可權會新增至應用程式註冊，但您也可以稍後加以變更。 如果選取了外部設定，您後續可以新增 Microsoft Graph 權限。

  • 選取 [新增]。

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

如需為存取 Azure 儲存體 和 Microsoft Graph 的 Web 應用程式設定 Microsoft Entra 登入的範例，請參閱將應用程式驗證新增至您的 Web 應用程式。

授權要求

根據預設，App Service 驗證只會處理 驗證。 它會判斷來電者是否為他們所說的人。 授權，判斷該呼叫端是否應該具有某些資源的存取權，是驗證以外的步驟。 如需詳細資訊，請參閱 授權基本概念。

您的應用程式可以以程式碼進行授權決策。 App Service 驗證提供一些 內建檢查，可有所説明，但它們本身可能不足以涵蓋您應用程式的授權需求。

提示

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

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

當您在應用程式程式碼中執行授權檢查時，可以使用 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 authentication V2 API 來啟用內建檢查。 目前，設定這些內建檢查的唯一方式是使用 Azure Resource Manager 範本 或 REST API。

在 API 物件內，Microsoft Entra 身分識別提供者組態有一個 validation 區段可包含 defaultAuthorizationPolicy 物件，如下列結構所示：

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

此原則會評估傳入權杖 (必須是存取權杖) 的 appid 或 azp 宣告。 請參閱 承載宣告。
allowedPrincipals 一組檢查，判斷傳入要求所代表的主體是否可以存取應用程式。 是否滿足 allowedPrincipals 會針對其已設定的屬性，根據邏輯 OR 來決定。
identities (在 allowedPrincipals 之下) 字串物件識別碼的允許清單，代表具有存取權的使用者或應用程式。 當此屬性設為非空白的陣列時，如果在清單中指定了要求所代表的使用者或應用程式，allowedPrincipals 需求就可以被滿足。 身分識別清單中總共有 500 個字元的限制。

此原則會評估傳入權杖的 oid 宣告。 請參閱 承載宣告。

此外，不論所使用的 API 版本為何，都可以透過 應用程式設定來設定某些檢查。 應用程式 WEBSITE_AUTH_AAD_ALLOWED_TENANTS 設定可以使用最多10個租使用者標識碼的逗號分隔清單進行設定，例如 aaaabbbb-0000-cccc-1111-dddd2222eeee。

此設定可能會要求傳入令牌來自其中一個指定的租使用者，如宣告所 tid 指定。 WEBSITE_AUTH_AAD_REQUIRE_CLIENT_SERVICE_PRINCIPAL應用程式設定可以設定為 true 或 1 要求傳入令牌以包含oid宣告。 如果 allowedPrincipals.identities 已設定，則會忽略此設定，並視為 true，因為 oid 會針對此提供的身分識別清單檢查宣告。

未通過這些內建檢查的要求將收到 HTTP 403 Forbidden 的回應。

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

在先前的小節中，您已註冊 App Service 或 Azure Function 來驗證使用者。 本節說明如何在 Microsoft Entra 中註冊原生用戶端或精靈應用程式。 他們可以代表使用者或本身要求存取 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 應用程式建立的應用程式註冊。 如果您沒有看到應用程式註冊，請務必在應用程式註冊中新增 user_impersonation 範圍。

  9. 在 [委派權限] 底下，選取 [user_impersonation]，然後選取 [新增權限]。

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

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

在多層式架構中，用戶端應用程式可以取得令牌，代表用戶端應用程式本身呼叫 App Service 或函式應用程式，而不是代表使用者。 此案例適用於未使用已登入使用者來執行工作的非互動式精靈應用程式。 其會使用標準 OAuth 2.0 用戶端認證授與。 如需詳細資訊，請參閱 Microsoft 身分識別平台 和 OAuth 2.0 用戶端認證流程。

  1. 從 Azure 入口網站功能表，選取 [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. 確實選取 [授與管理員同意]，以授權用戶端應用程式要求權限。

    類似於先前的案例（新增任何角色之前），您現在可以要求相同目標的resource存取令牌，而存取令牌包含roles包含用戶端應用程式授權的應用程式角色的宣告。

在目標 App Service 或函式應用程式程式代碼內，您現在可以驗證令牌中是否有預期的角色。 App Service 驗證不會執行此驗證。 如需詳細資訊，請參閱存取使用者宣告。

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

最佳作法

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

  • 在 Microsoft Entra 中設定每個 App Service 應用程式及其本身的應用程式註冊。
  • 為每個 App Service 應用程式提供其自己的權限並予以同意。
  • 避免在環境之間共享許可權。 針對不同的部署位置使用個別的應用程式註冊。 測試新的程式碼時，這種作法有助於避免問題影響到生產應用程式。

移轉至 Microsoft Graph

某些較舊的應用程式可能會與已淘汰的 Azure AD Graph 相依性進行設定，其排程為完整淘汰。 例如，您的應用程式程式代碼可能會呼叫 Azure AD Graph，以在中間件管線中檢查群組成員資格作為授權篩選的一部分。 應用程式應該移至 Microsoft Graph。 如需詳細資訊，請參閱 將您的應用程式從 Azure AD Graph 遷移至 Microsoft Graph。

在此移轉期間，您可能需要對 App Service 驗證的設定進行一些變更。 將Microsoft Graph 許可權新增至應用程式註冊之後，您可以：

  1. 如果簽發者 URL 尚未包含後綴，/v2.0請更新它。

  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 的令牌。 您應用程式程式代碼的任何使用該令牌也需要更新，如將應用程式從 Azure AD Graph 遷移至 Microsoft Graph 中所述。

後續步驟