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

Статья
05/02/2022
Чтение занимает 9 мин

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

Библиотеки Майкрософт, поддерживающие веб-приложения

Для защиты веб-приложения (и веб-API) используются следующие библиотеки Майкрософт:

Язык или платформа	Проект на сайте GitHub	Пакет	Получение запущен	Выполнение входа пользователей	Доступ к веб-API	Общедоступная версия (GA) или Общедоступная предварительная версия¹
.NET	MSAL.NET	Microsoft.Identity.Client	—			GA
.NET	Microsoft.IdentityModel	Microsoft.IdentityModel	—	²	²	GA
ASP.NET Core	ASP.NET Core	Microsoft.AspNetCore.Authentication	Краткое руководство			GA
ASP.NET Core	Microsoft.Identity.Web	Microsoft.Identity.Web	Краткое руководство			GA
Java	MSAL4J	msal4j	Краткое руководство			GA
Node.js	MSAL Node	msal-node	Краткое руководство			GA
Python	MSAL Python	msal	Краткое руководство			GA

¹Дополнительные условия использования предварительных версий Microsoft Azure применяются к библиотекам в общедоступной предварительной версии.

² Библиотека Microsoft.IdentityModel только проверяет маркеры и не может запрашивать идентификаторы или маркеры доступа.

Выберите вкладку, соответствующую интересующей вас платформе:

Фрагменты кода в этой и следующей статье извлекаются из пошагового руководства по веб-приложению ASP.NET Core, глава 1.

В этом руководстве представлены подробные сведения о реализации.

Файлы конфигурации.

Веб-приложения, реализующие вход пользователей с помощью платформы Microsoft Identity, настраиваются с помощью файлов конфигурации. Ниже приведены значения, которые необходимо указать в конфигурации.

Облачный экземпляр (Instance), если приложение должно, к примеру, выполняться в национальных облаках.
Аудитория в идентификаторе клиента (TenantId).
Идентификатор клиента (ClientId) для приложения, соответствующий скопированному с портала Microsoft Azure.

Кроме того, могут отображаться ссылки на Authority. Значение Authority представляет собой объединение значений Instance и TenantId.

В ASP.NET Core эти параметры находятся в файле appsettings.json в разделе "AzureAd".

{
  "AzureAd": {
    // Azure cloud instance among:
    // - "https://login.microsoftonline.com/" for Azure public cloud
    // - "https://login.microsoftonline.us/" for Azure US government
    // - "https://login.microsoftonline.de/" for Azure AD Germany
    // - "https://login.partner.microsoftonline.cn/common" for Azure AD China operated by 21Vianet
    "Instance": "https://login.microsoftonline.com/",

    // Azure AD audience among:
    // - "TenantId" as a GUID obtained from the Azure portal to sign in users in your organization
    // - "organizations" to sign in users in any work or school account
    // - "common" to sign in users with any work or school account or Microsoft personal account
    // - "consumers" to sign in users with a Microsoft personal account only
    "TenantId": "[Enter the tenantId here]",

    // Client ID (application ID) obtained from the Azure portal
    "ClientId": "[Enter the Client Id]",
    "CallbackPath": "/signin-oidc",
    "SignedOutCallbackPath": "/signout-oidc"
  }
}

В ASP.NET Core другой файл (properties\launchSettings.json) contains the URL (applicationUrl) and the TLS/SSL port (sslPort) для приложения и разных профилей.

{
  "iisSettings": {
    "windowsAuthentication": false,
    "anonymousAuthentication": true,
    "iisExpress": {
      "applicationUrl": "http://localhost:3110/",
      "sslPort": 44321
    }
  },
  "profiles": {
    "IIS Express": {
      "commandName": "IISExpress",
      "launchBrowser": true,
      "environmentVariables": {
        "ASPNETCORE_ENVIRONMENT": "Development"
      }
    },
    "webApp": {
      "commandName": "Project",
      "launchBrowser": true,
      "environmentVariables": {
        "ASPNETCORE_ENVIRONMENT": "Development"
      },
      "applicationUrl": "http://localhost:3110/"
    }
  }
}

