單頁應用程式：取得令牌以呼叫 API

發行項
03/14/2024

使用 MSAL.js 取得 API 令牌的模式，是先使用 acquireTokenSilent 方法嘗試無訊息令牌要求。呼叫此方法時，連結庫會先檢查瀏覽器記憶體中的快取，以查看是否有未過期的存取令牌存在並傳回它。如果找不到存取令牌或找到的存取令牌已過期，則會嘗試使用其重新整理令牌來取得新的存取令牌。如果重新整理令牌的 24 小時存留期也已過期，MSAL.js會開啟隱藏的 iframe，以使用現有的使用中會話搭配 Microsoft Entra ID（如果有的話），以無訊息方式要求新的授權碼，然後交換一組新的令牌（存取和重新整理令牌）。如需 Microsoft Entra ID 中單一登錄（SSO）工作階段和令牌存留期值的詳細資訊，請參閱令牌存留期。如需MSAL.js快取查閱原則的詳細資訊，請參閱：取得存取令牌。

Microsoft Entra ID 的無訊息令牌要求可能會因為密碼變更或更新的條件式存取原則等原因而失敗。更常發生失敗的原因是重新整理令牌的 24 小時存留期到期，以及瀏覽器封鎖第三方 Cookie，這可防止使用隱藏的 iframe 繼續驗證使用者。在這些情況下，您應該叫用其中一個互動式方法（可能會提示使用者）取得令牌：

彈出視窗，使用acquireTokenPopup
使用重新導向acquireTokenRedirect

選擇快顯或重新導向體驗

快顯或重新導向體驗之間的選擇取決於您的應用程式流程：

如果您不希望使用者在驗證期間離開主應用程式頁面，建議您使用快顯方法。因為驗證重新導向會在彈出視窗中發生，因此會保留主要應用程式的狀態。
如果使用者有停用彈出視窗的瀏覽器條件約束或原則，您可以使用重新導向方法。使用重新導向方法搭配 Internet Explorer 瀏覽器，因為 Internet Explorer 上的彈出視窗有已知問題。

您可以在建置存取令牌要求時，設定要包含存取令牌的 API 範圍。所有要求的範圍可能不會在存取令牌中授與。這取決於使用者的同意。

使用彈出視窗取得令牌

下列程式代碼結合先前所述的模式與快顯體驗的方法：

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

下列程式代碼結合先前所述的模式與快顯體驗的方法：

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

MSAL Angular 包裝函式會提供 HTTP 攔截器，其會自動以無訊息方式取得存取令牌，並將其附加至 API 的 HTTP 要求。

您可以在組態選項中 protectedResourceMap 指定 API 的範圍。 MsalInterceptor 自動取得令牌時，會要求指定的範圍。

// 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 會提供您可以訂閱的事件。請務必記得取消訂閱。

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

或者，您可以使用 acquire-token 方法來明確取得令牌，如核心MSAL.js連結庫中所述。

MSAL Angular 包裝函式會提供 HTTP 攔截器，其會自動以無訊息方式取得存取令牌，並將其附加至 API 的 HTTP 要求。您可以在組態選項中 protectedResourceMap 指定 API 的範圍。 MsalInterceptor 自動取得令牌時，會要求指定的範圍。

// 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 會提供您可以訂閱的回呼。請務必記得取消訂閱。

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

或者，您可以使用 acquire-token 方法來明確取得令牌，如核心MSAL.js連結庫中所述。

下列程式代碼結合先前所述的模式與快顯體驗的方法：

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

或者，如果您需要取得 React 元件外部的令牌，您可以呼叫 acquireTokenSilent ，但如果失敗，就不應該回復為互動。所有互動都應該在元件樹狀結構中的 MsalProvider 元件底下進行。

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

使用重新導向取得令牌

下列模式如先前所述，但以重新導向方法來以互動方式取得令牌。您必須在頁面載入時呼叫和等候 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);
      }
    });
}

下列模式如先前所述，但以重新導向方法來以互動方式取得令牌。您必須如先前所述註冊重新導向回呼。

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

要求選擇性宣告

您可以針對下列用途使用選擇性宣告：

在應用程式的令牌中包含額外的宣告。
變更 Microsoft Entra ID 在令牌中傳回之特定宣告的行為。
新增和存取應用程式的自訂宣告。

若要在中 IdToken要求選擇性宣告，您可以將字串化的宣告對象傳送至 claimsRequest 類別的 AuthenticationParameters.ts 欄位。

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

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

myMSALObj.acquireTokenPopup(request);

若要深入瞭解，請參閱選擇性宣告。

此程式代碼與先前所述相同，但我們建議啟動載入 MsalRedirectComponent 以處理重新導向。 MsalInterceptor 設定也可以變更為使用重新導向。

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

如果 acquireTokenSilent 失敗，則後援至 acquireTokenRedirect。這個方法會起始完整畫面重新導向，而當返回應用程式時，將會處理回應。從重新導向傳回之後轉譯此元件時， acquireTokenSilent 現在應該會成功，因為令牌將會從快取提取。

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

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

下一步

請移至此案例中的下一篇文章，呼叫 Web API。

Share via

單頁應用程式：取得令牌以呼叫 API

選擇快顯或重新導向體驗

使用彈出視窗取得令牌

使用重新導向取得令牌

要求選擇性宣告

下一步

其他資源