分享方式:


登入使用者的 Web 應用程式:程式碼設定

了解如何設定可登入使用者的 web 應用程式的程式碼。

支援 Web 應用程式的 Microsoft 程式庫

下列 Microsoft 程式庫用來保護 Web 應用程式 (和 web API):

語言/架構 專案平台
GitHub
套件 開始
啟動
登入使用者 存取 Web API 正式發行 (GA)
公開預覽1
.NET MSAL.NET Microsoft.Identity.Client 程式庫無法要求供使用者登入的識別碼權杖。 程式庫可以要求受保護 Web API 的存取權杖。 GA
.NET Microsoft.IdentityModel Microsoft.IdentityModel 程式庫無法要求供使用者登入的識別碼權杖。2 程式庫無法要求受保護 Web API 的存取權杖。2 GA
ASP.NET Core ASP.NET Core Microsoft.AspNetCore.Authentication 快速入門 程式庫可以要求供使用者登入的識別碼權杖。 程式庫無法要求受保護 Web API 的存取權杖。 GA
ASP.NET Core Microsoft.Identity.Web Microsoft.Identity.Web 快速入門 程式庫可以要求供使用者登入的識別碼權杖。 程式庫可以要求受保護 Web API 的存取權杖。 GA
Java MSAL4J msal4j 快速入門 程式庫可以要求供使用者登入的識別碼權杖。 程式庫可以要求受保護 Web API 的存取權杖。 GA
Spring spring-cloud-azure-starter-active-directory spring-cloud-azure-starter-active-directory 教學課程 程式庫可以要求供使用者登入的識別碼權杖。 程式庫可以要求受保護 Web API 的存取權杖。 GA
Node.js MSAL 節點 msal-node 快速入門 程式庫可以要求供使用者登入的識別碼權杖。 程式庫可以要求受保護 Web API 的存取權杖。 GA
Python MSAL Python msal 程式庫可以要求供使用者登入的識別碼權杖。 程式庫可以要求受保護 Web API 的存取權杖。 GA
Python identity identity 快速入門 程式庫可以要求供使用者登入的識別碼權杖。 程式庫可以要求受保護 Web API 的存取權杖。 --

(1)線上服務的通用授權條款適用於公開預覽中的程式庫。

(2) Microsoft.IdentityModel 程式庫只會驗證權杖,無法要求識別碼或存取權杖。

選取您感興趣之平台對應的索引標籤:

本文中的程式碼片段和下列內容節錄自ASP.NET Core 的 web 應用程式遞增教學課程 (第1章)

建議參考本教學課程以取得完整實作的詳細資料。

組態檔

使用 Microsoft 身分識別平台來登入使用者的 Web 應用程式是透過設定檔設定。 這些檔案必須指定下列值:

  • 例如,如果您想要讓應用程式在國家雲端中執行,則為雲端執行個體。 不同的選項包括;
    • Azure 公用雲端的 https://login.microsoftonline.com/
    • https://login.microsoftonline.us/ 適用於 Azure US Government
    • https://login.microsoftonline.de/ 適用於 Microsoft 德國
    • https://login.partner.microsoftonline.cn/common 適用於由 21Vianet 營運的 Microsoft Entra China
  • 租用戶識別碼中的對象。 選項會根據您的應用程式是單一租用戶或多租用戶而有所不同。
    • 從 Azure 入口網站取得的租用戶 GUID,以登入您組織中的使用者。 您也可以使用網域名稱。
    • organizations 以在任何公司或學校帳戶中登入使用者
    • common 以任何公司或學校帳戶或 Microsoft 個人帳戶登入使用者
    • consumers 僅使用 Microsoft 個人帳戶登入使用者
  • 從 Azure 入口網站複製的應用程式的用戶端識別碼

您也可以看到授權單位的參考、執行個體串連和租用戶識別碼值。

在 ASP.NET Core 中,這些設定位於 "Microsoft Entra ID" 區段的 appsettings.json 檔案中。

{
  "AzureAd": {
    "Instance": "https://login.microsoftonline.com/",
    "TenantId": "[Enter the tenantId here]",

    // Client ID (application ID) obtained from the Azure portal
    "ClientId": "[Enter the Client Id here]",
    "CallbackPath": "/signin-oidc",
    "SignedOutCallbackPath": "/signout-oidc"
  }
}

在 ASP.NET Core 中,另一個檔案 (properties\launchSettings.json) 包含 URL (applicationUrl),以及適用於您的應用程式和各種設定檔的 TLS/SSL 埠 (sslPort)。

{
  "iisSettings": {
    "windowsAuthentication": false,
    "anonymousAuthentication": true,
    "iisExpress": {
      "applicationUrl": "http://localhost:3110/",
      "sslPort": 44321
    }
  },
  "profiles": {
    "IIS Express": {
      "commandName": "IISExpress",
      "launchBrowser": true,
      "environmentVariables": {
        "ASPNETCORE_ENVIRONMENT": "Development"
      }
    },
    "webApp": {
      "commandName": "Project",
      "launchBrowser": true,
      "environmentVariables": {
        "ASPNETCORE_ENVIRONMENT": "Development"
      },
      "applicationUrl": "http://localhost:3110/"
    }
  }
}

在 Azure 入口網站中,您在應用程式的 [驗證] 頁面上註冊的重新導向 URI 必須符合這些 URL。 針對上述兩個設定檔為https://localhost:44321/signin-oidc。 原因是 applicationUrlhttp://localhost:3110,但指定了 sslPort (44321)。 CallbackPath即是/signin-oidc,如appsettings.json所定義。

