App Web che accede agli utenti: Configurazione del codice

Articolo
10/24/2023

Informazioni su come configurare il codice per l'app Web che accede 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	Ottenere avviata	Consentire l'accesso degli utenti	Accedere alle API Web	Disponibile a livello generale (GA) o Anteprima^{pubblica 1}
.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 l'ID o i token di accesso.

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

I frammenti di codice in questo articolo e i seguenti vengono estratti dall'esercitazione incrementale dell'app Web core di ASP.NET, capitolo 1.

Per informazioni dettagliate sull'implementazione, è possibile fare riferimento a questa esercitazione.

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 vuole che l'app venga eseguita in cloud nazionali, ad esempio. Le diverse opzioni includono;
- https://login.microsoftonline.com/ per il 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 China 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 accedere agli utenti in qualsiasi account aziendale o dell'istituto di istruzione
- common per accedere agli utenti con qualsiasi account aziendale o dell'istituto di istruzione o account personale Microsoft
- consumers per accedere agli utenti solo con un account personale Microsoft
ID client per l'applicazione, copiato dal portale di Azure

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

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 (proprietà\launch Impostazioni.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/"
    }
  }
}

Nella 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, sono https://localhost:44321/signin-oidc. Il motivo è che applicationUrl è http://localhost:3110, ma sslPort è specificato (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 deve 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 di 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]",
  }
}

Nella portale di Azure, gli URI di risposta 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

Nella portale di Azure gli URI di risposta registrati nella pagina Autenticazione dell'applicazione devono corrispondere redirectUri alle istanze 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
};

Nella portale di Azure gli URI di risposta registrati nella pagina Autenticazione dell'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 con estensione env non deve mai essere archiviato nel controllo del codice sorgente, perché contiene segreti. L'esempio di avvio rapido include un file con estensione gitignore che impedisce l'archiviazione del file con estensione env .

# Environments
.env

Codice di inizializzazione

Le differenze di codice di inizializzazione sono dipendenti dalla piattaforma. Per ASP.NET Core e ASP.NET, l'accesso degli utenti viene delegato al middleware openID Connessione. 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 Authorize attributo 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 era 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 vuole 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 Microsoft.AspNetCore.Authentication.AzureAD.UI pacchetto NuGet, se presente.

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

Configure Nel metodo in Startup.cs abilitare 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 AddMicrosoftIdentityWebApp metodo di estensione è definito in Microsoft.Identity.Web, che;
- Configura le opzioni per leggere il file di configurazione (qui dalla sezione "Microsoft Entra ID")
- Configura le opzioni di Connessione OpenID 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. Per impostazione predefinita, è AzureAd.
AddMicrosoftIdentityWebApp include altri parametri per scenari avanzati. Ad esempio, la traccia di openID Connessione eventi middleware consente di risolvere i problemi dell'applicazione Web se l'autenticazione non funziona. L'impostazione del parametro subscribeToOpenIdConnectMiddlewareDiagnosticsEvents facoltativo su true mostrerà come vengono elaborate le informazioni dal set di middleware ASP.NET Core man mano che procede dalla risposta HTTP all'identità dell'utente in HttpContext.User.
Il AddMicrosoftIdentityUI metodo di estensione è definito in Microsoft.Identity.Web.UI. Fornisce un controller predefinito per gestire l'accesso e la disconnessura.

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. Nella guida introduttiva 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 (isAuthenticated() metodo). 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 doFilter() metodo 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 nel gestore della route di autenticazione :

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 identity.

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

Passaggi successivi

Nell'articolo successivo si apprenderà come attivare l'accesso e la disconnessità.

Passare all'articolo successivo in questo scenario, Accedere e disconnettersi.

App Web che accede agli utenti: Configurazione del codice

Librerie Microsoft che supportano le app Web

File di configurazione

Codice di inizializzazione

Passaggi successivi

Risorse aggiuntive