Создание веб-приложения, которое реализует вход/выход пользователей - Microsoft identity platform

Статья
10/24/2023

Узнайте, как добавить вход в код для веб-приложения, которое реализует вход пользователей. Затем узнайте, как разрешить выход.

Вход состоит из двух частей:

Кнопка входа на HTML-странице
Действие входа в коде программной части контроллера

В ASP.NET Core для приложений платформы Microsoft Identity кнопка Вход реализуется в Views\Shared\_LoginPartial.cshtml (для приложения MVC) или Pages\Shared\_LoginPartial.cshtm (для приложения Razor). Он отображается только в том случае, если пользователь не прошел проверку подлинности. То есть он отображается, когда пользователь еще не вошел в приложение или выполнил выход из него. Напротив, кнопка Выйти отображается, когда пользователь уже вошел в систему. Обратите внимание, что контроллер учетной записи определен в пакете NuGet Microsoft.Identity.Web.UI в области с именем 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>

Когда пользователь, не прошедший проверку подлинности, посещает домашнюю страницу, index маршрут в app.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 при нажатии кнопки Входа в веб-приложении будет инициировано действиеSignIn в контроллере AccountController. В предыдущих версиях шаблонов Account ASP.NET Core контроллер был внедрен в веб-приложение. Теперь контроллер входит в пакет NuGet Microsoft. Identity.Web.UI. Дополнительные сведения см. в разделе AccountController.cs.

Этот контроллер также обрабатывает приложения Azure AD B2C.

В ASP.NET вход активируется из SignIn() метода на контроллере (например, AccountController.cs#L16-L23). Этот метод не является частью платформа .NET Framework (вопреки тому, что происходит в ASP.NET Core). При предложении перенаправления URI он отправляет запрос на вход в OpenID Connect.

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

В Java выход осуществляется путем прямого вызова конечной точки logout платформы Microsoft Identity и предоставления значения 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, контроллер входа берет на себя проверку подлинности пользователя на платформе удостоверений Майкрософт.

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;
    }
}

Когда пользователь выбирает ссылку для входа, он будет доставлен в конечную точку авторизации платформа удостоверений Майкрософт.

Успешный вход перенаправляет пользователя на 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"))

После входа пользователя в приложение необходимо включить этот метод для выхода из него.

Функция выхода

Выход из веб-приложения требует больше, чем удаление сведений об аутентифицированной учетной записи из состояния веб-приложения. Веб-приложение должно также перенаправить пользователя на конечную точку logout платформы удостоверений Майкрософт для выхода.

Когда веб-приложение перенаправляет пользователя на конечную точкуlogout, эта конечная точка удаляет сеанс пользователя из браузера. Если приложение не перенаправило на конечную точку logout, пользователь сможет повторно войти в приложение, не вводя свои учетные данные. Причина заключается в том, что у них будет один действительный сеанс входа с платформой Microsoft Identity.

Дополнительные сведения см. в разделе Отправка запроса на выход в документации платформа Microsoft Identity и протокол OpenID Connect .

Регистрация приложения

Во время регистрации приложения вы регистрируете URL-адрес выхода для внешнего канала. В нашем руководстве вы зарегистрировались https://localhost:44321/signout-oidc в поле URL-адрес внешнего канала для выхода на странице Проверка подлинности . Дополнительные сведения см. в разделе Регистрация приложения webApp.

Кнопка выхода

В ASP.NET при нажатии кнопки Выход в веб-приложении будет инициировано действие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` контроллера

В предыдущих версиях шаблонов Account ASP.NET Core контроллер был внедрен в веб-приложение. Теперь контроллер входит в пакет NuGet Microsoft. Identity.Web.UI. Дополнительные сведения см. в разделе AccountController.cs.

Задает URI /Account/SignedOut перенаправления OpenID таким образом, чтобы контроллер был вызван обратно, когда идентификатор Microsoft Entra завершил выход.
Вызывает Signout(), который позволяет промежуточному ПО OpenID Connect обращаться к конечной точке logout платформы идентификации Майкрософт. Затем конечная точка:
- Удаляет файл cookie сеанса из браузера.
- Вызывает URI перенаправления после выхода. По умолчанию URI перенаправления после выхода отображает страницу после выхода SignedOut.cshtml.cs. Эта страница также предоставляется как часть Microsoft.Identity.Web.

В ASP.NET выход запускается из метода SignOut() на контроллере (например, AccountController.cs#L25-L31). Этот метод не является частью платформа .NET Framework, вопреки тому, что происходит в ASP.NET Core. Оно делает следующее.

Отправляет запрос на выход из OpenID Connect.
Очищает кэш.
Выполняет перенаправление на страницу, которую он хочет.

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

@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, который уничтожает сеанс и перенаправляет браузер в конечную точку выхода из системы на платформе удостоверений Майкрософт.

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 маршрут, который перенаправляет браузер в конечную точку выхода платформа удостоверений Майкрософт.

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

Перехват вызова конечной точки `logout`.

URI-адрес страницы после выхода позволяет приложениям участвовать в глобальном выходе.

ПО промежуточного слоя ASP.NET Core OpenID Connect позволяет приложению перехватывать вызовы конечной точки платформы идентификации Майкрософт, logout предоставляя событие OpenID Connect с именем OnRedirectToIdentityProviderForSignOut . Это автоматически обрабатывается службой Microsoft.Identity.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, которое входит в систему пользователей в следующей серии учебников с несколькими частью
Изучение примеров веб-приложения платформа удостоверений Майкрософт

Веб-приложение, которое реализует вход пользователей: вход и выход

Вход

Кнопка "Войти"

Действие SignIn контроллера