На портале Azure URI перенаправления, регистрируемые на странице Аутентификация приложения, должны соответствовать этим URL-адресам. Для двух предыдущих файлов конфигурации это будет https://localhost:44321/signin-oidc. Причина в том, что этот applicationUrl имеет значение http://localhost:3110, но указан sslPort (44321). CallbackPath имеет значение /signin-oidc, как определено в appsettings.json.

Таким же образом для URI выхода будет задано значение https://localhost:44321/signout-oidc.

Примечание

SignedOutCallbackPath должен вести к порталу или к приложению, чтобы избежать конфликта во время обработки события.

В ASP.NET приложение настраивается с помощью файла Web.config, строки 12–15.

<?xml version="1.0" encoding="utf-8"?>
<!--
  For more information on how to configure your ASP.NET application, visit
  https://go.microsoft.com/fwlink/?LinkId=301880
  -->
<configuration>
  <appSettings>
    <add key="webpages:Version" value="3.0.0.0" />
    <add key="webpages:Enabled" value="false" />
    <add key="ClientValidationEnabled" value="true" />
    <add key="UnobtrusiveJavaScriptEnabled" value="true" />
    <add key="ida:ClientId" value="[Enter your client ID, as obtained from the app registration portal]" />
    <add key="ida:ClientSecret" value="[Enter your client secret, as obtained from the app registration portal]" />
    <add key="ida:AADInstance" value="https://login.microsoftonline.com/{0}{1}" />
    <add key="ida:RedirectUri" value="https://localhost:44326/" />
    <add key="vs:EnableBrowserLink" value="false" />
  </appSettings>

На портале Microsoft Azure URI ответа, регистрируемые на странице Аутентификация приложения, должны соответствовать этим URL-адресам. То есть, они должны иметь значение https://localhost:44326/.

Для Java конфигурация размещается в файле application.properties, расположенном в папке src/main/resources.

aad.clientId=Enter_the_Application_Id_here
aad.authority=https://login.microsoftonline.com/Enter_the_Tenant_Info_Here/
aad.secretKey=Enter_the_Client_Secret_Here
aad.redirectUriSignin=http://localhost:8080/msal4jsample/secure/aad
aad.redirectUriGraph=http://localhost:8080/msal4jsample/graph/me

На портале Microsoft Azure URI ответа, регистрируемые на странице Аутентификация для приложения, должны совпадать с экземплярами redirectUri, которые определяет приложение. То есть, они должны иметь значение http://localhost:8080/msal4jsample/secure/aad и http://localhost:8080/msal4jsample/graph/me.

Здесь параметры конфигурации находятся в index.js


const REDIRECT_URI = "http://localhost:3000/redirect";

const config = {
    auth: {
        clientId: "Enter_the_Application_Id_Here",
        authority: "https://login.microsoftonline.com/Enter_the_Tenant_Info_Here/",
        clientSecret: "Enter_the_Client_Secret_Here"
    },
    system: {
        loggerOptions: {
            loggerCallback(loglevel, message, containsPii) {
                console.log(message);
            },
            piiLoggingEnabled: false,
            logLevel: msal.LogLevel.Verbose,
        }
    }
};

