Ensidesprogram: Hämta en token för att anropa ett API

Mönstret för att hämta token för API:er med MSAL.js är att först försöka med en tyst tokenbegäran med hjälp acquireTokenSilent av metoden. När den här metoden anropas kontrollerar biblioteket först cachen i webbläsarlagringen för att se om det finns en åtkomsttoken som inte har upphört att gälla och returnerar den. Om ingen åtkomsttoken hittas eller om åtkomsttoken har upphört att gälla försöker den använda sin uppdateringstoken för att hämta en ny åtkomsttoken. Om uppdateringstokens livslängd på 24 timmar också har upphört att gälla MSAL.js öppnar en dold iframe för att tyst begära en ny auktoriseringskod med hjälp av den befintliga aktiva sessionen med Microsoft Entra-ID (om någon) som sedan byts ut mot en ny uppsättning token (åtkomst - och uppdateringstoken). Mer information om sessions- och tokenlivsvärden för enkel inloggning (SSO) i Microsoft Entra-ID finns i Tokens livslängd. Mer information om MSAL.js cache-uppslagsprincip finns i: Hämta en åtkomsttoken.

Begäranden om tyst token till Microsoft Entra-ID kan misslyckas av orsaker som lösenordsändring eller uppdaterade principer för villkorsstyrd åtkomst. Oftast beror fel på att uppdateringstokens livslängd på 24 timmar upphör att gälla och webbläsaren blockerar cookies från tredje part, vilket förhindrar att dolda iframes används för att fortsätta autentisera användaren. I dessa fall bör du anropa en av de interaktiva metoderna (som kan uppmana användaren) att hämta token:

• Popup-fönster med hjälp av acquireTokenPopup
• Omdirigering med hjälp av acquireTokenRedirect

Välj mellan en popup- eller omdirigeringsupplevelse

Valet mellan en popup- eller omdirigeringsupplevelse beror på ditt programflöde:

• Om du inte vill att användarna ska flytta från huvudprogramsidan under autentiseringen rekommenderar vi popup-metoden. Eftersom omdirigeringen av autentisering sker i ett popup-fönster bevaras huvudprogrammets tillstånd.

• Om användarna har webbläsarbegränsningar eller principer där popup-fönster är inaktiverade kan du använda omdirigeringsmetoden. Använd omdirigeringsmetoden med Webbläsaren Internet Explorer eftersom det finns kända problem med popup-fönster i Internet Explorer.

Du kan ange de API-omfång som du vill att åtkomsttoken ska inkludera när den skapar begäran om åtkomsttoken. Alla begärda omfång kanske inte beviljas i åtkomsttoken. Det beror på användarens medgivande.

Hämta en token med ett popup-fönster

JavaScript (MSAL.js v2)

Följande kod kombinerar det tidigare beskrivna mönstret med metoderna för en popup-upplevelse:

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

Följande kod kombinerar det tidigare beskrivna mönstret med metoderna för en popup-upplevelse:

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)

MSAL Angular-omslutningen tillhandahåller HTTP-interceptorn, som automatiskt hämtar åtkomsttoken tyst och kopplar dem till HTTP-begäranden till API:er.

Du kan ange omfången för API:er i konfigurationsalternativet protectedResourceMap . MsalInterceptor begär de angivna omfången när token hämtas automatiskt.

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

För lyckat och misslyckat förvärv av tyst token tillhandahåller MSAL Angular händelser som du kan prenumerera på. Det är också viktigt att komma ihåg att avbryta prenumerationen.

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

Du kan också uttryckligen hämta token med hjälp av metoderna för att hämta token enligt beskrivningen i kärnbiblioteket MSAL.js.

Angular (MSAL.js v1)

MSAL Angular-omslutningen tillhandahåller HTTP-interceptorn, som automatiskt hämtar åtkomsttoken tyst och kopplar dem till HTTP-begäranden till API:er. Du kan ange omfången för API:er i konfigurationsalternativet protectedResourceMap . MsalInterceptor begär de angivna omfången när token hämtas automatiskt.

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

Vid lyckat och misslyckat förvärv av tyst token tillhandahåller MSAL Angular återanrop som du kan prenumerera på. Det är också viktigt att komma ihåg att avbryta prenumerationen.

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

Du kan också uttryckligen hämta token med hjälp av metoderna för att hämta token enligt beskrivningen i kärnbiblioteket MSAL.js.

React

Följande kod kombinerar det tidigare beskrivna mönstret med metoderna för en popup-upplevelse:

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

Om du behöver hämta en token utanför en React-komponent kan du anropa acquireTokenSilent men bör inte återgå till interaktionen om den misslyckas. Alla interaktioner bör ske under komponenten MsalProvider i komponentträdet.

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

Hämta en token med en omdirigering

JavaScript (MSAL.js v2)

Följande mönster beskrivs tidigare men visas med en omdirigeringsmetod för att hämta token interaktivt. Du måste anropa och vänta handleRedirectPromise på sidinläsning.

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)

Följande mönster beskrivs tidigare men visas med en omdirigeringsmetod för att hämta token interaktivt. Du måste registrera återanropet för omdirigering som nämnts tidigare.

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

Begära valfria anspråk

Du kan använda valfria anspråk i följande syften:

• Inkludera extra anspråk i token för ditt program.
• Ändra beteendet för vissa anspråk som Microsoft Entra-ID returnerar i token.
• Lägga till och få åtkomst till anpassade anspråk för ditt program.

Om du vill begära valfria anspråk i IdTokenkan du skicka ett strängifierat anspråksobjekt till claimsRequest klassens AuthenticationParameters.ts fält.

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

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

myMSALObj.acquireTokenPopup(request);

Mer information finns i Valfria anspråk.

Angular (MSAL.js v2)

Den här koden är densamma som tidigare, förutom att vi rekommenderar att du startar MsalRedirectComponent för att hantera omdirigeringar. MsalInterceptor konfigurationer kan också ändras för att använda omdirigeringar.

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

Den här koden är densamma som beskrevs tidigare.

React

Om acquireTokenSilent misslyckas återgår du till acquireTokenRedirect. Den här metoden initierar en fullständig omdirigering och svaret hanteras när du återgår till programmet. När den här komponenten återges efter att ha återvänt från omdirigeringen acquireTokenSilent bör den nu lyckas eftersom token hämtas från cacheminnet.

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

Om du behöver hämta en token utanför en React-komponent kan du anropa acquireTokenSilent men bör inte återgå till interaktionen om den misslyckas. Alla interaktioner bör ske under komponenten MsalProvider i komponentträdet.

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

Nästa steg

Gå vidare till nästa artikel i det här scenariot, Anropa ett webb-API.