App Web che effettua l’accesso degli utenti: configurazione del codice

Articolo
08/01/2024

Questo articolo descrive come configurare il codice per un'app Web che consente di accedere agli utenti.

Librerie Microsoft che supportano le app Web

Le librerie Microsoft seguenti vengono usate per proteggere un'app Web (e un'API Web):

Linguaggio/framework	Progetto in GitHub	Pacchetto	Recupero avviata	Consentire l'accesso degli utenti	Accedere alle API Web	Disponibile a livello generale (GA) o Anteprima pubblica¹
.NET	MSAL.NET	Microsoft.Identity.Client	—			Disponibilità generale
.NET	Microsoft.IdentityModel	Microsoft.IdentityModel	—	²	²	Disponibilità generale
ASP.NET Core	ASP.NET Core	Microsoft.AspNetCore.Authentication	Guida introduttiva			Disponibilità generale
ASP.NET Core	Microsoft.Identity.Web	Microsoft.Identity.Web	Guida introduttiva			Disponibilità generale
Java	MSAL4J	msal4j	Guida introduttiva			Disponibilità generale
Spring	spring-cloud-azure-starter-active-directory	spring-cloud-azure-starter-active-directory	Esercitazione			Disponibilità generale
Node.js	MSAL Node	msal-node	Guida introduttiva			Disponibilità generale
Python	MSAL Python	msal				Disponibilità generale
Python	identity	identity	Guida introduttiva			--

⁽¹⁾ Le condizioni di licenza universali per i servizi online si applicano alle librerie in anteprima pubblica.

⁽²⁾ La libreria Microsoft.IdentityModel convalida solo i token. Non può richiedere token ID o di accesso.

Selezionare la scheda corrispondente alla piattaforma a cui si è interessati:

I frammenti di codice di questo articolo e dei successivi sono tratti dal capitolo 1 dell’esercitazione incrementale di app Web ASP.NET Core.

È possibile fare riferimento all'esercitazione per i dettagli di implementazione completi.

File di configurazione

Le applicazioni Web che consentono l'accesso degli utenti tramite Microsoft Identity Platform vengono configurate tramite file di configurazione. Tali file devono specificare i valori seguenti:

L'istanza cloud se si desidera che l'app venga eseguita in cloud nazionali, per esempio. Le diverse opzioni includono;
- https://login.microsoftonline.com/ per cloud pubblico di Azure
- https://login.microsoftonline.us/ per Azure US Government
- https://login.microsoftonline.de/ per Microsoft Entra Germania
- https://login.partner.microsoftonline.cn/common per Microsoft Entra Cina gestito da 21Vianet
Gruppo di destinatari nell'ID tenant. Le opzioni variano a seconda che l'app sia a tenant singolo o multi-tenant.
- GUID del tenant ottenuto dal portale di Azure per consentire agli utenti dell'organizzazione di accedere. È anche possibile usare un nome di dominio.
- organizations per consentire agli utenti di accedere a qualsiasi account aziendale o dell'istituto di istruzione
- common per consentire agli utenti di accedere con qualsiasi account aziendale o dell'istituto di istruzione o account personale Microsoft
- consumers per consentire agli utenti di accedere solo con un account personale Microsoft
L’ID client dell'applicazione copiato dal portale di Azure

È anche possibile visualizzare riferimenti all'autorità, una concatenazione dei valori instance e tenant ID.

In ASP.NET Core queste impostazioni si trovano nel file appsettings.json, nella sezione "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"
  }
}

In ASP.NET Core, un altro file (properties\launchSettings.json) contiene l'URL (applicationUrl) e la porta TLS/SSL (sslPort) per l'applicazione e i vari profili.

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

Nel portale di Azure gli URI di reindirizzamento registrati nella pagina Autenticazione per l'applicazione devono corrispondere a questi URL. Per i due file di configurazione precedenti, sarebbero https://localhost:44321/signin-oidc. Il motivo è che applicationUrl è http://localhost:3110, ma è specificato sslPort (44321). CallbackPath è /signin-oidc, come definito in appsettings.json.

