認証 Javascript API (プレビュー)

  • [アーティクル]

Fabric フロントエンドには、Microsoft Entra ID でアプリケーションのトークンを取得するための Fabric ワークロード用 Javascript API が用意されています。 この記事では、この API について説明します。

API

acquireAccessToken(params: AcquireAccessTokenParams): Promise<AccessToken>;  
export interface AcquireAccessTokenParams {
    additionalScopesToConsent?: string[];  
    claimsForConditionalAccessPolicy?: string;  
}

API は、トークン自体とトークンの有効期限を含む AccessToken オブジェクトを返します。

フロントエンド サンプルで API を呼び出すには、サンプル項目を作成し、下にスクロールして [認証ページに移動] を選択します。 そこから、[アクセス トークンの取得] を選択すると、トークンが返されます。

同意

同意が必要な理由を理解するには、「Microsoft Entra ID のユーザーと管理者の同意」を参照してください。

Note

CRUD/ジョブが機能し、テナント間でトークンを取得するには、同意が必要です。

Fabric ワークロードでの同意のしくみ

特定のアプリケーションに同意を与えるために、Fabric FE はワークロードのアプリケーション ID で構成された MSAL インスタンスを作成し、指定されたスコープのトークンを要求します (additionalScopesToConsent - AcquireAccessTokenParams を参照)。

特定のスコープのワークロード アプリケーションでトークンを要求すると、Microsoft Entra ID は、存在しない場合にポップアップの同意を表示し、ポップアップ ウィンドウをアプリケーションで構成されたリダイレクト URI にリダイレクトします。

通常、リダイレクト URI はトークンを要求したページと同じ領域にあり、ページがポップアップにアクセスして閉じることができるようにします。

ここでは、Fabric がトークンを要求しており、ワークロードのリダイレクト URI が Fabric の領域にないため、同じドメインではありません。 そのため、同意ダイアログが開いたら、リダイレクト後に手動で閉じる必要があります。 redirectUri で返されるコードは使用しません。そのため、自動的に閉じるだけです (Microsoft Entra ID がポップアップをリダイレクト URI にリダイレクトすると、ポップアップは単に閉じられます)。

リダイレクト URI のコード/構成は、index.ts ファイルで確認できます。

認証のセットアップを行うときに構成したアプリ "マイ ワークロード アプリ" とその依存関係 (ストレージと Power BI) の同意ポップアップの例を次に示します。

アクセス許可が必要なダイアログのスクリーンショット。

AcquireAccessTokenParams について説明するときに、同意を設定する方法について説明します。

ホーム テナントで同意を付与する別の方法 (オプション)

アプリケーションのホーム テナントで同意を得るには、テナント管理者に、次の形式の URL を使用してテナント全体の同意を付与するように依頼できます (独自のテナント ID とクライアント ID を挿入します)。

https://login.microsoftonline.com/{tenantId}/adminconsent?client_id={clientId}

AcquireAccessTokenParams

acquireAccessToken JS API を呼び出すときは、次の 2 つのパラメーターを指定できます。

  • additionalScopesToConsent: 再同意シナリオなど、同意を求めるその他のスコープ。
  • claimsForConditionalAccessPolicy: OBO フローが失敗した場合に Microsoft Entra ID から返される要求。たとえば、OBO には多要素認証が必要です。

これら 2 つのパラメーターを確認し、acquireAccessToken を呼び出すときに何を提供するかを確認してみましょう。

additionalScopesToConsent

次のシナリオで acquireAccessToken を呼び出すときに、additionalScopesToConsent で提供する内容を次に示します:

シナリオ 1: バックエンド ワークロードを呼び出すトークンの取得: AdditionalScopesToConsent が null です。

バックエンド ワークロードを呼び出すトークンを取得する場合は、任意の additionalScopesToConsent を指定せずに acquireAccessToken を呼び出します。

  • ユーザーがアプリケーションのホーム テナントにいる場合、ワークロードは同意を与えずにトークンを取得できます。

  • ユーザーが別のテナントにいる場合は、ワークロードがトークンを受け取る前に、同意を付与する (またはテナント管理者にアプリに同意してもらう) 必要があります。

シナリオ 2: Crud/Jobs JS API が失敗する: AdditionalScopesToConsent がデフォルトです。

これらの操作が失敗した場合、ワークロードは 、additionalScopesToConsent として ['.default'] を持つトークンを要求する必要があります。 これは、アプリケーションの依存関係の同意をトリガーします(当社のアプリの構成された API アクセス許可。詳細については「認証設定」を参照してください)。

シナリオ 3。 特定のスコープの OBO フローが、同意が必要なエラーで失敗する: AdditionalScopesToConsent は 'https://analysis.windows.net/powerbi/api/Workspace.Read.All` です

同意が必要なエラーのスクリーンショット。

ワークロード バックエンドの OBO フローが特定のスコープに対して同意が必要なエラーで失敗した場合、ワークロード バックエンドは、それらのスコープで acquireAccessToken API を呼び出すようにフロントエンドに通知する必要があります。

claimsForConditionalAccessPolicy

このパラメーターは、テナントで構成されている条件付きアクセス ポリシーが原因で、ワークロード BE で OBO エラーが発生した場合に使用されます。

OBO は、"要求"と呼ばれる文字列を返す条件付きアクセス ポリシーのために失敗します。この文字列は、FE がトークンを要求し、要求を claimsForConditionalAccessPolicy として渡すワークロード FE に送信する必要があります。 詳細については、「多要素認証 (MFA)、条件付きアクセス、増分同意の設定方法」を参照してください。

同意がないか条件付きアクセス ポリシーがないために OBO 操作が失敗した場合の応答の例については、BE サンプルの AuthenticationService AddBearerClaimToResponse の使用方法を参照してください。