Fabric アプリの認証

Fabric Apps には、ユーザーのサインイン、セッションの管理、アプリが行うすべてのデータとストレージ呼び出しに ID をアタッチする組み込みの認証サービスが含まれています。 この記事では、プロジェクトの認証を構成する前に理解しておく必要がある概念について説明します。

実装の詳細については、次を参照してください。

認証モード

デプロイされたFabricアプリはMicrosoft Entra IDで認証されます。 アプリがどこで動作し、誰がEntraトークンを取得しているかに基づいて統合経路を選択してください:

環境 サポートされているメソッド いつ使用するか
Fabricポータルを使ったブラウザアプリ Fabric SSOポップアップまたは埋め込みハンドオフ Fabricにインタラクティブなサインインを行わせるか、Fabric内に埋め込まれたアプリ内でサインインしましょう。
すでに委任された Entra トークンを持つブラウザまたは Node.js アプリ signInWithEntraToken() 提供されたトークンをポップアップやリダイレクトなしでRayfinセッションに交換します。
外部親ポータルに埋め込まれたアプリ createEmbedHost()親で、initEmbeddedAuth()iframeで 信頼できるEntra認証済み親がトークンをiframeに送らずにハンドオフを仲介できるようにします。
ローカルバックエンドによるローカル開発 電子メールとパスワード ローカルバックエンドに対してテストしてください;この方法はデプロイ済みのFabricバックエンドでは機能しません。

主な概念:

  • Fabric SSOはFabricポータルを使ってブラウザユーザーの認証を行います。 アプリは Fabric 内で動作することも、デプロイ済みのバックエンドを対象とするローカルのフロントエンドを含むスタンドアロンページから起動するポップアップを使用することもできます。
  • 直接Entra交換や外部親ホストハンドオフは、任意のアイデンティティ プロバイダーやアプリのみのサービス プリンシパル サインインのサポートではなく、追加のMicrosoft Entraパスです。
  • 電子メールとパスワード は、ローカル開発のみを目的としています。 デプロイ後は機能しません。
  • 初回サインイン時に、ユーザーが作成されます。 Fabric SSO では、個別のサインアップ手順はありません。ユーザーは初めてサインインすると自動的に作成されます。
  • Fabric展開には認証が必要です。 services.auth.enabledを false に設定すると、npx rayfin upが失敗します。

トークン要件および実装例については、Direct Entra token sign-in および Embed in an external parent portal を参照してください。

セッションと ID

ユーザーがサインインすると、SDK はサインインしたユーザーを表す セッション を作成します。 セッションは不透明です。アプリは、基になるトークンを検査しないでください。 代わりに、アプリは大まかなプロパティの小さなセットを読み取ります。

  • セッションが現在認証されているかどうか。
  • ユーザーの id と email。
  • rayfin.ymlで構成したカスタム要求。

ユーザーがサインインするのと同じクライアント インスタンスによって、すべてのデータとストレージ呼び出しに ID が自動的にアタッチされます。 トークンは手動で渡しません。

セッションでは変更イベントも発生するため、ユーザーがページを再読み込みせずにサインインまたはサインアウトしたときに UI が反応できるようにします。

サーバーサイド統合では、ユーザーごとに別個のクライアントと、メモリ専用のAuthセッション(RayfinClient は authStorage: false 上、Auth は { storage: false } 上)を使いましょう。 ユーザー間で可変のサインイン済みのクライアントを共有してはいけません。 リクエストやユーザー固有のスコープが終了したら、認証インスタンスを破棄します。

プロジェクトで認証を有効にする

認証は rayfin/rayfin.ymlで構成されます。 次の例では、Fabric SSO (デプロイされたアプリの場合) と電子メール/パスワード サインイン (ローカル開発用) の両方を有効にします。

services:
  auth:
    enabled: true
    allowedRedirectUris:
      - http://localhost:5173
    fabric:
      enabled: true
      externalEntraExchange: true
    password:
      enabled: true  # Local development only

各設定で制御される内容:

  • services.auth.enabled – 認証サービスをオンにします。 あらゆる Fabric の展開に必要です。
  • allowedRedirectUris – サインイン後のユーザーのリダイレクト先として許可されるオリジン。 ここにローカル開発 URL を追加します。 npx rayfin up は、デプロイされたアプリの配信元を自動的に追加します。
  • fabric.enabled – Fabric SSO を有効にします。 デプロイされたアプリに必要です。
  • fabric.externalEntraExchange – 直接委任されたEntraトークン交換および外部親ホストハンドオフを可能にします。 ターゲットとなる Fabric 環境も交換機能をサポートしている必要があります。
  • password.enabled – ローカル開発用の電子メールとパスワードのサインインを有効にします。

Important

Fabricデプロイでは、認証を有効にする必要があります。 npx rayfin up services.auth.enabledがfalseに設定されている場合は失敗します。

rayfin.ymlを編集した後、ローカル バックエンドを再起動するか、npx rayfin up実行して変更を適用します。

外部で取得した Entra トークンの前提条件

ダイレクトエクスチェンジおよび外部親ホスト認証には、対象展開で受け入れられる Fabric/Power BI オーディエンス用の、アイテムの所有テナントで発行されたItem.Execute.All付きの委託ユーザー トークンが必要です。 また、アプリアイテムに対して 実行 権限も持っている必要があります。 アプリ専用トークンはこれらのサインインパスではサポートされていません。

あなたのアイデンティティライブラリがトークンを取得し、同意を処理します。 Rayfin SDKはそれをRayfinセッションと交換します。Entraトークンは取得しません。 ブラウザの呼び出し元では、オリジンと Authorization ヘッダーを許可するようサービスの CORS ポリシーも設定する必要があります。

カスタム要求

カスタム要求を使用すると、テナント名、機能フラグ、アプリバージョンなど、すべてのセッションにアプリケーション固有のメタデータをアタッチできます。 これらは、データ モデルを変更することなく、ロールベースのアクセス制御や機能の制限に役立ちます。

services:
  auth:
    enabled: true
    customClaims:
      tenant: default
      app_version: 1.0.0

カスタム要求はセッション オブジェクト内に表示され、データアクセス許可ルールから参照できます。

SDK が提供するもの

RayfinClientを使用すると、認証サービスはclient.authで使用できます。 概念レベルでは、次の機能が提供されます。

  • ローカル開発中に電子メールとパスワードを使用してサインアップおよびサインインします。
  • Fabric SSO によるサインインおよびサインアップ(デプロイ済みアプリ向け) 同じ呼び出しで、新規ユーザーと戻りユーザーの両方が処理されます。
  • ブラウザや Node.js コードでの直接委任されたEntraトークン交換、さらに組み込みアプリに対する信頼された外部親ホストのハンドオフも可能です。
  • サインアウトして現在のセッションを終了します。
  • セッションの読み取りとサブスクリプション により、UI がユーザーの認証状態と同期し続けます。

これらの機能を実際のアプリに組み込むコードについては、「FabricアプリのSSO認証Fabric設定」を参照してください。 コールバックおよびハンドオフ許可リストのガイダンスについては 、「認証リダイレクトURIの設定」を参照してください。