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

發行項
07/08/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>

此範本透過應用程式的主要 (索引) 路由提供：

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 範本中，Web 應用程式會內嵌 Account 控制器。因為控制器現在是 Microsoft.Identity.Web.UI NuGet 套件的一部分，所以情況不再是如此。如需詳細資訊，請參閱 AccountController.cs。

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

在 ASP.NET 中，會從控制器 (例如 AccountController.cs#L16-L23) 上的 SignIn() 方法觸發登入。這個方法不是 .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 Connect 通訊協定文件中的＜傳送登出要求＞一節。

應用程式註冊

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

登出按鈕

在 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 範本中，Web 應用程式會內嵌 Account 控制器。因為控制器現在是 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() 方法觸發登出。這個方法不是 .NET Framework 的一部分，與 ASP.NET Core 中的情況相反。這麼做可：

傳送 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` 端點的呼叫