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

Статья
07/19/2024

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

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

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

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

⁽¹⁾ Условия универсального лицензионного соглашения для веб-служб применяются к библиотекам в общедоступной предварительной версии.

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

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

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

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

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

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

Облачный экземпляр, если вы хотите, чтобы ваше приложение выполнялось в национальных облаках, например. К разным параметрам относятся;
- https://login.microsoftonline.com/ для общедоступного облака Azure
- https://login.microsoftonline.us/ для государственных организаций США
- https://login.microsoftonline.de/ для Microsoft Entra Germany
- https://login.partner.microsoftonline.cn/common для Microsoft Entra China, управляемый 21Vianet
Аудитория в идентификаторе клиента. Параметры зависят от того, является ли ваше приложение одним клиентом или мультитенантным.
- GUID клиента, полученный из портал Azure для входа пользователей в организации. Вы также можете использовать доменное имя.
- organizations вход пользователей в любой рабочей или учебной учетной записи
- commonвход пользователей с помощью рабочей или учебной учетной записи или Microsoft личная учетная запись
- consumersвход пользователей только с помощью личная учетная запись Майкрософт
Идентификатор клиента приложения, скопированный из портал Azure

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

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

{
  "AzureAd": {
    "Instance": "https://login.microsoftonline.com/",
    "TenantId": "[Enter the tenantId here]",

    // Client ID (application ID) obtained from the Azure portal
    "ClientId": "[Enter the Client Id here]",
    "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 приложение настраивается с помощью файла appsettings.json строк 12–15.

{
  "AzureAd": {
    "Instance": "https://login.microsoftonline.com/",
    "TenantId": "[Enter the tenantId here]",
    "ClientId": "[Enter the Client Id here]",
  }
}

На портале 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.

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

CLOUD_INSTANCE="Enter_the_Cloud_Instance_Id_Here" # cloud instance string should end with a trailing slash
TENANT_ID="Enter_the_Tenant_Info_Here"
CLIENT_ID="Enter_the_Application_Id_Here"
CLIENT_SECRET="Enter_the_Client_Secret_Here"

REDIRECT_URI="http://localhost:3000/auth/redirect"
POST_LOGOUT_REDIRECT_URI="http://localhost:3000"

GRAPH_API_ENDPOINT="Enter_the_Graph_Endpoint_Here" # graph api endpoint string should end with a trailing slash

EXPRESS_SESSION_SECRET="Enter_the_Express_Session_Secret_Here"

Эти параметры используются для создания объекта конфигурации в файле authConfig.js, который в конечном итоге будет использоваться для инициализации Узла MSAL:

/*
 * Copyright (c) Microsoft Corporation. All rights reserved.
 * Licensed under the MIT License.
 */

require('dotenv').config({ path: '.env.dev' });

/**
 * Configuration object to be passed to MSAL instance on creation.
 * For a full list of MSAL Node configuration parameters, visit:
 * https://github.com/AzureAD/microsoft-authentication-library-for-js/blob/dev/lib/msal-node/docs/configuration.md
 */
const msalConfig = {
    auth: {
        clientId: process.env.CLIENT_ID, // 'Application (client) ID' of app registration in Azure portal - this value is a GUID
        authority: process.env.CLOUD_INSTANCE + process.env.TENANT_ID, // Full directory URL, in the form of https://login.microsoftonline.com/<tenant>
        clientSecret: process.env.CLIENT_SECRET // Client secret generated from the app registration in Azure portal
    },
    system: {
        loggerOptions: {
            loggerCallback(loglevel, message, containsPii) {
                console.log(message);
            },
            piiLoggingEnabled: false,
            logLevel: 3,
        }
    }
}

const REDIRECT_URI = process.env.REDIRECT_URI;
const POST_LOGOUT_REDIRECT_URI = process.env.POST_LOGOUT_REDIRECT_URI;
const GRAPH_ME_ENDPOINT = process.env.GRAPH_API_ENDPOINT + "v1.0/me";

module.exports = {
    msalConfig,
    REDIRECT_URI,
    POST_LOGOUT_REDIRECT_URI,
    GRAPH_ME_ENDPOINT
};

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

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

Параметры конфигурации задаются в .env в качестве переменных среды:

# Note: If you are using Azure App Service, go to your app's Configuration,
# and then set the following values into your app's "Application settings".

CLIENT_ID=<client id>
CLIENT_SECRET=<client secret>

# Expects a full authority URL such as "https://login.microsoftonline.com/TENANT_GUID"
# or "https://login.microsoftonline.com/contoso.onmicrosoft.com".
# Alternatively, leave it undefined if you are building a multi-tenant app in world-wide cloud
#AUTHORITY=<authority url>

Эти переменные среды ссылаются на app_config.py:

import os

# Application (client) ID of app registration
CLIENT_ID = os.getenv("CLIENT_ID")
# Application's generated client secret: never check this into source control!
CLIENT_SECRET = os.getenv("CLIENT_SECRET")

# You can configure your authority via environment variable
# Defaults to a multi-tenant app in world-wide cloud
AUTHORITY = os.getenv("AUTHORITY", "https://login.microsoftonline.com/common")

REDIRECT_PATH = "/getAToken"  # Used for forming an absolute URL to your redirect URI.
# The absolute URL must match the redirect URI you set
# in the app's registration in the Azure portal.

# You can find more Microsoft Graph API endpoints from Graph Explorer
# https://developer.microsoft.com/en-us/graph/graph-explorer
ENDPOINT = 'https://graph.microsoft.com/v1.0/users'  # This resource requires no admin consent

# You can find the proper permission names from this document
# https://docs.microsoft.com/en-us/graph/permissions-reference
SCOPE = ["User.ReadBasic.All"]

# Tells the Flask-session extension to store sessions in the filesystem
SESSION_TYPE = "filesystem"
# Using the file system will not work in most production systems,
# it's better to use a database-backed session store instead.

Env-файл никогда не должен быть проверен в системе управления версиями, так как он содержит секреты. В примере краткого руководства содержится файл .gitignore , который предотвращает проверку env-файла .

# Environments
.env

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

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

В веб-приложениях (и веб-API) ASP.NET Core приложение защищено, поскольку у вас есть атрибут Authorize на контроллерах или в действиях контроллера. Этот атрибут проверяет, прошел ли пользователь проверку подлинности. До выпуска .NET 6 инициализация кода была в файле Startup.cs . В новых проектах ASP.NET Core с .NET 6 файла Startup.cs больше нет. Вместо него используется файл Program.cs. Остальная часть этого учебника относится к .NET 5 или более ранней версии.

Примечание.

Если вы хотите начать непосредственно с новых шаблонов ASP.NET Core для платформа удостоверений Майкрософт, использующих Microsoft.Identity.Web, можно скачать предварительный просмотр пакета NuGet, содержащего шаблоны проектов для .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 Active Directory версии 1.0. В этой статье объясняется, как создать приложение платформа удостоверений Майкрософт версии 2.0, которое заменяет этот код.

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

Обновите код в ConfigureServices, чтобы он использовал методы AddMicrosoftIdentityWebApp и 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.AddAuthentication(OpenIdConnectDefaults.AuthenticationScheme)
         .AddMicrosoftIdentityWebApp(Configuration, "AzureAd");

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

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

// 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();

 app.MapRazorPages();
 app.MapControllers();
 // more code here
}

В этом коде:

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

Дополнительные сведения о том, как создавать веб-приложения с помощью Microsoft.Identity.Web, см. в разделе Веб-приложения в microsoft-identity-web.

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

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

  app.UseCookieAuthentication(new CookieAuthenticationOptions());

  OwinTokenAcquirerFactory factory = TokenAcquirerFactory.GetDefaultInstance<OwinTokenAcquirerFactory>();
  factory.Build();
  app.AddMicrosoftIdentityWebApi(factory);
 }

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

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

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

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

Примечание.

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

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

В примере узла используется платформа Express. MSAL инициализируется в обработчике маршрутов проверки подлинности:

var express = require('express');

const authProvider = require('../auth/AuthProvider');
const { REDIRECT_URI, POST_LOGOUT_REDIRECT_URI } = require('../authConfig');

const router = express.Router();

router.get('/signin', authProvider.login({
    scopes: [],
    redirectUri: REDIRECT_URI,
    successRedirect: '/'

Пример Python построен с помощью платформы Flask, хотя и другие платформы, такие как Django, также могут использоваться. Приложение Flask инициализировано с конфигурацией приложения в верхней части app.py:

import identity
import identity.web
import requests
from flask import Flask, redirect, render_template, request, session, url_for
from flask_session import Session

import app_config

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

Затем код создает auth объект с помощью пакета удостоверений.

auth = identity.web.Auth(
    session=session,
    authority=app.config["AUTHORITY"],
    client_id=app.config["CLIENT_ID"],
    client_credential=app.config["CLIENT_SECRET"],
)

Следующий шаг

Войдите и выйдите.

Поделиться через

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

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

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

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

Следующий шаг

Обратная связь

Дополнительные ресурсы