Allo stesso modo, l'URI di disconnessione verrebbe impostato su https://localhost:44321/signout-oidc.

Nota

SignedOutCallbackPath dovrebbe essere impostato sul portale o sull'applicazione per evitare conflitti durante la gestione dell'evento.

In ASP.NET l'applicazione viene configurata tramite il file appsettings.json, le righe da 12 a 15.

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

Nel portale di Azure gli URI di replica registrati nella pagina Autenticazione per l'applicazione devono corrispondere a questi URL. Vale a dire, dovrebbero essere https://localhost:44326/.

In Java la configurazione si trova nel file application.properties che si trova in 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

Nel portale di Azure gli URI di replica registrati nella pagina Autenticazione per l'applicazione devono corrispondere alle istanze redirectUri definite dall’applicazione. Vale a dire, dovrebbero essere http://localhost:8080/msal4jsample/secure/aad e http://localhost:8080/msal4jsample/graph/me.

In questo caso, i parametri di configurazione risiedono in .env.dev come variabili di ambiente:

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"

Questi parametri vengono usati per creare un oggetto di configurazione nel file authConfig.js, che verrà infine usato per inizializzare il nodo 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
};

Nel portale di Azure gli URI di replica registrati nella pagina Autenticazione per l'applicazione devono corrispondere alle istanze redirectUri definite dall’applicazione (http://localhost:3000/auth/redirect).

Per semplicità in questo articolo, il segreto client viene archiviato nel file di configurazione. Nell'app di produzione prendere in considerazione l'uso di un insieme di credenziali delle chiavi o di una variabile di ambiente. Un'opzione ancora migliore consiste nell'usare un certificato.

I parametri di configurazione vengono impostati in .env come variabili di ambiente:

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

Tali variabili di ambiente vengono a cui si fa riferimento in 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.

Il file .env non dovrebbe mai essere archiviato nel controllo del codice sorgente, perché contiene segreti. L'esempio di avvio rapido include un file .gitignore che impedisce l'archiviazione del file .env.

# Environments
.env

Codice di inizializzazione

Le differenze di codice di inizializzazione dipendono dalla piattaforma. Per ASP.NET Core e ASP.NET, l'accesso degli utenti viene delegato al middleware OpenID Connect. Il modello ASP.NET o ASP.NET Core genera applicazioni Web per l'endpoint di Azure AD v1.0. Alcune configurazioni sono necessarie per adattarle a Microsoft Identity Platform.

In ASP.NET App Web core (e API Web), l'applicazione è protetta perché si dispone di un attributo Authorize nei controller o nelle azioni del controller. Questo attributo verifica che l'utente sia autenticato. Prima del rilascio di .NET 6, l'inizializzazione del codice si trovava nel file Startup.cs. I nuovi progetti ASP.NET Core con .NET 6 non contengono più un file Startup.cs. L'esecuzione del file è il file Program.cs. La parte restante di questa esercitazione riguarda .NET 5 o versione precedente.

Nota

Se si desidera iniziare direttamente con i nuovi modelli di ASP.NET Core per Microsoft Identity Platform, che sfruttano Microsoft.Identity.Web, è possibile scaricare un pacchetto NuGet di anteprima contenente i modelli di progetto per .NET 5.0. Dopo l'installazione, è quindi possibile creare direttamente un'istanza di ASP.NET applicazioni Web Core (MVC o Blazor). Per informazioni dettagliate, vedere Modelli di progetto di app Web Microsoft.Identity.Web. Questo è l'approccio più semplice perché eseguirà tutti i passaggi seguenti.

Se si preferisce avviare il progetto con l'impostazione predefinita corrente ASP.NET progetto Web Core in Visual Studio o usando dotnet new mvc --auth SingleOrg o dotnet new webapp --auth SingleOrg, verrà visualizzato codice simile al seguente:

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

Questo codice usa il pacchetto NuGet Microsoft.AspNetCore.Authentication.AzureAD.UI legacy usato per creare un'applicazione Azure Active Directory v1.0. Questo articolo illustra come creare un'applicazione Microsoft Identity Platform v2.0 che sostituisce tale codice.

