Aplikacja internetowa, która loguje użytkowników: konfiguracja kodu

Artykuł
04/04/2025

Dotyczy: Dzierżawcy siły roboczej Biały okrąg z szarym symbolem X. dzierżawcy zewnętrzni ( White circle with a gray X symbol. dowiedz się więcej)

W tym artykule opisano sposób konfigurowania kodu dla aplikacji internetowej, która loguje użytkowników.

Biblioteki firmy Microsoft obsługujące aplikacje internetowe

Następujące biblioteki firmy Microsoft są używane do ochrony aplikacji internetowej (i internetowego interfejsu API):

Język/struktura	Projekt dotyczący GitHub	Pakiet	Uzyskiwanie rozpoczął	Logowanie użytkowników	Dostęp do interfejsów API sieci Web	Ogólnie dostępne (ogólna dostępność) lub Publiczna wersja zapoznawcza¹
.NET	MSAL.NET	Microsoft.Identity.Client	—			Ogólna dostępność
.NET	Microsoft.IdentityModel	Microsoft.IdentityModel	—	²	²	Ogólna dostępność
ASP.NET Core	Microsoft.Identity.Web	Microsoft.Identity.Web	Szybki start			Ogólna dostępność
Java	MSAL4J	msal4j	Szybki start			Ogólna dostępność
Wiosna	spring-cloud-azure-starter-active-directory	spring-cloud-azure-starter-active-directory	Samouczek			Ogólna dostępność
Node.js	MSAL Node	msal-node	Szybki start			Ogólna dostępność
Python	MSAL Python	msal	—			Ogólna dostępność
Python	tożsamość	tożsamość	Szybki start			--

⁽¹⁾Uniwersalne postanowienia licencyjne dotyczące usług online mają zastosowanie do bibliotek w publicznej wersji zapoznawczej.

⁽²⁾Biblioteka Microsoft.IdentityModel weryfikuje tylko tokeny — nie może żądać identyfikatora ani tokenów dostępu.

Wybierz kartę odpowiadającą platformie, która Cię interesuje.

Fragmenty kodu w tym artykule i następujące elementy są wyodrębniane z samouczka przyrostowego aplikacji internetowej platformy ASP.NET Core, rozdział 1.

Aby uzyskać szczegółowe informacje o implementacji, warto zapoznać się z tym samouczkiem.

Pliki konfiguracji

Aplikacje internetowe, które logują użytkowników przy użyciu Platforma tożsamości Microsoft, są konfigurowane za pomocą plików konfiguracji. Te pliki muszą określać następujące wartości:

Warto rozważyć instancję chmury, jeśli chcesz, aby twoja aplikacja działała na przykład w chmurach krajowych. Dostępne są różne opcje:
- https://login.microsoftonline.com/ dla chmury publicznej platformy Azure
- https://login.microsoftonline.us/ dla instytucji rządowych USA na platformie Azure
- https://login.microsoftonline.de/ dla firmy Microsoft Entra Germany
- https://login.partner.microsoftonline.cn/common dla Microsoft Entra China obsługiwanego przez firmę 21Vianet
Odbiorcy w identyfikatorze dzierżawy. Opcje różnią się w zależności od tego, czy aplikacja jest jednodzierżawcza, czy wielodzierżawcza.
- Identyfikator GUID dzierżawy uzyskany z portalu Azure do logowania użytkowników w Twojej organizacji. Można również użyć nazwy domeny.
- organizations aby zalogować użytkowników na dowolnym koncie służbowym lub szkolnym
- common aby zalogować użytkowników przy użyciu dowolnego konta służbowego lub osobistego Microsoft
- consumers aby zalogować użytkowników tylko przy użyciu konta osobistego Microsoft
Identyfikator klienta aplikacji skopiowany z witryny Azure Portal

Mogą również zostać wyświetlone odwołania do autorytetu, będące połączeniem wartości wystąpienia i identyfikatora dzierżawcy.

W ASP.NET Core te ustawienia znajdują się w pliku appsettings.json w sekcji "Microsoft Entra ID".

{
  "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"
  }
}

W programie ASP.NET Core inny plik (properties\launchSettings.json) zawiera adres URL (applicationUrl) i port TLS/SSL (sslPort) dla aplikacji i różnych profilów.

{
  "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/"
    }
  }
}

W portalu Azure identyfikatory URI przekierowania zarejestrowane na stronie Uwierzytelnianie dla Twojej aplikacji muszą być zgodne z tymi adresami URL. W przypadku dwóch poprzednich plików konfiguracji to będzie https://localhost:44321/signin-oidc. Przyczyną jest to, że applicationUrl jest http://localhost:3110, ale sslPort jest określony (44321). CallbackPath to /signin-oidc, zgodnie z definicją w appsettings.json.

