Egyoldalas alkalmazás: Jogkivonat beszerzése API meghívásához

Az API-k jogkivonatainak MSAL.js történő beszerzésének mintája az, hogy először megkísérel egy csendes jogkivonat-kérést a acquireTokenSilent metódus használatával. A metódus meghívásakor a kódtár először ellenőrzi a gyorsítótárat a böngészőtárolóban, és ellenőrzi, hogy létezik-e nem lejárt hozzáférési jogkivonat, és visszaadja azt. Ha nem található hozzáférési jogkivonat, vagy a talált hozzáférési jogkivonat lejárt, megpróbálja a frissítési jogkivonatát használni egy új hozzáférési jogkivonat lekéréséhez. Ha a frissítési jogkivonat 24 órás élettartama is lejárt, MSAL.js megnyit egy rejtett iframe-et, amely csendesen kér egy új engedélyezési kódot a meglévő aktív munkamenet és a Microsoft Entra-azonosító használatával (ha van ilyen), amelyet aztán új jogkivonatokra cserél (hozzáférési és frissítési jogkivonatok). Az egyszeri bejelentkezés (SSO) munkamenetéről és a jogkivonat élettartamértékeiről a Microsoft Entra ID-ban további információt a jogkivonat élettartamairól talál. A gyorsítótár-keresési szabályzat MSAL.js további információkért lásd: Hozzáférési jogkivonat beszerzése.

A Microsoft Entra-azonosítóra irányuló csendes jogkivonat-kérések sikertelenek lehetnek olyan okok miatt, mint a jelszó módosítása vagy a frissített feltételes hozzáférési szabályzatok. A hibák leggyakrabban a frissítési jogkivonat 24 órás lejárati idejének és a külső cookie-kat blokkoló böngészőnek köszönhetők, ami megakadályozza a rejtett iframe-ek használatát a felhasználó hitelesítésének folytatásához. Ezekben az esetekben meg kell hívnia az egyik interaktív metódust (amely megkérheti a felhasználót) a jogkivonatok beszerzésére:

• Előugró ablak a következő használatával: acquireTokenPopup
• Átirányítás a következő használatával: acquireTokenRedirect

Választás előugró vagy átirányítási felület között

Az előugró vagy az átirányítási felület közötti választás az alkalmazás folyamatától függ:

• Ha nem szeretné, hogy a felhasználók a hitelesítés során elmozduljanak a fő alkalmazáslapról, javasoljuk az előugró módszert. Mivel a hitelesítési átirányítás egy előugró ablakban történik, a fő alkalmazás állapota megmarad.

• Ha a felhasználók böngészőkorlátokkal vagy szabályzatokkal rendelkeznek, amelyekben az előugró ablakok le vannak tiltva, használhatja az átirányítási módszert. Használja az átirányítási módszert az Internet Explorer böngészővel, mert az Internet Explorer előugró ablakaival kapcsolatban ismert problémák merülnek fel.

Beállíthatja azokat az API-hatóköröket, amelyeket a hozzáférési jogkivonatnak tartalmaznia kell a hozzáférési jogkivonat-kérés létrehozásakor. Előfordulhat, hogy a hozzáférési jogkivonat nem minden kért hatókört ad meg. Ez a felhasználó hozzájárulásától függ.

Jogkivonat beszerzése előugró ablakkal

JavaScript (MSAL.js v2)

A következő kód egyesíti a korábban leírt mintát az előugró felület metódusaival:

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

A következő kód egyesíti a korábban leírt mintát az előugró felület metódusaival:

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)

Az MSAL Angular burkoló biztosítja a HTTP-elfogót, amely automatikusan csendesen szerzi be a hozzáférési jogkivonatokat, és csatolja őket az API-kHOZ tartozó HTTP-kérésekhez.

A konfigurációs beállításban megadhatja az API-k hatóköreit protectedResourceMap . MsalInterceptor a jogkivonatok automatikus beszerzésekor kéri a megadott hatóköröket.

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

