编写可使用户登录/注销的 Web 应用 - Microsoft identity platform

项目
02/21/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.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 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.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 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 应用示例

通过

注销

应用程序注册

注销按钮

控制器的 `SignOut` 操作

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

协议

后续步骤

反馈

其他资源

通过

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

登录

登录按钮

控制器的 SignIn 操作

注销

应用程序注册

注销按钮

控制器的 SignOut 操作

截获对 logout 终结点的调用

协议

后续步骤

反馈

其他资源

控制器的 `SignIn` 操作

控制器的 `SignOut` 操作

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