W ten sam sposób identyfikator URI wylogowania zostanie ustawiony na https://localhost:44321/signout-oidc.

Uwaga

Parametr SignedOutCallbackPath powinien być ustawiony na portal lub aplikację, aby uniknąć konfliktu podczas obsługi zdarzenia.

W ASP.NET aplikacja jest konfigurowana za pomocą pliku appsettings.json , wiersze od 12 do 15.

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

W portalu Azure URI odpowiedzi, które rejestrujesz na stronie Uwierzytelnianie dla swojej aplikacji, powinny odpowiadać tym adresom URL. Oznacza to, że powinny być https://localhost:44326/.

W języku Java konfiguracja znajduje się w pliku application.properties znajdującym się w lokalizacji 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

W portalu Azure identyfikatory URI odpowiedzi, które zarejestrujesz na stronie Uwierzytelnianie swojej aplikacji, muszą odpowiadać wystąpieniom definiowanym przez aplikację. Oznacza to, że powinny być http://localhost:8080/msal4jsample/secure/aad i http://localhost:8080/msal4jsample/graph/me.

W tym miejscu parametry konfiguracji znajdują się w pliku .env.dev jako zmienne środowiskowe:

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"

Te parametry służą do tworzenia obiektu konfiguracji w pliku authConfig.js , który ostatecznie zostanie użyty do zainicjowania węzła 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
};

W Azure Portal URI odpowiedzi zarejestrowane na stronie uwierzytelniania aplikacji muszą być zgodne z wystąpieniami redirectUri definiowanymi przez aplikację (http://localhost:3000/auth/redirect).

Dla uproszczenia w tym artykule tajny klucz klienta jest przechowywany w pliku konfiguracyjnym. W aplikacji produkcyjnej rozważ użycie magazynu kluczy lub zmiennej środowiskowej. Jeszcze lepszym rozwiązaniem jest użycie certyfikatu.

Parametry konfiguracji są ustawiane w pliku env jako zmienne środowiskowe:

# 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>

Do tych zmiennych środowiskowych odwołuje się 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.

Plik env nigdy nie powinien być zaewidencjonowany w kontroli źródła, ponieważ zawiera wpisy tajne. Przykład szybkiego startu zawiera plik .gitignore, który zapobiega dodaniu do repozytorium pliku .env.

# Environments
.env

Kod inicjowania

Różnice kodu inicjowania są zależne od platformy. W przypadku ASP.NET Core i ASP.NET logowanie użytkowników jest delegowane do oprogramowania pośredniczącego OpenID Connect. Szablon ASP.NET lub ASP.NET Core generuje aplikacje internetowe dla punktu końcowego usługi Azure AD w wersji 1.0. Aby dostosować je do Platforma tożsamości Microsoft, wymagana jest konfiguracja.

W aplikacjach internetowych platformy ASP.NET Core (i internetowych interfejsach API) aplikacja jest chroniona, ponieważ masz Authorize atrybut na kontrolerach lub akcjach kontrolera. Ten atrybut sprawdza, czy użytkownik jest uwierzytelniony. Przed wydaniem platformy .NET 6 inicjowanie kodu znajdowało się w pliku Startup.cs . Nowe projekty ASP.NET Core z platformą .NET 6 nie zawierają już pliku Startup.cs . Jego miejscem jest plik Program.cs . Pozostała część tego samouczka dotyczy platformy .NET 5 lub starszej wersji.

Uwaga

Jeśli chcesz zacząć bezpośrednio od nowych szablonów platformy ASP.NET Core dla platformy tożsamości Microsoft, które korzystają z Microsoft.Identity.Web, możesz pobrać wersję przedpremierową pakietu NuGet zawierającą szablony projektów dla platformy .NET 5.0. Następnie po zainstalowaniu można bezpośrednio stworzyć instancję aplikacji internetowych ASP.NET Core (MVC lub Blazor). Aby uzyskać szczegółowe informacje, zobacz Szablony projektów aplikacji internetowej Microsoft.Identity.Web. Jest to najprostsze podejście, ponieważ wykona wszystkie poniższe kroki.

Jeśli wolisz rozpocząć projekt przy użyciu bieżącego domyślnego szablonu ASP.NET Core web w programie Visual Studio lub za pomocą poleceń dotnet new mvc --auth SingleOrg lub dotnet new webapp --auth SingleOrg, zobaczysz kod podobny do następującego:

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

Ten kod używa starszego pakietu NuGet Microsoft.AspNetCore.Authentication.AzureAD.UI , który służy do tworzenia aplikacji usługi Azure Active Directory w wersji 1.0. W tym artykule wyjaśniono, jak utworzyć aplikację Platforma tożsamości Microsoft w wersji 2.0, która zastępuje ten kod.

Dodaj pakiety NuGet Microsoft.Identity.Web i Microsoft.Identity.Web.UI do projektu. Usuń pakiet NuGet Microsoft.AspNetCore.Authentication.AzureAD.UI, jeśli jest obecny.

Zaktualizuj kod w ConfigureServices, aby używał metod AddMicrosoftIdentityWebApp i 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();

W metodzie Configure w Startup.cs włącz uwierzytelnianie za pomocą wywołania metody app.UseAuthentication(); i 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
}

