撰寫登入/註銷使用者的 Web 應用程式 - Microsoft identity platform

文章
01/30/2024

瞭解如何將登入新增至登入使用者的 Web 應用程式程式代碼。然後，瞭解如何讓他們註銷。

登入包含兩個部分：

HTML 頁面上的登入按鈕
控制器程式代碼後置中的登入動作

在 ASP.NET Core 中，針對 Microsoft 身分識別平台應用程式，[登入] 按鈕會公開於 Views\Shared\_LoginPartial.cshtml （適用於 MVC 應用程式）或 Pages\Shared\_LoginPartial.cshtm [Razor 應用程式]。只有當使用者未通過驗證時，才會顯示它。也就是說，當使用者尚未登入或已註銷時，就會顯示它。相反地， 當用戶已經登入時，會顯示 [註銷 ] 按鈕。請注意，帳戶控制器定義於 Microsoft.Identity.Web.UI NuGet 套件中名為 MicrosoftIdentity 的區域

<ul class="navbar-nav">
  @if (User.Identity.IsAuthenticated)
  {
    <li class="nav-item">
        <span class="navbar-text text-dark">Hello @User.Identity.Name!</span>
    </li>
    <li class="nav-item">
        <a class="nav-link text-dark" asp-area="MicrosoftIdentity" asp-controller="Account" asp-action="SignOut">Sign out</a>
    </li>
  }
  else
  {
    <li class="nav-item">
        <a class="nav-link text-dark" asp-area="MicrosoftIdentity" asp-controller="Account" asp-action="SignIn">Sign in</a>
    </li>
  }
</ul>

在 ASP.NET MVC 中， [登入 ] 按鈕會在中 Views\Shared\_LoginPartial.cshtml公開。只有當使用者未通過驗證時，才會顯示它。也就是說，當使用者尚未登入或已註銷時，就會顯示它。

@if (Request.IsAuthenticated)
{
 // Code omitted code for clarity
}
else
{
    <ul class="nav navbar-nav navbar-right">
        <li>@Html.ActionLink("Sign in", "SignIn", "Account", routeValues: null, htmlAttributes: new { id = "loginLink" })</li>
    </ul>
}

在 Java 快速入門中，登入按鈕位於 main/resources/templates/index.html 檔案中。

<!DOCTYPE html>
<html xmlns:th="http://www.thymeleaf.org">
<head>
    <meta charset="UTF-8">
    <title>HomePage</title>
</head>
<body>
<h3>Home Page</h3>

<form action="/msal4jsample/secure/aad">
    <input type="submit" value="Login">
</form>

</body>
</html>

在Node.js快速入門中，登入按鈕的程式代碼位於 index.hbs 範本檔案中。

<p>Welcome to {{title}}</p>
<a href="/auth/signin">Sign in</a>

此樣本是透過應用程式的主要（index）路由來提供：

var express = require('express');
var router = express.Router();

router.get('/', function (req, res, next) {
    res.render('index', {
        title: 'MSAL Node & Express Web App',
        isAuthenticated: req.session.isAuthenticated,
        username: req.session.account?.username,
    });
});

在 Python 快速入門中，登入連結的程式代碼位於 login.html 範本檔案中。

<ul><li><a href='{{ auth_uri }}'>Sign In</a></li></ul>

當未經驗證的用戶流覽首頁時，indexapp.py 中的路由會將使用者重新導向至login路由。

@app.route("/")
def index():
    if not (app.config["CLIENT_ID"] and app.config["CLIENT_SECRET"]):
        # This check is not strictly necessary.
        # You can remove this check from your production code.
        return render_template('config_error.html')
    if not auth.get_user():
        return redirect(url_for("login"))
    return render_template('index.html', user=auth.get_user(), version=identity.__version__)

路由 login 會找出適當的 auth_uri ，並呈現 login.html 範本。

