單一頁面應用程式：取得權杖以呼叫 API

發行項
06/27/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();
  }
}

此外，您可以使用 core 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();
   }
 }

此外，您可以使用 core 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 中要求選擇性的宣告，您可以將 stringified 宣告物件傳送至 AuthenticationParameters.ts 類別的欄位 claimsRequest。

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。

共用方式為

單一頁面應用程式：取得權杖以呼叫 API

選擇快顯或重新導向體驗

使用快顯視窗取得權杖

使用重新導向取得權杖

要求選擇性宣告

下一步

意見反應

其他資源