Inizializzare le applicazioni client usando MSAL.js

Articolo
07/10/2024

Questo articolo descrive l'inizializzazione di Microsoft Authentication Library per JavaScript (MSAL.js) con un'istanza di un'applicazione agente utente.

L'applicazione agente utente è una forma di applicazione client pubblica in cui il codice client viene eseguito in un agente utente, ad esempio un Web browser. I client come questi non archiviano segreti perché il contesto del browser è accessibile pubblicamente.

Per altre informazioni sui tipi di applicazione client e sulle opzioni di configurazione dell'applicazione, vedere App client pubbliche e riservate in MSAL.

Prerequisiti

Prima di inizializzare un'applicazione, è necessario registrarla nell'Interfaccia di amministrazione di Microsoft Entra stabilendo una relazione di trust tra l'applicazione e Microsoft Identity Platform.

Dopo aver registrato l'app, sono necessari alcuni o tutti i valori seguenti disponibili nell'Interfaccia di amministrazione di Microsoft Entra.

Valore	Obbligatorio	Descrizione
ID applicazione (client)	Richiesto	Un GUID che identifica in modo univoco l'applicazione all'interno di Microsoft Identity Platform.
Autorità	Facoltativo	L'URL del provider di identità (l'istanza) e i destinatari di accesso dell'applicazione. L'istanza e i destinatari di accesso, se concatenati, costituiscono l'autorità.
ID della directory (tenant)	Facoltativo	Specificare l'ID directory (tenant) se si sta creando un'applicazione line-of-business esclusivamente per l'organizzazione, spesso definita applicazione a tenant singolo.
URI di reindirizzamento	Facoltativo	Se si sta creando un'app Web, `redirectUri` specifica dove il provider di identità (Microsoft Identity Platform) deve restituire i token di sicurezza che ha prodotto.

Inizializzare applicazioni MSAL.js 2.x

Inizializzare il contesto di autenticazione MSAL.js creando un'istanza PublicClientApplication con un oggetto Configuration. La proprietà di configurazione minima richiesta è clientID dell'applicazione, visualizzato come ID (client) applicazione nella pagina delle Informazioni generali della registrazione dell'app nell'Interfaccia di amministrazione di Microsoft Entra.

Ecco un esempio di oggetto di configurazione e creazione di un'istanza di PublicClientApplication:

const msalConfig = {
  auth: {
    clientId: "Enter_the_Application_Id_Here",
    authority: "https://login.microsoftonline.com/Enter_the_Tenant_Info_Here",
    knownAuthorities: [],
    redirectUri: "https://localhost:{port}/redirect",
    postLogoutRedirectUri: "https://localhost:{port}/redirect",
    navigateToLoginRequestUrl: true,
  },
  cache: {
    cacheLocation: "sessionStorage",
    storeAuthStateInCookie: false,
  },
  system: {
    loggerOptions: {
      loggerCallback: (
        level: LogLevel,
        message: string,
        containsPii: boolean
      ): void => {
        if (containsPii) {
          return;
        }
        switch (level) {
          case LogLevel.Error:
            console.error(message);
            return;
          case LogLevel.Info:
            console.info(message);
            return;
          case LogLevel.Verbose:
            console.debug(message);
            return;
          case LogLevel.Warning:
            console.warn(message);
            return;
        }
      },
      piiLoggingEnabled: false,
    },
    windowHashTimeout: 60000,
    iframeHashTimeout: 6000,
    loadFrameTimeout: 0,
  },
};

// Create an instance of PublicClientApplication
const msalInstance = new PublicClientApplication(msalConfig);

// Handle the redirect flows
msalInstance
  .handleRedirectPromise()
  .then((tokenResponse) => {
    // Handle redirect response
  })
  .catch((error) => {
    // Handle redirect error
  });

`handleRedirectPromise`

Richiamare handleRedirectPromise quando l'applicazione usa flussi di reindirizzamento. Quando si usano i flussi di reindirizzamento, handleRedirectPromise deve essere eseguito in ogni caricamento di pagina.

Tre risultati sono possibili dalla promessa:

.then viene richiamato e tokenResponse è vero: l'applicazione viene restituita da un'operazione di reindirizzamento che ha avuto esito positivo.
.then viene richiamato e tokenResponse è falso (null): l'applicazione non viene restituita da un'operazione di reindirizzamento.
.catch viene richiamato: l'applicazione viene restituita da un'operazione di reindirizzamento e si è verificato un errore.

Inizializzare applicazioni MSAL.js 1.x

Inizializzare il contesto di autenticazione MSAL 1.x creando un'istanza di UserAgentApplication con un oggetto di configurazione. La proprietà di configurazione minima richiesta è clientID dell'applicazione, visualizzata come ID applicazione (client) nella pagina Panoramica della registrazione dell'app nell'Interfaccia di amministrazione di Microsoft Entra.

Per i metodi di autenticazione con flussi di reindirizzamento (loginRedirect e acquireTokenRedirect) in MSAL.js 1.2.x o versioni precedenti, è necessario registrare in modo esplicito l'esito positivo o l'errore di un callback tramite il metodo handleRedirectCallback(). La registrazione esplicita del callback è necessaria in MSAL.js 1.2.x e versioni precedenti perché i flussi di reindirizzamento non restituiscono promesse diversamente dai metodi con un'esperienza popup. La registrazione del callback è facoltativa in MSAL.js versione 1.3.x e successive.

// Configuration object constructed
const msalConfig = {
  auth: {
    clientId: "Enter_the_Application_Id_Here",
  },
};

// Create UserAgentApplication instance
const msalInstance = new UserAgentApplication(msalConfig);

function authCallback(error, response) {
  // Handle redirect response
}

// Register a redirect callback for Success or Error (when using redirect methods)
// **REQUIRED** in MSAL.js 1.2.x and earlier
// **OPTIONAL** in MSAL.js 1.3.x and later
msalInstance.handleRedirectCallback(authCallback);

Istanza singola e configurazione

Entrambi MSAL.js 1.x e 2.x sono progettati per avere una singola istanza e una configurazione rispettivamente di UserAgentApplication o PublicClientApplication per rappresentare un singolo contesto di autenticazione.

Più istanze di UserAgentApplication o PublicClientApplication non sono consigliate perché possono causare voci di cache e comportamento nel browser in conflitto.

Passaggi successivi

L'esempio di codice MSAL.js 2.x in GitHub illustra la creazione di un'istanza di PublicClientApplication con un oggetto Configuration:

Condividi tramite