W tym kodzie:

Metoda rozszerzenia AddMicrosoftIdentityWebApp jest zdefiniowana w Microsoft.Identity.Web, który;
- Konfiguruje opcje odczytu pliku konfiguracji (tutaj w sekcji "Microsoft Entra ID")
- Konfiguruje opcje OpenID Connect tak, aby autorytetem była platforma tożsamości Microsoft.
- Weryfikuje wystawcę tokenu.
- Gwarantuje, że twierdzenia odpowiadające nazwie są mapowane z preferred_username twierdzenia w tokenie identyfikatora.
Oprócz obiektu konfiguracji można określić nazwę sekcji konfiguracji podczas wywoływania metody AddMicrosoftIdentityWebApp. Domyślnie to jest AzureAd.
AddMicrosoftIdentityWebApp ma inne parametry dla zaawansowanych scenariuszy. Na przykład śledzenie zdarzeń oprogramowania pośredniczącego OpenID Connect może pomóc w rozwiązywaniu problemów z aplikacją internetową, jeśli uwierzytelnianie nie działa. Ustawienie opcjonalnego parametru subscribeToOpenIdConnectMiddlewareDiagnosticsEvents na true spowoduje wyświetlenie, jak informacje są przetwarzane przez zestaw oprogramowania pośredniczącego ASP.NET Core w miarę, jak postępują od odpowiedzi HTTP do tożsamości użytkownika w programie HttpContext.User.
Metoda rozszerzenia AddMicrosoftIdentityUI jest zdefiniowana w Microsoft.Identity.Web.UI. Zapewnia on domyślny kontroler do obsługi logowania i wylogowywania.

Aby uzyskać więcej informacji na temat sposobu tworzenia aplikacji internetowych w witrynie Microsoft.Identity.Web, zobacz Web Apps in microsoft-identity-web (Aplikacje internetowe w witrynie microsoft-identity-web).

Kod związany z uwierzytelnianiem w aplikacji internetowej ASP.NET i internetowych interfejsach API znajduje się w pliku 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);
 }

W przykładzie języka Java jest używana platforma Spring. Aplikacja jest chroniona, ponieważ implementujesz filtr, który przechwytuje każdą odpowiedź HTTP. W przewodniku szybkiego startu dla aplikacji internetowych Javy ten filtr jest AuthFilter w src/main/java/com/microsoft/azure/msalwebsample/AuthFilter.java.

Filtr przetwarza przepływ kodu autoryzacji OAuth 2.0 i sprawdza, czy użytkownik jest uwierzytelniony (isAuthenticated() metoda). Jeśli użytkownik nie jest uwierzytelniony, system oblicza adres URL punktów końcowych autoryzacji Microsoft Entra i przekierowuje przeglądarkę do tego adresu URL.

Po nadejściu odpowiedzi zawierającej kod autoryzacji uzyskuje token przy użyciu biblioteki MSAL Java. Gdy w końcu odbierze token z punktu końcowego tokenu (na URI przekierowania), użytkownik jest zalogowany.

Aby uzyskać szczegółowe informacje, zobacz metodę doFilter() w AuthFilter.java.

Uwaga

Kod obiektu doFilter() jest napisany w nieco innej kolejności, ale przepływ jest opisany.

Aby uzyskać szczegółowe informacje na temat przepływu kodu autoryzacji wyzwalanego przez tę metodę, zobacz Platformę tożsamości Microsoft i przepływ kodu autoryzacji OAuth 2.0.

Przykładowa aplikacja Node używa frameworka Express. Biblioteka MSAL jest inicjowana w procedurze obsługi tras uwierzytelniania :

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: '/'

Przykład języka Python jest kompilowany przy użyciu platformy Flask, chociaż mogą być również używane inne struktury, takie jak Django. Aplikacja Flask jest inicjowana przy użyciu konfiguracji aplikacji w górnej części 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)

Następnie kod tworzy auth obiekt przy użyciu pakietu identity.

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

Następny krok

Zaloguj się i wyloguj się.

Udostępnij za pośrednictwem

Aplikacja internetowa, która loguje użytkowników: konfiguracja kodu

Biblioteki firmy Microsoft obsługujące aplikacje internetowe

Pliki konfiguracji

Kod inicjowania

Następny krok

Opinia

Dodatkowe zasoby