Jednostráková aplikace: Získání tokenu pro volání rozhraní API

platí pro: nájemci zaměstnaneckých prostor externí nájemci (další informace)

Vzor pro získání tokenů pro rozhraní API s MSAL.js spočívá v prvním pokusu o požadavek na bezobslužný token pomocí acquireTokenSilent metody. Při zavolání této metody knihovna nejprve zkontroluje mezipaměť v úložišti prohlížeče a zjistí, jestli neexistuje přístupový token, jehož platnost nevypršela, a vrátí ho. Pokud se nenajde žádný přístupový token nebo platnost nalezeného přístupového tokenu vypršela, pokusí se použít obnovovací token k získání nového přístupového tokenu. Pokud vypršela platnost 24hodinové životnosti obnovovacího tokenu, MSAL.js otevře skrytý iframe, aby tiše požádal o nový autorizační kód pomocí existující aktivní relace s Microsoft Entra ID (pokud existuje), který pak bude vyměněn za novou sadu tokenů (přístupové a obnovovací tokeny).

Další informace o relacích jednotného přihlašování (SSO) a hodnotách životnosti tokenů v Microsoft Entra ID najdete v tématu Životnost tokenů. Další informace o zásadách vyhledávání v mezipaměti MSAL.js najdete v tématu: Získání přístupového tokenu.

Žádosti o bezobslužný token na ID Microsoft Entra můžou selhat z důvodů, jako je změna hesla nebo aktualizace zásad podmíněného přístupu. Častěji jsou selhání způsobená vypršením 24hodinové doby platnosti obnovovacího tokenu a prohlížečem blokujícím soubory cookie třetích stran, což brání použití skrytých elementů iframe k pokračování v ověřování uživatele. V těchto případech byste měli vyvolat jednu z interaktivních metod (která může uživatele vyzvat) k získání tokenů:

• Automaticky otevírané okno pomocí acquireTokenPopup
• Přesměrovat pomocí acquireTokenRedirect

Volba mezi vyskakovacími okny nebo přesměrováním

Volba mezi automaticky otevírané okno nebo prostředím pro přesměrování závisí na toku aplikace:

• Pokud nechcete, aby se uživatelé během ověřování přesouvají z hlavní stránky aplikace, doporučujeme automaticky otevíranou metodu. Vzhledem k tomu, že přesměrování ověřování probíhá v automaticky otevíraném okně, zachová se stav hlavní aplikace.
• Pokud mají uživatelé omezení prohlížeče nebo zásady, ve kterých jsou automaticky otevíraná okna zakázaná, můžete použít metodu přesměrování. Použijte metodu přesměrování v prohlížeči Internet Explorer, protože existují známé problémy s automaticky otevíranými okny v Internet Exploreru.

Můžete nastavit obory rozhraní API, které chcete, aby přístupový token zahrnoval při vytváření žádosti o přístupový token. V přístupovém tokenu nemusí být uděleny všechny požadované obory. To závisí na souhlasu uživatele.

Získání tokenu s vyskakovacím oknem

Reagovat

Následující kód kombinuje dříve popsaný vzor s metodami pro automaticky otevírané prostředí:

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

Případně pokud potřebujete získat token mimo komponentu React, můžete volat acquireTokenSilent , ale pokud selže, neměli byste se k interakci vrátit. Všechny interakce by se měly provádět pod komponentou MsalProvider ve stromu komponent.

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

JavaScript (MSAL.js)

Následující kód kombinuje dříve popsaný vzor s metodami pro automaticky otevírané prostředí:

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

Angular (MSAL.js)

Obálka MSAL Angular poskytuje průsečík HTTP, který automaticky získá přístupové tokeny bezobslužně a připojí je k požadavkům HTTP na rozhraní API.

Obory pro rozhraní API můžete zadat v protectedResourceMap možnosti konfigurace. MsalInterceptor požaduje zadané obory při automatickém získávání 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 {}

V případě úspěchu a selhání získání tichého tokenu poskytuje MSAL Angular události, ke kterým se můžete přihlásit. Je také důležité si pamatovat, že se odhlásíte.

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

Alternativně můžete tokeny explicitně získat pomocí metod získání tokenu, jak je popsáno v základní knihovně MSAL.js.

Získání tokenu s přesměrováním

Reagovat

Pokud acquireTokenSilent selže, přejděte zpět na acquireTokenRedirect. Tato metoda zahájí úplné přesměrování a odpověď bude zpracována při návratu do aplikace. Když se tato komponenta vykreslí po návratu z přesměrování, acquireTokenSilent by nyní měl uspět, protože tokeny se načítají z mezipaměti.

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

Případně pokud potřebujete získat token mimo komponentu React, můžete volat acquireTokenSilent , ale pokud selže, neměli byste se k interakci vrátit. Všechny interakce by se měly provádět pod komponentou MsalProvider ve stromu komponent.

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

JavaScript (MSAL.js)

Následující vzor je, jak bylo popsáno výše, ale je zobrazen s použitím metody přesměrování pro interaktivní získání tokenů. Při načítání stránky je potřeba zavolat a čekat na handleRedirectPromise.

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

Vyžádání volitelných údajů

Volitelné nároky můžete použít pro následující účely:

• Zahrňte do tokenů pro vaši aplikaci další tvrzení.
• Změňte chování určitých deklarací identity, které microsoft Entra ID vrací v tokenech.
• Přidejte a přistupujte k vlastním tvrzením ve vaší aplikaci.

Chcete-li požádat o volitelné nároky v IdToken, můžete odeslat objekt nároků ve formě řetězce do pole claimsRequest ve třídě AuthenticationParameters.ts.

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

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

myMSALObj.acquireTokenPopup(request);

Další informace najdete v tématu Volitelné nároky.

Angular (MSAL.js)

Tento kód je stejný jako výše popsaný, s výjimkou toho, že doporučujeme spustit metodu MsalRedirectComponent pro zpracování přesměrování. MsalInterceptor Konfigurace lze také změnit tak, aby používaly přesměrování.

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

Další krok

• Volání webového API