Toepassing met één pagina: een token verkrijgen om een API aan te roepen

Het patroon voor het verkrijgen van tokens voor API's met MSAL.js is om eerst een stille tokenaanvraag te proberen met behulp van de acquireTokenSilent methode. Wanneer deze methode wordt aangeroepen, controleert de bibliotheek eerst de cache in de browseropslag om te zien of er een niet-verlopen toegangstoken bestaat en retourneert deze. Als er geen toegangstoken is gevonden of het gevonden toegangstoken is verlopen, wordt geprobeerd het vernieuwingstoken te gebruiken om een nieuw toegangstoken op te halen. Als de levensduur van het vernieuwingstoken van 24 uur ook is verlopen, opent MSAL.js een verborgen iframe om op de achtergrond een nieuwe autorisatiecode aan te vragen met behulp van de bestaande actieve sessie met Microsoft Entra-id (indien van toepassing), die vervolgens wordt uitgewisseld voor een nieuwe set tokens (toegangs- en vernieuwingstokens). Zie Levensduur van token voor meer informatie over eenmalige aanmeldingssessie en levensduurwaarden voor tokens in Microsoft Entra ID. Zie voor meer informatie over MSAL.js cachezoekbeleid: Een toegangstoken verkrijgen.

De stille tokenaanvragen voor Microsoft Entra-id kunnen mislukken vanwege redenen als een wachtwoordwijziging of bijgewerkte beleidsregels voor voorwaardelijke toegang. Vaker worden fouten veroorzaakt door het verlopen van de levensduur van het vernieuwingstoken van 24 uur en de browser blokkeert cookies van derden, waardoor het gebruik van verborgen iframes wordt voorkomen om de gebruiker te blijven verifiëren. In deze gevallen moet u een van de interactieve methoden aanroepen (waardoor de gebruiker mogelijk wordt gevraagd) om tokens te verkrijgen:

• Pop-upvenster met behulp van acquireTokenPopup
• Omleiden met behulp van acquireTokenRedirect

Kiezen tussen een pop-up- of omleidingservaring

De keuze tussen een pop-up- of omleidingservaring is afhankelijk van uw toepassingsstroom:

• Als u niet wilt dat gebruikers tijdens de verificatie van uw hoofdtoepassingspagina weggaan, raden we de pop-upmethode aan. Omdat de verificatieomleiding plaatsvindt in een pop-upvenster, blijft de status van de hoofdtoepassing behouden.

• Als gebruikers browserbeperkingen of beleidsregels hebben waarbij pop-upvensters zijn uitgeschakeld, kunt u de omleidingsmethode gebruiken. Gebruik de omleidingsmethode met de browser Internet Explorer, omdat er bekende problemen zijn met pop-upvensters in Internet Explorer.

U kunt de API-bereiken instellen die u wilt opnemen in het toegangstoken wanneer de aanvraag voor het toegangstoken wordt gebouwd. Alle aangevraagde bereiken worden mogelijk niet verleend in het toegangstoken. Dat hangt af van de toestemming van de gebruiker.

Een token verkrijgen met een pop-upvenster

JavaScript (MSAL.js v2)

De volgende code combineert het eerder beschreven patroon met de methoden voor een pop-upervaring:

// 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)

De volgende code combineert het eerder beschreven patroon met de methoden voor een pop-upervaring:

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)

De MSAL Angular-wrapper biedt de HTTP-interceptor, die automatisch toegangstokens op de achtergrond verkrijgt en deze koppelt aan de HTTP-aanvragen voor API's.

U kunt de bereiken voor API's opgeven in de protectedResourceMap configuratieoptie. MsalInterceptor vraagt de opgegeven bereiken aan bij het automatisch verkrijgen van tokens.

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

MsAL Angular biedt gebeurtenissen waarop u zich kunt abonneren voor succes en falen van de stille tokenverwerving. Het is ook belangrijk om u af te melden.

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();
  }
}

U kunt ook expliciet tokens verkrijgen met behulp van de methoden acquire-token, zoals beschreven in de kernbibliotheek MSAL.js.

Angular (MSAL.js v1)

De MSAL Angular-wrapper biedt de HTTP-interceptor, die automatisch toegangstokens op de achtergrond verkrijgt en deze koppelt aan de HTTP-aanvragen voor API's. U kunt de bereiken voor API's opgeven in de protectedResourceMap configuratieoptie. MsalInterceptor vraagt de opgegeven bereiken aan bij het automatisch verkrijgen van tokens.

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

MsAL Angular biedt callbacks waarop u zich kunt abonneren voor succes en falen van de stille tokenverwerving. Het is ook belangrijk om u af te melden.

// 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();
   }
 }

U kunt ook expliciet tokens verkrijgen met behulp van de methoden acquire-token, zoals beschreven in de kernbibliotheek MSAL.js.

React

De volgende code combineert het eerder beschreven patroon met de methoden voor een pop-upervaring:

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>
  );
}

Als u een token buiten een React-onderdeel moet verkrijgen, kunt u ook bellen acquireTokenSilent , maar moet u niet terugvallen op interactie als dit mislukt. Alle interacties moeten plaatsvinden onder het onderdeel in de MsalProvider onderdeelstructuur.

// 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);
  });

Een token verkrijgen met een omleiding

JavaScript (MSAL.js v2)

Het volgende patroon is zoals eerder beschreven, maar wordt weergegeven met een omleidingsmethode om tokens interactief te verkrijgen. U moet bellen en wachten handleRedirectPromise bij het laden van de 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)

Het volgende patroon is zoals eerder beschreven, maar wordt weergegeven met een omleidingsmethode om tokens interactief te verkrijgen. U moet de omleidingsaanroep registreren zoals eerder vermeld.

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);
    }
  });

Optionele claims aanvragen

U kunt optionele claims gebruiken voor de volgende doeleinden:

• Voeg extra claims toe aan tokens voor uw toepassing.
• Wijzig het gedrag van bepaalde claims die microsoft Entra-id retourneert in tokens.
• Aangepaste claims voor uw toepassing toevoegen en openen.

Als u optionele claims IdTokenwilt aanvragen, kunt u een tekenreeksclaimobject verzenden naar het claimsRequest veld van de AuthenticationParameters.ts klasse.

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

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

myMSALObj.acquireTokenPopup(request);

Zie Optionele claims voor meer informatie.

Angular (MSAL.js v2)

Deze code is hetzelfde als eerder beschreven, maar we raden u aan om MsalRedirectComponent omleidingen te verwerken. MsalInterceptor configuraties kunnen ook worden gewijzigd om omleidingen te gebruiken.

// 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)

Deze code is hetzelfde als eerder beschreven.

React

Als acquireTokenSilent dit mislukt, moet u terugvallen op acquireTokenRedirect. Met deze methode wordt een volledige frame-omleiding gestart en wordt het antwoord verwerkt wanneer u terugkeert naar de toepassing. Wanneer dit onderdeel wordt weergegeven nadat deze is geretourneerd vanuit de omleiding, moet het nu lukken omdat acquireTokenSilent de tokens worden opgehaald uit de 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>
  );
}

Als u een token buiten een React-onderdeel moet verkrijgen, kunt u ook bellen acquireTokenSilent , maar moet u niet terugvallen op interactie als dit mislukt. Alle interacties moeten plaatsvinden onder het onderdeel in de MsalProvider onderdeelstructuur.

// 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);
  });

Volgende stappen

Ga verder met het volgende artikel in dit scenario: Een web-API aanroepen.