@app.route("/login")
def login():
    return render_template("login.html", version=identity.__version__, **auth.log_in(
        scopes=app_config.SCOPE, # Have user consent to scopes during log-in
        redirect_uri=url_for("auth_response", _external=True), # Optional. If present, this absolute URL must match your app's redirect_uri registered in Azure Portal
        ))

`SignIn` 控制器的動作

在 ASP.NET 中，選取 Web 應用程式中的 [登入 ] 按鈕會 SignIn 觸發控制器上的 AccountController 動作。在舊版的 ASP.NET Core 範本中 Account ，控制器內嵌於 Web 應用程式。這種情況不再是這種情況，因為控制器現在是 Microsoft.Identity.Web.UI NuGet 套件的一部分。如需詳細資訊，請參閱AccountController.cs。

此控制器也會處理 Azure AD B2C 應用程式。

在 ASP.NET 中，會從 SignIn() 控制器上的方法觸發登入（例如， AccountController.cs#L16-L23）。此方法不是 .NET Framework 的一部分（與 ASP.NET Core 中發生的情況相反）。在提出重新導向 URI 之後，它會傳送 OpenID 登入挑戰。

public void SignIn()
{
    // Send an OpenID Connect sign-in request.
    if (!Request.IsAuthenticated)
    {
        HttpContext.GetOwinContext().Authentication.Challenge(new AuthenticationProperties { RedirectUri = "/" }, OpenIdConnectAuthenticationDefaults.AuthenticationType);
    }
}

在 Java 中，註銷是藉由直接呼叫 Microsoft 身分識別平台 logout 端點並提供post_logout_redirect_uri值來處理。如需詳細資訊，請參閱 AuthPageController.java#L30-L48。

@Controller
public class AuthPageController {

    @Autowired
    AuthHelper authHelper;

    @RequestMapping("/msal4jsample")
    public String homepage(){
        return "index";
    }

    @RequestMapping("/msal4jsample/secure/aad")
    public ModelAndView securePage(HttpServletRequest httpRequest) throws ParseException {
        ModelAndView mav = new ModelAndView("auth_page");

        setAccountInfo(mav, httpRequest);

        return mav;
    }

