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

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

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

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

語言/架構	專案平台 GitHub	套件	開始 啟動	登入使用者	存取 Web API	正式發行 (GA) 或 公開預覽1
.NET	MSAL.NET	Microsoft.Identity.Client	—			GA
.NET	Microsoft.IdentityModel	Microsoft.IdentityModel	—	2	2	GA
ASP.NET Core	ASP.NET Core	Microsoft.AspNetCore.Authentication	快速入門			GA
ASP.NET Core	Microsoft.Identity.Web	Microsoft.Identity.Web	快速入門			GA
Java	MSAL4J	msal4j	快速入門			GA
Spring	spring-cloud-azure-starter-active-directory	spring-cloud-azure-starter-active-directory	教學課程			GA
Node.js	MSAL 節點	msal-node	快速入門			GA
Python	MSAL Python	msal				GA
Python	identity	identity	快速入門			--

⁽¹⁾線上服務的通用授權條款適用於公開預覽中的程式庫。

⁽²⁾ Microsoft.IdentityModel 程式庫只會驗證權杖，無法要求識別碼或存取權杖。

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

ASP.NET Core

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

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

ASP.NET

本文中程式碼範例和以下項目是從 ASP.NET Web 應用程式 範例擷取的。

建議參考本範例以取得完整實作的詳細資料。

Java

本文中的程式碼片段和下列內容節錄自 MSAL Java 中 java web 應用程式呼叫 Microsoft graph 的範例。

建議參考本範例以取得完整實作的詳細資料。

Node.js

本文中的程式碼片段和下列內容節錄自 MSAL Node中 Node.jp web 應用程式登入使用者範例。

建議參考本範例以取得完整實作的詳細資料。

Python

本文中的程式碼片段和下列程式碼片段會從呼叫 Microsoft 圖形的 Python Web 應用程式擷取，範例使用身分識別套件 (MSAL Python 的包裝函式)。

建議參考本範例以取得完整實作的詳細資料。

組態檔

使用 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

在 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。 原因是 applicationUrl 是 http://localhost:3110，但指定了 sslPort (44321)。 CallbackPath即是/signin-oidc，如appsettings.json所定義。

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

注意

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

ASP.NET

在 ASP.NET 中，應用程式是透過appsettings.json檔 (12 行到 15 行) 設定。

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

在 Azure 入口網站中，您在應用程式的 [驗證] 頁面上註冊的回覆 URI 必須符合這些 URL。 也就是說，它們應該是https://localhost:44326/。

Java

在 Java 中，設定位於位於位於中src/main/resources下面的應用程式屬性檔案。

aad.clientId=Enter_the_Application_Id_here
aad.authority=https://login.microsoftonline.com/Enter_the_Tenant_Info_Here/
aad.secretKey=Enter_the_Client_Secret_Here
aad.redirectUriSignin=http://localhost:8080/msal4jsample/secure/aad
aad.redirectUriGraph=http://localhost:8080/msal4jsample/graph/me

在 Azure 入口網站中，您在應用程式的 [驗證] 頁面上註冊的回覆 URI 必須符合應用程式定義的 redirectUri 執行個體。 也就是說，它們應該是http://localhost:8080/msal4jsample/secure/aad和http://localhost:8080/msal4jsample/graph/me。

Node.js

在這裡，作為環境變數的設定參數會位於 .env.dev：

CLOUD_INSTANCE="Enter_the_Cloud_Instance_Id_Here" # cloud instance string should end with a trailing slash
TENANT_ID="Enter_the_Tenant_Info_Here"
CLIENT_ID="Enter_the_Application_Id_Here"
CLIENT_SECRET="Enter_the_Client_Secret_Here"

REDIRECT_URI="http://localhost:3000/auth/redirect"
POST_LOGOUT_REDIRECT_URI="http://localhost:3000"

GRAPH_API_ENDPOINT="Enter_the_Graph_Endpoint_Here" # graph api endpoint string should end with a trailing slash

EXPRESS_SESSION_SECRET="Enter_the_Express_Session_Secret_Here"

這些參數是用來在 authConfig.js 檔案中建立設定物件，且最終用來初始化 MSAL 節點：

/*
 * Copyright (c) Microsoft Corporation. All rights reserved.
 * Licensed under the MIT License.
 */

require('dotenv').config({ path: '.env.dev' });

/**
 * Configuration object to be passed to MSAL instance on creation.
 * For a full list of MSAL Node configuration parameters, visit:
 * https://github.com/AzureAD/microsoft-authentication-library-for-js/blob/dev/lib/msal-node/docs/configuration.md
 */
const msalConfig = {
    auth: {
        clientId: process.env.CLIENT_ID, // 'Application (client) ID' of app registration in Azure portal - this value is a GUID
        authority: process.env.CLOUD_INSTANCE + process.env.TENANT_ID, // Full directory URL, in the form of https://login.microsoftonline.com/<tenant>
        clientSecret: process.env.CLIENT_SECRET // Client secret generated from the app registration in Azure portal
    },
    system: {
        loggerOptions: {
            loggerCallback(loglevel, message, containsPii) {
                console.log(message);
            },
            piiLoggingEnabled: false,
            logLevel: 3,
        }
    }
}

const REDIRECT_URI = process.env.REDIRECT_URI;
const POST_LOGOUT_REDIRECT_URI = process.env.POST_LOGOUT_REDIRECT_URI;
const GRAPH_ME_ENDPOINT = process.env.GRAPH_API_ENDPOINT + "v1.0/me";

module.exports = {
    msalConfig,
    REDIRECT_URI,
    POST_LOGOUT_REDIRECT_URI,
    GRAPH_ME_ENDPOINT
};

