编写可使用户登录/注销的 Web 应用

项目
03/08/2024

了解如何在可将用户登录的 Web 应用的代码中添加登录。然后了解如何让用户注销。

登录由两个部分组成：

HTML 页中的登录按钮
控制器 code-behind 中的登录操作

在 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>

此模板通过应用的主（索引）路径提供：

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>

当未经身份验证的用户访问主页时，app.py 中的 index 路由会将用户重定向到 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 应用中选择“登录”按钮会触发 AccountController 控制器上的 SignIn 操作。在以前的 ASP.NET Core 模板版本中，Account 控制器嵌入在 Web 应用中。现在不再是这样，因为该控制器现在是“Microsoft.Identity.Web.UI”NuGet 包的一部分。有关详细信息，请参阅 AccountController.cs。

此控制器还处理 Azure AD B2C 应用程序。

在 ASP.NET 中，登录是从控制器（例如 AccountController.cs#L16-L23）中的 SignIn() 方法触发的。与 ASP.NET Core 中的情况相反，此方法不是 .NET Framework 的一部分。它在提议重定向 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.partner.microsoftonline.cn/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 Connect 协议文档中的发送注销请求部分。

应用程序注册

在应用程序注册期间，需要注册一个前向通道注销 URL。在本教程中，你已在“身份验证”页面上的“前向通道注销 URL”字段中注册了 https://localhost:44321/signout-oidc 。有关详细信息，请参阅注册 webApp 应用。

注销按钮

在 ASP.NET 的 Web 应用中选择“注销”按钮会触发 AccountController 控制器上的 SignOut 操作（见下）

<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 Connect 中间件联系 Microsoft 标识平台 logout 终结点。然后，终结点将会：
- 从浏览器中清除会话 Cookie。
- 回调注销后重定向 URI。默认情况下，注销后重定向 URI 会显示已注销视图页面 SignedOut.cshtml.cs。该页面也作为 Microsoft.Identity.Web 的一部分提供。

在 ASP.NET 中，注销是从控制器（例如 AccountController.cs#L25-L31）中的 SignOut() 方法触发的。与 ASP.NET Core 中的情况相反，此方法不是 .NET Framework 的一部分。该方法：

发送 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.partner.microsoftonline.cn/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 Connect 中间件提供名为 OnRedirectToIdentityProviderForSignOut 的 OpenID Connect 事件，可让应用截获对 Microsoft 标识平台 logout 终结点的调用。这由 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 Connect 提供的协议文档。

后续步骤

通过在以下多部分教程系列中生成可用户登录的 ASP.NET Core Web 应用来了解详细信息
浏览 Microsoft 标识平台 Web 应用示例

用于登录用户的 Web 应用：登录和注销

登录

登录按钮

控制器的 SignIn 操作

注销

应用程序注册

注销按钮

控制器的 SignOut 操作

截获对 logout 终结点的调用

协议

后续步骤

其他资源

控制器的 `SignIn` 操作

控制器的 `SignOut` 操作

截获对 `logout` 终结点的调用