共用方式為

將 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：建立並使用新的應用程式註冊

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

注意

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

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

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

  • 目前租用戶 - 單一租用戶。 僅此組織目錄中的帳戶。 您目錄中的所有使用者及來賓帳戶都能使用您的應用程式或 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 Key Vault 中的祕密，稍後可以將該設定更新為使用 Key Vault 參考。

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

任一：

  • 選取 [在此目錄中挑選現有的應用程式註冊]，然後從下拉式清單中選取應用程式註冊。
  • 選取 [提供現有應用程式註冊的詳細資料]，並提供：
    • 應用程式 (用戶端) 識別碼。
    • 用戶端密碼 (建議)。 應用程式在要求權杖時用來證明其身分識別的祕密值。 此值會在應用程式的設定中儲存為名為 MICROSOFT_PROVIDER_AUTHENTICATION_SECRET 的插槽黏性應用程式設定。 如果未設定客戶端密碼，則來自服務的登入作業會使用 OAuth 2.0 隱含授與流程，不建議這麼做。
    • 簽發者 URL，其格式為 <authentication-endpoint>/<tenant-id>/v2.0。 將 <authentication-endpoint> 取代為雲端環境專屬的驗證端點值。 例如，全域 Azure 中的員工租用戶會使用 "https://sts.windows.net" 做為其驗證端點。

如果需要手動在員工租用戶中建立應用程式註冊，請遵循註冊應用程式快速入門。 完成註冊程序後，請務必記下應用程式 (用戶端) 識別碼和用戶端密碼值。

在註冊程序期間，在 [重新導向 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 的已接受格式，請參閱應用程式註冊最佳做法參考。

  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 登入的範例，請參閱此教學課程。

授權要求

根據預設，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 authentication V2 API 來啟用內建檢查。 目前，設定這些內建檢查的唯一方式是透過 Azure Resource Manager 範本或 REST API。

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

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

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

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

此外，不論使用的 API 版本為何，都可以透過應用程式設定設定某些檢查。 WEBSITE_AUTH_AAD_ALLOWED_TENANTS應用程式設定可設定最多 10 個租使用者標識碼的逗號分隔清單（例如，“aaaabbbb-0000-cccc-1111-dddd222eeee”），要求傳入令牌來自其中一個指定的租使用者，如宣告所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]。

  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 或 Function 應用程式。 此案例適用於未使用已登入使用者來執行工作的非互動式精靈應用程式。 其會使用標準 OAuth 2.0 用戶端認證授與。

  1. 從入口網站功能表，選取 [Microsoft Entra]。
  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 或 Function 應用程式的程式碼內，您現在可以驗證預期的角色是否存在於權杖中 (這不會由 App Service 驗證執行)。 如需詳細資訊，請參閱存取使用者宣告。

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

最佳作法

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

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

移轉至 Microsoft Graph

某些較舊的應用程式可能還會設定為依賴已淘汰的 Azure AD Graph，這項服務已排程進行完整停用。 例如，在中介軟體管道的授權篩選期間，您的應用程式程式碼可能會呼叫 Azure AD Graph 檢查群組成員資格。 依照 Microsoft Entra 在 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 的權仗。 根據 Microsoft Entra 提供的指引，您也必須更新在應用程式程式碼中對該權杖的任何使用。

後續步驟