以同樣的方式,登出 URI 會設定為https://localhost:44321/signout-oidc

注意

SignedOutCallbackPath 應設定為入口網站或應用程式,以避免在處理事件時發生衝突。

初始化程式碼

初始化程式碼差異為平台依存性。 針對 ASP.NET Core 和 ASP.NET,登入使用者會委派給 OpenID Connect 中介軟體。 ASP.NET 或 ASP.NET Core 範本會產生 Azure AD v1.0 端點的 web 應用程式。 需要進行某些設定才能將它們調整適用於 Microsoft 身分識別平台。

在 ASP.NET Core web 應用程式 (和 web API) 中,應用程式會受到保護,因為您在控制器或控制器動作上有Authorize屬性。 此屬性會檢查使用者是否已驗證。 在 .NET 6 版本之前,程式碼初始化是在 Startup.cs 檔案中。 具有 .NET 6 的新 ASP.NET Core 專案不再包含 Startup.cs 檔案。 其位置是 Program.cs 檔案。 本教學課程的其餘部分與 .NET 5 或更低版本有關。

注意

如果您想要直接使用適用於 Microsoft 身分識別平台的新 ASP.NET Core 範本來啟動,以利用 web.config,您可以下載包含 .NET 5.0 專案範本的預覽 NuGet 套件。 然後,安裝之後,您就可以直接將 ASP.NET Core 的 web 應用程式具現化 (MVC 或 Blazor)。 如需詳細資訊,請參閱 Microsoft 身分識別 web 應用程式專案範本。 這是最簡單的方法,因為該方法會為您執行下列所有步驟。

如果您想要使用 Visual Studio 中的目前預設 ASP.NET Core Web 專案來啟動專案,或使用dotnet new mvc --auth SingleOrgdotnet new webapp --auth SingleOrg,您將會看到如下所示的程式碼:

 services.AddAuthentication(AzureADDefaults.AuthenticationScheme)
         .AddAzureAD(options => Configuration.Bind("AzureAd", options));

此程式碼會使用舊版的 Microsoft.AspNetCore.Authentication.AzureAD.UI,NuGet 封裝,來建立 Azure Active Directory v1.0 應用程式。 本文說明如何建立 Microsoft 身分識別平台 v2.0 應用程式來取代該程式碼。

  1. Microsoft 身別識別 WebMicrosoft 身別識別 Web UI NuGet 套件新增至您的專案中。 如果 NuGet 套件存在,請移除 Microsoft.AspNetCore.Authentication.AzureAD.UI

  2. 更新中ConfigureServices的程式碼,使其使用AddMicrosoftIdentityWebAppAddMicrosoftIdentityUI方法。

    public class Startup
    {
     ...
     // This method gets called by the runtime. Use this method to add services to the container.
     public void ConfigureServices(IServiceCollection services)
     {
      services.AddAuthentication(OpenIdConnectDefaults.AuthenticationScheme)
             .AddMicrosoftIdentityWebApp(Configuration, "AzureAd");
    
      services.AddRazorPages().AddMvcOptions(options =>
      {
       var policy = new AuthorizationPolicyBuilder()
                     .RequireAuthenticatedUser()
                     .Build();
       options.Filters.Add(new AuthorizeFilter(policy));
      }).AddMicrosoftIdentityUI();
    
  3. Startup.csConfigure 方法中,透過呼叫 app.UseAuthentication();app.MapControllers(); 來啟用驗證。

    // This method gets called by the runtime. Use this method to configure the HTTP request pipeline.
    public void Configure(IApplicationBuilder app, IWebHostEnvironment env)
    {
     // more code here
     app.UseAuthentication();
     app.UseAuthorization();
    
     app.MapRazorPages();
     app.MapControllers();
     // more code here
    }
    

在該程式碼中:

  • AddMicrosoftIdentityWebApp擴充方法是在 Microsoft.Identity.Web 中定義,其中;

    • 設定選項以讀取設定檔 (這裡從 “Microsoft Entra ID”區段中讀取)
    • 設定 OpenID Connect 選項,讓 Microsoft 身分識別平台成為授權單位。
    • 驗證權杖的簽發者。
    • 確保從識別碼權杖中的preferred_username宣告對應至相對名稱的宣告。
  • 除了設定物件之外,您還可以在呼叫AddMicrosoftIdentityWebApp時指定設定區段的名稱。 預設為AzureAd

  • AddMicrosoftIdentityWebApp具有優勢案例的其他參數。 例如,追蹤 OpenID Connect 中介軟體事件可協助您疑難排解 web 應用程式 (如果驗證無法運作)。 將選擇性參數subscribeToOpenIdConnectMiddlewareDiagnosticsEvents設定為true,會顯示 ASP.NET Core 中介軟體從 HTTP 回應到中 HttpContext.User 的使用者身分識別時,如何處理資訊。

  • AddMicrosoftIdentityUI擴充方法是在 Microsft 身分識別 Web 中定義。 該方法提供預設控制器來處理登入和登出。

如需 Microsoft.Identity.Web 如何讓您建立 Web 應用程式的詳細資訊,請參閱 microsoft-identity-web 中的 Web 應用程式

下一步

在下一篇文章中,您將了解如何觸發登入和登出。

請移至本案例的下一篇文章,登入並登出