シングルページアプリケーション：API を呼び出すトークンを取得する

[アーティクル]
10/25/2023

MSAL.js を使用して API 用のトークンを取得するパターンは、acquireTokenSilent メソッドを使用してサイレントトークン要求を最初に試行することです。このメソッドが呼び出されると、ライブラリでは、まずブラウザーストレージ内のキャッシュを調べて、期限切れでないアクセストークンが存在するかどうかを確認し、それを返します。アクセストークンが見つからないか、見つかったアクセストークンの有効期限が切れている場合は、その更新トークンを使用して新しいアクセストークンを取得しようとします。更新トークンの 24 時間の有効期間も期限切れになった場合、MSAL.js は非表示の iframe を開き、Microsoft Entra ID との既存のアクティブなセッション (存在する場合) を利用して新しい認可コードをサイレントに要求します。その後、これは新しいトークンセット (アクセスおよび更新トークン) と交換されます。シングルサインオン (SSO) セッションおよび Microsoft Entra ID 内のトークン有効期間値の詳細については、トークンの有効期間に関するページを参照してください。 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 ラッパーを使用すると、自動的にアクセストークンをサイレントに取得して API への HTTP 要求にそれを添付する HTTP インターセプターが提供されます。

API のスコープは、protectedResourceMap 構成オプションで指定できます。 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();
  }
}

あるいは、コア MSAL.js ライブラリ内に記述されているように、取得トークンメソッドを使用してトークンを明示的に取得することができます。

MSAL Angular ラッパーを使用すると、自動的にアクセストークンをサイレントに取得して API への HTTP 要求にそれを添付する HTTP インターセプターが提供されます。 API のスコープは、protectedResourceMap 構成オプションで指定できます。 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();
   }
 }

あるいは、コア 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 で省略可能な要求を要請するには、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 を呼び出すトークンを取得する

ポップアップ エクスペリエンスか、リダイレクト エクスペリエンスを選択

ポップアップ ウィンドウを使用してトークンを取得する

リダイレクトを使用してトークンを取得する

次のステップ

その他のリソース

シングルページアプリケーション：API を呼び出すトークンを取得する

ポップアップエクスペリエンスか、リダイレクトエクスペリエンスを選択

ポップアップウィンドウを使用してトークンを取得する