A csendes jogkivonat beszerzésének sikeressége és sikertelensége érdekében az MSAL Angular olyan eseményeket biztosít, amelyekre előfizethet. Azt is fontos megjegyezni, hogy leiratkozni.

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

A jogkivonatokat az alapvető MSAL.js kódtárban leírt beolvasási jogkivonat-metódusok használatával is explicit módon szerezheti be.

Angular (MSAL.js v1)

Az MSAL Angular burkoló biztosítja a HTTP-elfogót, amely automatikusan csendesen szerzi be a hozzáférési jogkivonatokat, és csatolja őket az API-kHOZ tartozó HTTP-kérésekhez. A konfigurációs beállításban megadhatja az API-k hatóköreit protectedResourceMap . MsalInterceptor a jogkivonatok automatikus beszerzésekor kéri a megadott hatóköröket.

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

A csendes jogkivonat beszerzésének sikeressége és sikertelensége érdekében az MSAL Angular visszahívásokat biztosít, amelyekre előfizethet. Azt is fontos megjegyezni, hogy leiratkozni.

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

A jogkivonatokat az alapvető MSAL.js kódtárban leírt beolvasási jogkivonat-metódusok használatával is explicit módon szerezheti be.

Reagálás

A következő kód egyesíti a korábban leírt mintát az előugró felület metódusaival:

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

Másik lehetőségként, ha a React-összetevőn kívül kell jogkivonatot beszereznie, de acquireTokenSilent nem szabad visszaesnie az interakcióba, ha az meghiúsul. Az összes interakciónak az MsalProvider összetevő fa alatt kell végbevennie.

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

Jogkivonat beszerzése átirányítással

JavaScript (MSAL.js v2)

Az alábbi minta a korábban ismertetett módon jelenik meg, de átirányítási módszerrel jelenik meg a jogkivonatok interaktív beszerzéséhez. Fel kell hívnia és várnia handleRedirectPromise kell az oldalbetöltésre.

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)

Az alábbi minta a korábban ismertetett módon jelenik meg, de átirányítási módszerrel jelenik meg a jogkivonatok interaktív beszerzéséhez. Regisztrálnia kell az átirányítási visszahívást a korábban említett módon.

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

Nem kötelező jogcímek kérése

A választható jogcímeket a következő célokra használhatja:

• További jogcímek belefoglalása az alkalmazás jogkivonataiba.
• Módosíthatja bizonyos jogcímek viselkedését, amelyeket a Microsoft Entra ID tokenekben ad vissza.
• Hozzáadhat egyéni jogcímeket az alkalmazáshoz, és elérheti őket.

Ha opcionális jogcímeket szeretne kérni, IdTokensztringezett jogcímobjektumot küldhet az claimsRequestAuthenticationParameters.ts osztály mezőjébe.

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

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

myMSALObj.acquireTokenPopup(request);

További információ: Választható jogcímek.

Angular (MSAL.js v2)

Ez a kód megegyezik a korábban ismertetettekkel, de javasoljuk, hogy az átirányítások kezeléséhez indítsa el a MsalRedirectComponent rendszerindítást. MsalInterceptor a konfigurációk is módosíthatók átirányítások használatára.

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

Ez a kód megegyezik a korábban ismertetett kóddal.

Reagálás

Ha acquireTokenSilent nem sikerül, térjen vissza a .-ra acquireTokenRedirect. Ez a metódus teljes keretes átirányítást kezdeményez, és a válasz az alkalmazásba való visszatéréskor lesz kezelve. Ha ez az összetevő az átirányításból való visszatérés után jelenik meg, acquireTokenSilent a jogkivonatok a gyorsítótárból való lekérése után sikeresnek kell lenniük.

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

Másik lehetőségként, ha a React-összetevőn kívül kell jogkivonatot beszereznie, de acquireTokenSilent nem szabad visszaesnie az interakcióba, ha az meghiúsul. Az összes interakciónak az MsalProvider összetevő fa alatt kell végbevennie.

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

Következő lépések

Lépjen tovább a következő cikkre ebben a forgatókönyvben: Webes API meghívása.