Aggiungere i pacchetti NuGet Microsoft.Identity.Web e Microsoft.Identity.Web.UI al progetto. Rimuovere il pacchetto NuGet Microsoft.AspNetCore.Authentication.AzureAD.UI, se presente.

Aggiornare il codice in ConfigureServices in modo che usi i metodi AddMicrosoftIdentityWebApp e 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();

Nel metodo Configure in Startup.csabilitare l'autenticazione con una chiamata a app.UseAuthentication(); e 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
}

Nel codice:

Il metodo di estensione AddMicrosoftIdentityWebApp viene definito in Microsoft.Identity.Web, che;
- Configura le opzioni per leggere il file di configurazione (qui dalla sezione "Microsoft Entra ID")
- Configura le opzioni OpenID Connect in modo che l'autorità sia Microsoft Identity Platform.
- Convalida l'autorità di certificazione del token.
- Assicura che le attestazioni corrispondenti al nome vengano mappate dall'attestazione preferred_username nel token ID.
Oltre all'oggetto di configurazione, è possibile specificare il nome della sezione di configurazione quando si chiama AddMicrosoftIdentityWebApp. L'impostazione predefinita è AzureAd.
AddMicrosoftIdentityWebApp include altri parametri per scenari avanzati. Ad esempio, la traccia degli eventi middleware OpenID Connect consente di risolvere i problemi dell'applicazione Web se l'autenticazione non funziona. L'impostazione del parametro facoltativo subscribeToOpenIdConnectMiddlewareDiagnosticsEvents su true mostrerà come vengono elaborate le informazioni dal set di middleware ASP.NET Core man mano che passa dalla risposta HTTP all'identità dell'utente in HttpContext.User.
Il metodo di estensione AddMicrosoftIdentityUI viene definito in Microsoft.Identity.Web.UI. Fornisce un controller predefinito per gestire l'accesso e la disconnessione.

Per altre informazioni su come Microsoft.Identity.Web consente di creare app Web, vedere App Web in microsoft-identity-web.

Il codice correlato all'autenticazione in un'app Web ASP.NET e alle API Web si trova nel file 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);
 }

L'esempio Java usa spring framework. L'applicazione è protetta perché si implementa un filtro che intercetta ogni risposta HTTP. Nell’avvio rapido per le app Web Java questo filtro è AuthFilter in src/main/java/com/microsoft/azure/msalwebsample/AuthFilter.java.

Il filtro elabora il flusso del codice di autorizzazione OAuth 2.0 e controlla se l'utente è autenticato (metodo isAuthenticated()). Se l'utente non è autenticato, calcola l'URL degli endpoint di autorizzazione di Microsoft Entra e reindirizza il browser a questo URI.

Quando arriva la risposta, contenente il codice di autorizzazione, acquisisce il token usando MSAL Java. Quando riceve infine il token dall'endpoint del token (nell'URI di reindirizzamento), l'utente ha eseguito l'accesso.

Per informazioni dettagliate, vedere il metodo doFilter() in AuthFilter.java.

Nota

Il codice di doFilter() viene scritto in un ordine leggermente diverso, ma il flusso è quello descritto.

Per informazioni dettagliate sul flusso del codice di autorizzazione attivato da questo metodo, vedere il flusso del codice di autorizzazione di Microsoft Identity Platform e OAuth 2.0.

L'esempio Node usa il framework Express. MSAL viene inizializzato in gestore di route auth:

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

L'esempio Python viene compilato con il framework Flask, anche se è possibile usare anche altri framework come Django. L'app Flask viene inizializzata con la configurazione dell'app nella parte superiore di 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)

Il codice crea quindi un auth oggetto usando il pacchetto dell’identità.

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

Passaggio successivo

Accedere e disconnettersi.

Condividi tramite

App Web che effettua l’accesso degli utenti: configurazione del codice

Librerie Microsoft che supportano le app Web

File di configurazione

Codice di inizializzazione

Passaggio successivo

Commenti e suggerimenti

Risorse aggiuntive