На портале Microsoft Azure URI ответов, регистрируемые на странице "Аутентификация" для приложения, должны соответствовать экземплярам redirectUri, определяемым приложением (http://localhost:3000/redirect).

Примечание

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

Ниже приведен файл конфигурации Python в app_config.py:

CLIENT_SECRET = "Enter_the_Client_Secret_Here"
AUTHORITY = "https://login.microsoftonline.com/common"
CLIENT_ID = "Enter_the_Application_Id_here"
ENDPOINT = 'https://graph.microsoft.com/v1.0/users'
SCOPE = ["User.ReadBasic.All"]
SESSION_TYPE = "filesystem"  # So the token cache will be stored in a server-side session

Примечание

CLIENT_SECRET = os.getenv("CLIENT_SECRET")
if not CLIENT_SECRET:
    raise ValueError("Need to define CLIENT_SECRET environment variable")

Код инициализации

Код инициализации может меняться в зависимости от платформы. Для ASP.NET Core и ASP.NET вход пользователей в систему делегируется программному обеспечению промежуточного слоя OpenID Connect. Шаблон ASP.NET или ASP.NET Core создает веб-приложения для конечной точки Azure Active Directory (Azure AD) версии 1.0. Для адаптации к платформе Microsoft Identity требуется определенная конфигурация. В случае Java обработку выполняет служба Spring совместно с приложением.

В веб-приложениях (и веб-API) ASP.NET Core приложение защищено, поскольку у вас есть атрибут [Authorize] на контроллерах или в действиях контроллера. Этот атрибут проверяет, прошел ли пользователь проверку подлинности. Код, инициализирующий приложение, находится в файле Startup.cs.

Чтобы добавить проверку подлинности на платформе Microsoft Identity (прежнее название — Azure AD версии 2.0), необходимо добавить следующий код. Комментарии в коде должны быть описательными.

Примечание

Если надо начать непосредственно с новых шаблонов ASP.NET Core для платформы Microsoft Identity, использующих Microsoft.Identity.Web, можно загрузить предварительную версию пакета NuGet, содержащую шаблоны проектов для .NET Core 3.1 и .NET 5.0. После установки можно напрямую создать экземпляр веб-приложений ASP.NET Core (MVC или Blazor). Дополнительные сведения см. в статье Шаблоны проектов веб-приложений Microsoft.Identity.Web. Это простейший способ, поскольку все действия, описанные ниже, будут выполнены за вас.

Если вы предпочитаете запускать проект с текущим веб-проектом ASP.NET Core по умолчанию в Visual Studio или с помощью dotnet new mvc --auth SingleOrg или dotnet new webapp --auth SingleOrg, будет отображаться код, подобный следующему:

 services.AddAuthentication(AzureADDefaults.AuthenticationScheme)
         .AddAzureAD(options => Configuration.Bind("AzureAd", options));

В этом коде используется устаревший пакет NuGet Microsoft.AspNetCore.Authentication.AzureAD.UI, который используется для создания приложения Azure AD версии 1.0. В этой статье приведены объяснения по созданию приложения платформы Microsoft Identity (Azure AD 2.0), заменяющего этот код.

Добавьте в проект пакеты NuGet Microsoft.Identity.Web и Microsoft.Identity.Web.UI. Удалите пакет NuGet Microsoft.AspNetCore.Authentication.AzureAD.UI, если он имеется.

Обновите код в ConfigureServices, чтобы он использовал методы AddMicrosoftIdentityWebAppAuthentication и AddMicrosoftIdentityUI.

public class Startup
{
 ...
 // This method gets called by the runtime. Use this method to add services to the container.
 public void ConfigureServices(IServiceCollection services)
 {
  services.AddMicrosoftIdentityWebAppAuthentication(Configuration, "AzureAd");

  services.AddRazorPages().AddMvcOptions(options =>
  {
   var policy = new AuthorizationPolicyBuilder()
                 .RequireAuthenticatedUser()
                 .Build();
   options.Filters.Add(new AuthorizeFilter(policy));
  }).AddMicrosoftIdentityUI();

В методе Configure в Startup.cs включите проверку подлинности с помощью обращения к app.UseAuthentication();.

// This method gets called by the runtime. Use this method to configure the HTTP request pipeline.
public void Configure(IApplicationBuilder app, IWebHostEnvironment env)
{
 // more code here
 app.UseAuthentication();
 app.UseAuthorization();
 // more code here
}

В приведенном выше коде:

AddMicrosoftIdentityWebAppAuthenticationМетод расширения определен в Microsoft.Identity.Web. Этот код выполняет нижеуказанные действия.
- Добавляет службу аутентификации.
- Настраивает параметры для чтения файла конфигурации (здесь из раздела "AzureAD").
- Настраивает параметры OpenID Connect, чтобы центр сертификации был платформой Microsoft Identity.
- Проверяет издателя маркера.
- Гарантирует, что утверждения, соответствующие имени, сопоставлены с утверждением preferred_username маркере идентификации.
В дополнение к объекту конфигурации можно указать имя раздела конфигурации при вызове AddMicrosoftIdentityWebAppAuthentication. По умолчанию это AzureAd.
AddMicrosoftIdentityWebAppAuthentication имеет другие параметры для расширенных сценариев. Например, трассировка событий программного обеспечения промежуточного слоя OpenID Connect позволяет устранить неполадки в веб-приложении, если проверка подлинности не работает. При установке необязательного параметра subscribeToOpenIdConnectMiddlewareDiagnosticsEvents в true будет показано, как обрабатывается информация набором программного обеспечения промежуточного слоя ASP.NET Core по мере перехода от HTTP-ответа к удостоверению пользователя в HttpContext.User.
Метод расширения AddMicrosoftIdentityUI определен в Microsoft.Identity.Web.UI. Он предоставляет контроллер по умолчанию для управления входом и выходом.

Дополнительные сведения о том, как Microsoft.Identity.Web обеспечивает создание приложений, см. под адресу https://aka.ms/ms-id-web/webapp

Код, связанный с проверкой подлинности в веб-приложении ASP.NET и веб-API, находится в файле App_Start/Startup.Auth.cs.

 public void ConfigureAuth(IAppBuilder app)
 {
  app.SetDefaultSignInAsAuthenticationType(CookieAuthenticationDefaults.AuthenticationType);

  app.UseCookieAuthentication(new CookieAuthenticationOptions());

  app.UseOpenIdConnectAuthentication(
    new OpenIdConnectAuthenticationOptions
    {
     // Authority` represents the identity platform endpoint - https://login.microsoftonline.com/common/v2.0.
     // `Scope` describes the initial permissions that your app will need.
     //  See https://azure.microsoft.com/documentation/articles/active-directory-v2-scopes/.
     ClientId = clientId,
     Authority = String.Format(CultureInfo.InvariantCulture, aadInstance, "common", "/v2.0"),
     RedirectUri = redirectUri,
     Scope = "openid profile",
     PostLogoutRedirectUri = redirectUri,
    });
 }

В примере Java используется платформа Spring. Приложение защищено, поскольку вы реализуете фильтр, который перехватывает каждый HTTP-ответ. В кратком руководстве по веб-приложениям Java этот фильтр имеет значение AuthFilter в src/main/java/com/microsoft/azure/msalwebsample/AuthFilter.java.

Фильтр обрабатывает поток кода авторизации OAuth 2.0 и проверяет, прошел ли пользователь проверку подлинности (метод isAuthenticated()). Если пользователь не прошел проверку подлинности, он вычисляет URL-адрес конечных точек авторизации Microsoft Azure Active Directory и перенаправляет браузер на этот URI.

Когда получен ответ с кодом авторизации, он получает маркер с помощью MSAL Java. Когда он наконец получает маркер из конечной точки маркера (в URI перенаправления), это означает, что пользователь вошел в систему.

Дополнительные сведения см. в описании метода doFilter() в AuthFilter.java.

Примечание

Код для doFilter() написан немного иначе, однако последовательность описана.

Дополнительные сведения о потоке кода авторизации, который запускается этим методом, см. в статье Платформа Microsoft Identity и поток кода авторизации OAuth 2.0.

const msal = require('@azure/msal-node');

// Create msal application object
const cca = new msal.ConfidentialClientApplication(config);

В примере Python используется Flask. Инициализация Flask и MSAL Python выполняется в app.py#L1-L28.

import uuid
import requests
from flask import Flask, render_template, session, request, redirect, url_for
from flask_session import Session  # https://pythonhosted.org/Flask-Session
import msal
import app_config

app = Flask(__name__)
app.config.from_object(app_config)
Session(app)

Дальнейшие действия

В следующей статье вы узнаете, как активировать вход и выход.

Перейдите к следующей статье в этом сценарии, Вход и выход.

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

Были ли сведения на этой странице полезными?

Библиотеки Майкрософт, поддерживающие веб-приложения

Файлы конфигурации.

Код инициализации

Дальнейшие действия