在 Azure 入口網站中，您在應用程式的 [驗證] 頁面上註冊的回覆 URI 必須符合應用程式定義 (http://localhost:3000/auth/redirect) 的 redirectUri 執行個體。

為了簡單起見，用戶端密碼會儲存在設定檔中。 在生產應用程式中，請考慮使用金鑰保存庫或環境變數。 更好的選項是使用憑證。

Python

設定參數在 .env 中設定為環境變數：

# Note: If you are using Azure App Service, go to your app's Configuration,
# and then set the following values into your app's "Application settings".

CLIENT_ID=<client id>
CLIENT_SECRET=<client secret>

# Expects a full authority URL such as "https://login.microsoftonline.com/TENANT_GUID"
# or "https://login.microsoftonline.com/contoso.onmicrosoft.com".
# Alternatively, leave it undefined if you are building a multi-tenant app in world-wide cloud
#AUTHORITY=<authority url>

這些環境變數會在 app_config.py 中參考：

import os

# Application (client) ID of app registration
CLIENT_ID = os.getenv("CLIENT_ID")
# Application's generated client secret: never check this into source control!
CLIENT_SECRET = os.getenv("CLIENT_SECRET")

# You can configure your authority via environment variable
# Defaults to a multi-tenant app in world-wide cloud
AUTHORITY = os.getenv("AUTHORITY", "https://login.microsoftonline.com/common")

REDIRECT_PATH = "/getAToken"  # Used for forming an absolute URL to your redirect URI.
# The absolute URL must match the redirect URI you set
# in the app's registration in the Azure portal.

# You can find more Microsoft Graph API endpoints from Graph Explorer
# https://developer.microsoft.com/en-us/graph/graph-explorer
ENDPOINT = 'https://graph.microsoft.com/v1.0/users'  # This resource requires no admin consent

# You can find the proper permission names from this document
# https://docs.microsoft.com/en-us/graph/permissions-reference
SCOPE = ["User.ReadBasic.All"]

# Tells the Flask-session extension to store sessions in the filesystem
SESSION_TYPE = "filesystem"
# Using the file system will not work in most production systems,
# it's better to use a database-backed session store instead.

.env 檔案不應該簽入原始檔控制，因為它包含秘密。 快速入門範例包含 .gitignore 檔案，可防止簽入 .env 檔案。

# Environments
.env

初始化程式碼

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

ASP.NET Core

在 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 SingleOrg或dotnet 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 身別識別 Web 和 Microsoft 身別識別 Web UI NuGet 套件新增至您的專案中。 如果 NuGet 套件存在，請移除 Microsoft.AspNetCore.Authentication.AzureAD.UI 。

2. 更新中ConfigureServices的程式碼，使其使用AddMicrosoftIdentityWebApp和AddMicrosoftIdentityUI方法。

   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.cs 的 Configure 方法中，透過呼叫 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 應用程式。

ASP.NET

ASP.NET web 應用程式和 web API 中的相關驗證程式碼位於 App_Start/startup.auth.cs 檔中。

 public void ConfigureAuth(IAppBuilder app)
 {
  app.SetDefaultSignInAsAuthenticationType(CookieAuthenticationDefaults.AuthenticationType);

  app.UseCookieAuthentication(new CookieAuthenticationOptions());

  OwinTokenAcquirerFactory factory = TokenAcquirerFactory.GetDefaultInstance<OwinTokenAcquirerFactory>();
  factory.Build();
  app.AddMicrosoftIdentityWebApi(factory);
 }

Java

JAVA 範例會使用 Spring 架構。 應用程式會受到保護，因為您執行的篩選準則可攔截每個 HTTP 回應。 在 JAVA web 應用程式的快速入門中，此篩選是src/main/java/com/microsoft/azure/msalwebsample/AuthFilter.java中的AuthFilter。

篩選器會處理 OAuth 2.0 授權碼流程，並檢查使用者是否已進行驗證 (方法isAuthenticated())。 如果使用者未經過驗證，則會計算 Microsoft Entra 授權端點的 URL，並將瀏覽器重新導向至這個 URI。

當回應 (包含授權碼) 抵達時，它會使用 MSAL Java 取得權杖。 當它最後收到權杖端點 (重新導向 URI) 的權杖時，使用者就會登入。

如需詳細資訊，請參閱 AuthFilter.java 中的doFilter()方法。

注意

doFilter()的程式碼撰寫順序稍有不同，但流程則如所述。

如需此方法觸發授權碼流程的詳細資訊，請參閱Microsoft 身分識別平台和 OAuth 2.0 授權碼流程。

Node.js

Node 範例會使用 Express 架構。 MSAL 會在驗證路由處理常式中初始化：

var express = require('express');

const authProvider = require('../auth/AuthProvider');
const { REDIRECT_URI, POST_LOGOUT_REDIRECT_URI } = require('../authConfig');

const router = express.Router();

router.get('/signin', authProvider.login({
    scopes: [],
    redirectUri: REDIRECT_URI,
    successRedirect: '/'

Python

Python 範例是使用 Flask 架構所建置，不過 Django 等其他架構也可以使用。 Flask 應用程式會使用位於 app.py 頂端的應用程式組態來初始化：

import identity
import identity.web
import requests
from flask import Flask, redirect, render_template, request, session, url_for
from flask_session import Session

import app_config

app = Flask(__name__)
app.config.from_object(app_config)
Session(app)

然後，程式碼會使用身分識別套件建構auth物件。

auth = identity.web.Auth(
    session=session,
    authority=app.config["AUTHORITY"],
    client_id=app.config["CLIENT_ID"],
    client_credential=app.config["CLIENT_SECRET"],
)

下一步

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

ASP.NET Core

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

ASP.NET

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

Java

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

Node.js

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

Python

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