Applicazione a pagina singola: acquisire un token per chiamare un'API

Il modello per l'acquisizione di token per le API con MSAL.js consiste nel tentare prima di tutto una richiesta di token invisibile all'utente usando il metodo acquireTokenSilent. Quando questo metodo viene chiamato, la libreria controlla innanzitutto la cache nell'archiviazione del browser per verificare se esiste un token di accesso non scaduto e lo restituisce. Se non viene trovato alcun token di accesso o il token trovato è scaduto, tenta di usare il token di aggiornamento per ottenere un nuovo token di accesso. Se anche la durata di 24 ore del token di aggiornamento è scaduta, MSAL.js apre un iframe nascosto per richiedere automaticamente un nuovo codice di autorizzazione usando la sessione attiva esistente con Microsoft Entra ID (se presente), che verrà scambiato per un nuovo set di token (token di accesso e token di aggiornamento). Per altre informazioni sui valori di durata dei token e della sessione Single Sign-On (SSO) in Microsoft Entra ID, vedere Durate dei token. Per altre informazioni sui criteri di ricerca della cache MSAL.js, vedere: Acquisizione di un token di accesso.

Le richieste di token invisibili all'utente a Microsoft Entra ID potrebbero non riuscire per motivi come una modifica della password o dei criteri di accesso condizionale aggiornati. Più spesso, gli errori sono dovuti alla scadenza del token di aggiornamento di 24 ore e al browser che blocca i cookie di terze parti, cosa che impedisce l'uso di iframe nascosti per continuare l'autenticazione dell'utente. In questi casi, è necessario richiamare uno dei metodi interattivi (che potrebbero richiedere all'utente di acquisire i token):

• Finestra popup, usando acquireTokenPopup
• Reindirizzamento usando acquireTokenRedirect

Scegliere tra un'esperienza popup o di reindirizzamento

La scelta tra un'esperienza popup o di reindirizzamento dipende dal flusso dell'applicazione:

• Se non si vuole che gli utenti si spostino dalla pagina principale dell'applicazione durante l'autenticazione, è consigliabile usare il metodo popup. Poiché il reindirizzamento dell'autenticazione si verifica in una finestra popup, lo stato dell'applicazione principale viene mantenuto.

• Se gli utenti hanno vincoli o criteri del browser in cui le finestre popup sono disabilitate, è possibile usare il metodo di reindirizzamento. Usare il metodo di reindirizzamento con il browser Internet Explorer, perché sono presenti problemi noti relativi alle finestre popup in Internet Explorer.

È possibile impostare gli ambiti API da includere nel token di accesso durante la compilazione della richiesta di token di accesso. Tutti gli ambiti richiesti potrebbero non essere concessi nel token di accesso. Ciò dipende dal consenso dell'utente.

Acquisire un token con una finestra popup

JavaScript (MSAL.js v2)

Il codice seguente combina il modello descritto in precedenza con i metodi per un'esperienza popup:

// MSAL.js v2 exposes several account APIs, logic to determine which account to use is the responsibility of the developer
const account = publicClientApplication.getAllAccounts()[0];

const accessTokenRequest = {
  scopes: ["user.read"],
  account: account,
};

publicClientApplication
  .acquireTokenSilent(accessTokenRequest)
  .then(function (accessTokenResponse) {
    // Acquire token silent success
    let accessToken = accessTokenResponse.accessToken;
    // Call your API with token
    callApi(accessToken);
  })
  .catch(function (error) {
    //Acquire token silent failure, and send an interactive request
    if (error instanceof InteractionRequiredAuthError) {
      publicClientApplication
        .acquireTokenPopup(accessTokenRequest)
        .then(function (accessTokenResponse) {
          // Acquire token interactive success
          let accessToken = accessTokenResponse.accessToken;
          // Call your API with token
          callApi(accessToken);
        })
        .catch(function (error) {
          // Acquire token interactive failure
          console.log(error);
        });
    }
    console.log(error);
  });

JavaScript (MSAL.js v1)

Il codice seguente combina il modello descritto in precedenza con i metodi per un'esperienza popup:

const accessTokenRequest = {
  scopes: ["user.read"],
};

userAgentApplication
  .acquireTokenSilent(accessTokenRequest)
  .then(function (accessTokenResponse) {
    // Acquire token silent success
    // Call API with token
    let accessToken = accessTokenResponse.accessToken;
  })
  .catch(function (error) {
    //Acquire token silent failure, and send an interactive request
    if (error.errorMessage.indexOf("interaction_required") !== -1) {
      userAgentApplication
        .acquireTokenPopup(accessTokenRequest)
        .then(function (accessTokenResponse) {
          // Acquire token interactive success
        })
        .catch(function (error) {
          // Acquire token interactive failure
          console.log(error);
        });
    }
    console.log(error);
  });

Angular (MSAL.js v2)

Il wrapper Angular MSAL fornisce l'intercettore HTTP, che acquisirà automaticamente i token di accesso in modo invisibile all'utente e li allegherà alle richieste HTTP alle API.

È possibile specificare gli ambiti per le API nell'opzione di configurazione protectedResourceMap. MsalInterceptor richiede gli ambiti specificati durante l'acquisizione automatica dei token.

// In app.module.ts
import { PublicClientApplication, InteractionType } from "@azure/msal-browser";
import { MsalInterceptor, MsalModule } from "@azure/msal-angular";

@NgModule({
  declarations: [
    // ...
  ],
  imports: [
    // ...
    MsalModule.forRoot(
      new PublicClientApplication({
        auth: {
          clientId: "Enter_the_Application_Id_Here",
        },
        cache: {
          cacheLocation: "localStorage",
          storeAuthStateInCookie: isIE,
        },
      }),
      {
        interactionType: InteractionType.Popup,
        authRequest: {
          scopes: ["user.read"],
        },
      },
      {
        interactionType: InteractionType.Popup,
        protectedResourceMap: new Map([
          ["https://graph.microsoft.com/v1.0/me", ["user.read"]],
        ]),
      }
    ),
  ],
  providers: [
    {
      provide: HTTP_INTERCEPTORS,
      useClass: MsalInterceptor,
      multi: true,
    },
  ],
  bootstrap: [AppComponent],
})
export class AppModule {}

Per l'esito positivo e negativo dell'acquisizione di token invisibile all'utente, MSAL Angular fornisce eventi a cui è possibile sottoscriversi. È anche importante ricordarsi di annullare la sottoscrizione.

import { MsalBroadcastService } from '@azure/msal-angular';
import { EventMessage, EventType } from '@azure/msal-browser';

import { filter, Subject, takeUntil } from 'rxjs';

// In app.component.ts
export class AppComponent implements OnInit {
  private readonly _destroying$ = new Subject<void>();

  constructor(private broadcastService: MsalBroadcastService) { }

  ngOnInit() {
    this.broadcastService.msalSubject$
    .pipe(
      filter((msg: EventMessage) => msg.eventType === EventType.ACQUIRE_TOKEN_SUCCESS),
      takeUntil(this._destroying$)
    )
    .subscribe((result: EventMessage) => {
      // Do something with event payload here
    });
  }

  ngOnDestroy(): void {
    this._destroying$.next(undefined);
    this._destroying$.complete();
  }
}

In alternativa, è possibile acquisire in modo esplicito i token usando i metodi acquire-token, come descritto nella libreria principale MSAL.js.

Angular (MSAL.js v1)

Il wrapper Angular MSAL fornisce l'intercettore HTTP, che acquisirà automaticamente i token di accesso in modo invisibile all'utente e li allegherà alle richieste HTTP alle API. È possibile specificare gli ambiti per le API nell'opzione di configurazione protectedResourceMap. MsalInterceptor richiede gli ambiti specificati durante l'acquisizione automatica dei token.

// app.module.ts
@NgModule({
  declarations: [
    // ...
  ],
  imports: [
    // ...
    MsalModule.forRoot(
      {
        auth: {
          clientId: "Enter_the_Application_Id_Here",
        },
      },
      {
        popUp: !isIE,
        consentScopes: ["user.read", "openid", "profile"],
        protectedResourceMap: [
          ["https://graph.microsoft.com/v1.0/me", ["user.read"]],
        ],
      }
    ),
  ],
  providers: [
    {
      provide: HTTP_INTERCEPTORS,
      useClass: MsalInterceptor,
      multi: true,
    },
  ],
  bootstrap: [AppComponent],
})
export class AppModule {}

Per l'esito positivo e negativo dell'acquisizione di token invisibile all'utente, MSAL Angular fornisce callback a cui è possibile sottoscriversi. È anche importante ricordarsi di annullare la sottoscrizione.

// In app.component.ts
 ngOnInit() {
    this.subscription = this.broadcastService.subscribe("msal:acquireTokenFailure", (payload) => {
    });
}
ngOnDestroy() {
   this.broadcastService.getMSALSubject().next(1);
   if (this.subscription) {
     this.subscription.unsubscribe();
   }
 }

In alternativa, è possibile acquisire in modo esplicito i token usando i metodi acquire-token, come descritto nella libreria principale MSAL.js.

React

Il codice seguente combina il modello descritto in precedenza con i metodi per un'esperienza popup:

import {
  InteractionRequiredAuthError,
  InteractionStatus,
} from "@azure/msal-browser";
import { AuthenticatedTemplate, useMsal } from "@azure/msal-react";

function ProtectedComponent() {
  const { instance, inProgress, accounts } = useMsal();
  const [apiData, setApiData] = useState(null);

  useEffect(() => {
    if (!apiData && inProgress === InteractionStatus.None) {
      const accessTokenRequest = {
        scopes: ["user.read"],
        account: accounts[0],
      };
      instance
        .acquireTokenSilent(accessTokenRequest)
        .then((accessTokenResponse) => {
          // Acquire token silent success
          let accessToken = accessTokenResponse.accessToken;
          // Call your API with token
          callApi(accessToken).then((response) => {
            setApiData(response);
          });
        })
        .catch((error) => {
          if (error instanceof InteractionRequiredAuthError) {
            instance
              .acquireTokenPopup(accessTokenRequest)
              .then(function (accessTokenResponse) {
                // Acquire token interactive success
                let accessToken = accessTokenResponse.accessToken;
                // Call your API with token
                callApi(accessToken).then((response) => {
                  setApiData(response);
                });
              })
              .catch(function (error) {
                // Acquire token interactive failure
                console.log(error);
              });
          }
          console.log(error);
        });
    }
  }, [instance, accounts, inProgress, apiData]);

  return <p>Return your protected content here: {apiData}</p>;
}

function App() {
  return (
    <AuthenticatedTemplate>
      <ProtectedComponent />
    </AuthenticatedTemplate>
  );
}

In alternativa, se è necessario acquisire un token all'esterno di un componente React, è possibile chiamare acquireTokenSilent ma senza eseguire il fallback all'interazione in caso di errore. Tutte le interazioni devono essere eseguite sotto il componente MsalProvider nell'albero dei componenti.

// MSAL.js v2 exposes several account APIs, logic to determine which account to use is the responsibility of the developer
const account = publicClientApplication.getAllAccounts()[0];

const accessTokenRequest = {
  scopes: ["user.read"],
  account: account,
};

// Use the same publicClientApplication instance provided to MsalProvider
publicClientApplication
  .acquireTokenSilent(accessTokenRequest)
  .then(function (accessTokenResponse) {
    // Acquire token silent success
    let accessToken = accessTokenResponse.accessToken;
    // Call your API with token
    callApi(accessToken);
  })
  .catch(function (error) {
    //Acquire token silent failure
    console.log(error);
  });

Acquisire un token con un reindirizzamento

JavaScript (MSAL.js v2)

Il modello seguente è come descritto in precedenza, ma illustrato con un metodo di reindirizzamento per acquisire i token in modo interattivo. È necessario chiamare e attendere handleRedirectPromise al caricamento della pagina.

const redirectResponse = await publicClientApplication.handleRedirectPromise();
if (redirectResponse !== null) {
  // Acquire token silent success
  let accessToken = redirectResponse.accessToken;
  // Call your API with token
  callApi(accessToken);
} else {
  // MSAL.js v2 exposes several account APIs, logic to determine which account to use is the responsibility of the developer
  const account = publicClientApplication.getAllAccounts()[0];

  const accessTokenRequest = {
    scopes: ["user.read"],
    account: account,
  };

  publicClientApplication
    .acquireTokenSilent(accessTokenRequest)
    .then(function (accessTokenResponse) {
      // Acquire token silent success
      // Call API with token
      let accessToken = accessTokenResponse.accessToken;
      // Call your API with token
      callApi(accessToken);
    })
    .catch(function (error) {
      //Acquire token silent failure, and send an interactive request
      console.log(error);
      if (error instanceof InteractionRequiredAuthError) {
        publicClientApplication.acquireTokenRedirect(accessTokenRequest);
      }
    });
}

JavaScript (MSAL.js v1)

Il modello seguente è come descritto in precedenza, ma illustrato con un metodo di reindirizzamento per acquisire i token in modo interattivo. È necessario registrare il callback di reindirizzamento come indicato in precedenza.

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

userAgentApplication.handleRedirectCallback(authCallback);

const accessTokenRequest: AuthenticationParameters = {
  scopes: ["user.read"],
};

userAgentApplication
  .acquireTokenSilent(accessTokenRequest)
  .then(function (accessTokenResponse) {
    // Acquire token silent success
    // Call API with token
    let accessToken = accessTokenResponse.accessToken;
  })
  .catch(function (error) {
    //Acquire token silent failure, and send an interactive request
    console.log(error);
    if (error.errorMessage.indexOf("interaction_required") !== -1) {
      userAgentApplication.acquireTokenRedirect(accessTokenRequest);
    }
  });

Richiedere attestazioni facoltative

È possibile usare attestazioni facoltative per gli scopi seguenti:

• Includere attestazioni aggiuntive nei token per l'applicazione.
• Modificare il comportamento di determinate attestazioni che Microsoft Entra ID restituisce nei token.
• Aggiungere e accedere ad attestazioni personalizzate per l'applicazione.

Per richiedere attestazioni facoltative in IdToken, è possibile inviare un oggetto attestazioni con stringa al campo claimsRequest della classe AuthenticationParameters.ts.

var claims = {
  optionalClaims: {
    idToken: [
      {
        name: "auth_time",
        essential: true,
      },
    ],
  },
};

var request = {
  scopes: ["user.read"],
  claimsRequest: JSON.stringify(claims),
};

myMSALObj.acquireTokenPopup(request);

Per altre informazioni, vedere Attestazioni facoltative.

Angular (MSAL.js v2)

Questo codice è identico a quello descritto in precedenza, ma è consigliabile eseguire il bootstrap di MsalRedirectComponent per gestire i reindirizzamenti. Le configurazioni MsalInterceptor possono essere modificate anche per usare i reindirizzamenti.

// In app.module.ts
import { PublicClientApplication, InteractionType } from "@azure/msal-browser";
import {
  MsalInterceptor,
  MsalModule,
  MsalRedirectComponent,
} from "@azure/msal-angular";

@NgModule({
  declarations: [
    // ...
  ],
  imports: [
    // ...
    MsalModule.forRoot(
      new PublicClientApplication({
        auth: {
          clientId: "Enter_the_Application_Id_Here",
        },
        cache: {
          cacheLocation: "localStorage",
          storeAuthStateInCookie: isIE,
        },
      }),
      {
        interactionType: InteractionType.Redirect,
        authRequest: {
          scopes: ["user.read"],
        },
      },
      {
        interactionType: InteractionType.Redirect,
        protectedResourceMap: new Map([
          ["https://graph.microsoft.com/v1.0/me", ["user.read"]],
        ]),
      }
    ),
  ],
  providers: [
    {
      provide: HTTP_INTERCEPTORS,
      useClass: MsalInterceptor,
      multi: true,
    },
  ],
  bootstrap: [AppComponent, MsalRedirectComponent],
})
export class AppModule {}

Angular (MSAL.js v1)

Questo codice è identico a quello descritto in precedenza.

React

Se acquireTokenSilent ha esito negativo, eseguire il fallback in acquireTokenRedirect. Questo metodo avvia un reindirizzamento full-frame e la risposta verrà gestita quando si torna all'applicazione. Quando il rendering di questo componente viene eseguito dopo la restituzione dal reindirizzamento, acquireTokenSilent avrà esito positivo perché i token verranno estratti dalla cache.

import {
  InteractionRequiredAuthError,
  InteractionStatus,
} from "@azure/msal-browser";
import { AuthenticatedTemplate, useMsal } from "@azure/msal-react";

function ProtectedComponent() {
  const { instance, inProgress, accounts } = useMsal();
  const [apiData, setApiData] = useState(null);

  useEffect(() => {
    const accessTokenRequest = {
      scopes: ["user.read"],
      account: accounts[0],
    };
    if (!apiData && inProgress === InteractionStatus.None) {
      instance
        .acquireTokenSilent(accessTokenRequest)
        .then((accessTokenResponse) => {
          // Acquire token silent success
          let accessToken = accessTokenResponse.accessToken;
          // Call your API with token
          callApi(accessToken).then((response) => {
            setApiData(response);
          });
        })
        .catch((error) => {
          if (error instanceof InteractionRequiredAuthError) {
            instance.acquireTokenRedirect(accessTokenRequest);
          }
          console.log(error);
        });
    }
  }, [instance, accounts, inProgress, apiData]);

  return <p>Return your protected content here: {apiData}</p>;
}

function App() {
  return (
    <AuthenticatedTemplate>
      <ProtectedComponent />
    </AuthenticatedTemplate>
  );
}

In alternativa, se è necessario acquisire un token all'esterno di un componente React, è possibile chiamare acquireTokenSilent ma senza eseguire il fallback all'interazione in caso di errore. Tutte le interazioni devono essere eseguite sotto il componente MsalProvider nell'albero dei componenti.

// MSAL.js v2 exposes several account APIs, logic to determine which account to use is the responsibility of the developer
const account = publicClientApplication.getAllAccounts()[0];

const accessTokenRequest = {
  scopes: ["user.read"],
  account: account,
};

// Use the same publicClientApplication instance provided to MsalProvider
publicClientApplication
  .acquireTokenSilent(accessTokenRequest)
  .then(function (accessTokenResponse) {
    // Acquire token silent success
    let accessToken = accessTokenResponse.accessToken;
    // Call your API with token
    callApi(accessToken);
  })
  .catch(function (error) {
    //Acquire token silent failure
    console.log(error);
  });

Passaggi successivi

Passare all'articolo successivo in questo scenario: Chiamare un'API Web.