    // More code omitted for simplicity

當使用者選取觸發/auth/signin路由的 [登入] 連結時，登入控制器會接手以向 Microsoft 身分識別平台驗證使用者。

login(options = {}) {
    return async (req, res, next) => {

        /**
         * MSAL Node library allows you to pass your custom state as state parameter in the Request object.
         * The state parameter can also be used to encode information of the app's state before redirect.
         * You can pass the user's state in the app, such as the page or view they were on, as input to this parameter.
         */
        const state = this.cryptoProvider.base64Encode(
            JSON.stringify({
                successRedirect: options.successRedirect || '/',
            })
        );

        const authCodeUrlRequestParams = {
            state: state,

            /**
             * By default, MSAL Node will add OIDC scopes to the auth code url request. For more information, visit:
             * https://docs.microsoft.com/azure/active-directory/develop/v2-permissions-and-consent#openid-connect-scopes
             */
            scopes: options.scopes || [],
            redirectUri: options.redirectUri,
        };

        const authCodeRequestParams = {
            state: state,

            /**
             * By default, MSAL Node will add OIDC scopes to the auth code request. For more information, visit:
             * https://docs.microsoft.com/azure/active-directory/develop/v2-permissions-and-consent#openid-connect-scopes
             */
            scopes: options.scopes || [],
            redirectUri: options.redirectUri,
        };

        /**
         * If the current msal configuration does not have cloudDiscoveryMetadata or authorityMetadata, we will 
         * make a request to the relevant endpoints to retrieve the metadata. This allows MSAL to avoid making 
         * metadata discovery calls, thereby improving performance of token acquisition process. For more, see:
         * https://github.com/AzureAD/microsoft-authentication-library-for-js/blob/dev/lib/msal-node/docs/performance.md
         */
        if (!this.msalConfig.auth.cloudDiscoveryMetadata || !this.msalConfig.auth.authorityMetadata) {

            const [cloudDiscoveryMetadata, authorityMetadata] = await Promise.all([
                this.getCloudDiscoveryMetadata(this.msalConfig.auth.authority),
                this.getAuthorityMetadata(this.msalConfig.auth.authority)
            ]);

            this.msalConfig.auth.cloudDiscoveryMetadata = JSON.stringify(cloudDiscoveryMetadata);
            this.msalConfig.auth.authorityMetadata = JSON.stringify(authorityMetadata);
        }

        const msalInstance = this.getMsalInstance(this.msalConfig);

        // trigger the first leg of auth code flow
        return this.redirectToAuthCodeUrl(
            authCodeUrlRequestParams,
            authCodeRequestParams,
            msalInstance
        )(req, res, next);
    };
}
redirectToAuthCodeUrl(authCodeUrlRequestParams, authCodeRequestParams, msalInstance) {
    return async (req, res, next) => {
        // Generate PKCE Codes before starting the authorization flow
        const { verifier, challenge } = await this.cryptoProvider.generatePkceCodes();

        // Set generated PKCE codes and method as session vars
        req.session.pkceCodes = {
            challengeMethod: 'S256',
            verifier: verifier,
            challenge: challenge,
        };

        /**
         * By manipulating the request objects below before each request, we can obtain
         * auth artifacts with desired claims. For more information, visit:
         * https://azuread.github.io/microsoft-authentication-library-for-js/ref/modules/_azure_msal_node.html#authorizationurlrequest
         * https://azuread.github.io/microsoft-authentication-library-for-js/ref/modules/_azure_msal_node.html#authorizationcoderequest
         **/
        req.session.authCodeUrlRequest = {
            ...authCodeUrlRequestParams,
            responseMode: msal.ResponseMode.FORM_POST, // recommended for confidential clients
            codeChallenge: req.session.pkceCodes.challenge,
            codeChallengeMethod: req.session.pkceCodes.challengeMethod,
        };

        req.session.authCodeRequest = {
            ...authCodeRequestParams,
            code: '',
        };

        try {
            const authCodeUrlResponse = await msalInstance.getAuthCodeUrl(req.session.authCodeUrlRequest);
            res.redirect(authCodeUrlResponse);
        } catch (error) {
            next(error);
        }
    };
}

/**
 * Retrieves cloud discovery metadata from the /discovery/instance endpoint
 * @returns 
 */
async getCloudDiscoveryMetadata(authority) {
    const endpoint = 'https://login.microsoftonline.com/common/discovery/instance';

    try {
        const response = await axios.get(endpoint, {
            params: {
                'api-version': '1.1',
                'authorization_endpoint': `${authority}/oauth2/v2.0/authorize`
            }
        });

        return await response.data;
    } catch (error) {
        throw error;
    }
}

當使用者選取 [登入] 連結時，系統會將他們帶到 Microsoft 身分識別平台授權端點。

成功的登入會將使用者重新導向至 auth_response 路由，此路由會使用 auth.complete_login完成登入程式，並在出現任何狀況時呈現錯誤，並將現在已驗證的使用者重新導向至首頁。

@app.route(app_config.REDIRECT_PATH)
def auth_response():
    result = auth.complete_log_in(request.args)
    if "error" in result:
        return render_template("auth_error.html", result=result)
    return redirect(url_for("index"))

使用者登入您的應用程式之後，您會想要讓他們註銷。

登出

從 Web 應用程式註銷牽涉到的不僅僅是從 Web 應用程式狀態移除登入帳戶的相關信息。 Web 應用程式也必須將使用者重新導向至 Microsoft 身分識別平台 logout 端點以註銷。

當您的 Web 應用程式將使用者重新導向至 logout 端點時，此端點會從瀏覽器清除使用者的工作階段。如果您的應用程式未移至 logout 端點，使用者將會重新驗證您的應用程式，而不會再次輸入其認證。原因是他們將有有效的單一登錄會話與 Microsoft 身分識別平台。

若要深入瞭解，請參閱 Microsoft 身分識別平台和 OpenID 連線通訊協定檔中的傳送註銷要求一節。

應用程式註冊

在應用程式註冊期間，您會註冊前端通道註銷 URL。在本教學課程中，您已在 https://localhost:44321/signout-oidc [驗證] 頁面上的 [前端通道註銷 URL] 欄位中註冊。如需詳細資訊，請參閱註冊 webApp 應用程式。

註銷按鈕

在 ASP.NET 中，選取 Web 應用程式中的 [註銷 ] 按鈕會 SignOut 觸發控制器上的 AccountController 動作（請參閱下方）

<ul class="navbar-nav">
  @if (User.Identity.IsAuthenticated)
  {
    <li class="nav-item">
        <span class="navbar-text text-dark">Hello @User.Identity.Name!</span>
    </li>
    <li class="nav-item">
        <a class="nav-link text-dark" asp-area="MicrosoftIdentity" asp-controller="Account" asp-action="SignOut">Sign out</a>
    </li>
  }
  else
  {
    <li class="nav-item">
        <a class="nav-link text-dark" asp-area="MicrosoftIdentity" asp-controller="Account" asp-action="SignIn">Sign in</a>
    </li>
  }
</ul>

在 ASP.NET MVC 中，註銷按鈕會在中 Views\Shared\_LoginPartial.cshtml公開。只有在有已驗證的帳戶時，才會顯示它。也就是說，當使用者先前已登入時，就會顯示它。

@if (Request.IsAuthenticated)
{
    <text>
        <ul class="nav navbar-nav navbar-right">
            <li class="navbar-text">
                Hello, @User.Identity.Name!
            </li>
            <li>
                @Html.ActionLink("Sign out", "SignOut", "Account")
            </li>
        </ul>
    </text>
}
else
{
    <ul class="nav navbar-nav navbar-right">
        <li>@Html.ActionLink("Sign in", "SignIn", "Account", routeValues: null, htmlAttributes: new { id = "loginLink" })</li>
    </ul>
}

在我們的 Java 快速入門中，註銷按鈕位於 main/resources/templates/auth_page.html 檔案中。

<!DOCTYPE html>
<html lang="en" xmlns:th="http://www.thymeleaf.org">
<body>

<form action="/msal4jsample/sign_out">
    <input type="submit" value="Sign out">
</form>
...

{{#if isAuthenticated }}
<a href="/auth/signout">Sign out</a>

在 Python 快速入門中，註銷按鈕位於 templates/index.html 檔案中。

<li><a href="/logout">Logout</a></li>

`SignOut` 控制器的動作

在舊版的 ASP.NET Core 範本中 Account ，控制器內嵌於 Web 應用程式。這種情況不再是這種情況，因為控制器現在是 Microsoft.Identity.Web.UI NuGet 套件的一部分。如需詳細資訊，請參閱AccountController.cs。

將 OpenID 重新導向 URI 設定為 /Account/SignedOut ，以便在 Microsoft Entra ID 完成登出時呼叫控制器。
呼叫 Signout()，讓 OpenID 連線中間件連絡 Microsoft 身分識別平台 logout 端點。然後，端點：
- 從瀏覽器清除會話 Cookie。
- 回呼註銷後重新導向 URI。根據預設，註銷后重新導向 URI 會顯示已註銷的檢視頁面 SignedOut.cshtml.cs。此頁面也提供為 Microsoft.Identity.Web 的一部分。

在 ASP.NET 中，會從 SignOut() 控制器上的方法觸發註銷（例如， AccountController.cs#L25-L31）。此方法不是 .NET Framework 的一部分，與 Core ASP.NET 發生的情況相反。這麼做可：

傳送 OpenID 註銷挑戰。
清除快取。
重新導向至想要的頁面。

/// <summary>
/// Send an OpenID Connect sign-out request.
/// </summary>
public void SignOut()
{
 HttpContext.GetOwinContext()
            .Authentication
            .SignOut(CookieAuthenticationDefaults.AuthenticationType);
 Response.Redirect("/");
}

在 Java 中，註銷是藉由直接呼叫 Microsoft 身分識別平台 logout 端點並提供post_logout_redirect_uri值來處理。如需詳細資訊，請參閱 AuthPageController.java#L50-L60。

@RequestMapping("/msal4jsample/sign_out")
    public void signOut(HttpServletRequest httpRequest, HttpServletResponse response) throws IOException {

        httpRequest.getSession().invalidate();

        String endSessionEndpoint = "https://login.microsoftonline.com/common/oauth2/v2.0/logout";

        String redirectUrl = "http://localhost:8080/msal4jsample/";
        response.sendRedirect(endSessionEndpoint + "?post_logout_redirect_uri=" +
                URLEncoder.encode(redirectUrl, "UTF-8"));
    }

當使用者選取 [註銷] 按鈕時，應用程式會觸發/auth/signout路由，這會終結會話，並將瀏覽器重新導向至 Microsoft 身分識別平台註銷端點。

logout(options = {}) {
    return (req, res, next) => {

        /**
         * Construct a logout URI and redirect the user to end the
         * session with Azure AD. For more information, visit:
         * https://docs.microsoft.com/azure/active-directory/develop/v2-protocols-oidc#send-a-sign-out-request
         */
        let logoutUri = `${this.msalConfig.auth.authority}/oauth2/v2.0/`;

        if (options.postLogoutRedirectUri) {
            logoutUri += `logout?post_logout_redirect_uri=${options.postLogoutRedirectUri}`;
        }

        req.session.destroy(() => {
            res.redirect(logoutUri);
        });
    }
}

當使用者選取 [註銷] 時，應用程式會logout觸發路由，將瀏覽器重新導向至 Microsoft 身分識別平台註銷端點。

@app.route("/logout")
def logout():
    return redirect(auth.log_out(url_for("index", _external=True)))

攔截對端點的 `logout` 呼叫

註銷後 URI 可讓應用程式參與全域註銷。

ASP.NET Core OpenID 連線中間件可讓您的應用程式藉由提供名為的 OpenID 連線事件來攔截對 Microsoft 身分識別平台 logout 端點的OnRedirectToIdentityProviderForSignOut呼叫。這是由 Microsoft.Identity.Web 自動處理（在 Web 應用程式呼叫 Web API 的情況下清除帳戶）

在 ASP.NET 中，您會委派給中間件以執行註銷，清除會話 Cookie：

public class AccountController : Controller
{
 ...
 public void EndSession()
 {
  Request.GetOwinContext().Authentication.SignOut();
  Request.GetOwinContext().Authentication.SignOut(Microsoft.AspNet.Identity.DefaultAuthenticationTypes.ApplicationCookie);
  this.HttpContext.GetOwinContext().Authentication.SignOut(CookieAuthenticationDefaults.AuthenticationType);
 }
}

通訊協定

如果您想要深入了解註銷，請閱讀 OpenID 連線提供的通訊協定檔。

下一步

在下列多部分教學課程系列中建置可登入使用者的 ASP.NET Core Web 應用程式，以深入瞭解
探索 Microsoft 身分識別平台 Web 應用程式範例

登入使用者的 Web 應用程式：登入和註銷

登入

登入按鈕

SignIn 控制器的動作

登出

應用程式註冊

註銷按鈕

SignOut 控制器的動作

攔截對端點的 logout 呼叫

通訊協定

下一步

更多資源

`SignIn` 控制器的動作

`SignOut` 控制器的動作

攔截對端點的 `logout` 呼叫