Обзор рекомендаций по аутентификации рабочей нагрузки в Microsoft Fabric

В этой статье содержатся рекомендации по работе с проверкой подлинности при создании рабочих нагрузок Microsoft Fabric. В ней содержатся сведения о работе с токенами и согласиями.

Прежде чем начать, убедитесь, что вы знакомы с концепциями в обзоре аутентификации и настройках аутентификации.

API плоскости данных и плоскости управления

API плоскости данных — это API, предоставляемые серверной частью рабочей нагрузки. Фронтенд рабочей нагрузки может вызывать их напрямую. Для API плоскости данных серверная часть рабочей нагрузки может сама определять, какие API предоставлять.
API плоскости управления — это API, проходящие через Fabric. Процесс начинается с того, что интерфейсный компонент рабочей нагрузки вызывает API JavaScript, и заканчивается тем, что Fabric вызывает серверный компонент рабочей нагрузки. Примером такого API является создание элемента.

Для API управляющей плоскости нагрузка должна следовать контрактам, определённым в бэкенде рабочей нагрузки, и реализовывать эти API.

Отобразить вкладку API в приложении рабочей нагрузки в Microsoft Entra ID

На вкладке Expose a API нужно добавить области для API управляющей плоскости и области для API плоскостей данных:

Области видимости, добавленные для API плоскости управления, должны предварительно авторизовать приложение Fabric Client for Workloads с идентификатором приложения d2450708-699c-41e3-8077-b0c8341509aa. Эти области содержатся в токене, который серверная часть рабочей нагрузки получает, когда Fabric вызывает её.

Чтобы поток работал, необходимо добавить хотя бы одну область действия для API плоскости управления.
Области видимости, добавленные для API плоскости данных, должны предварительно авторизовывать Microsoft Power BI с идентификатором приложения 871c010f-5e61-4fb1-83ac-98610a7e9110. Они содержатся в токене, который возвращает API JavaScript acquireAccessToken.

Для API уровня данных на этой вкладке можно управлять детальными разрешениями для каждого API, который предоставляет ваша рабочая нагрузка. В идеале вам следует добавить набор разрешений для каждого API, который раскрывает серверная часть рабочей нагрузки, и проверить, что полученный токен включает эти разрешения, когда эти API вызываются с клиента. Например:
- Рабочая нагрузка открывает два API для клиента, ReadData и WriteData.
- Нагрузка предоставляет две области плоскости данных: data.read и data.write.
- В API ReadData рабочий процесс проверяет, что область действия data.read присутствует в токене, прежде чем продолжить выполнение процесса. То же самое относится к WriteData.

вкладка разрешений API в приложении рабочей нагрузки в Microsoft Entra ID

На вкладке Разрешения API необходимо добавить все области действия, которые требуются вашей рабочей нагрузке для получения токена. Обязательной областью для добавления является Fabric.Extend в службе Power BI. Запросы к Fabric могли бы провалиться без этого прицела.

Работа с токенами и согласиями

При работе с API уровня данных внешнему интерфейсу рабочей нагрузки необходимо получить токен для вызовов к серверной части рабочей нагрузки.

В следующих разделах описывается, как внешний интерфейс рабочей нагрузки должен использовать JavaScript API и потоки "от имени" (OBO), чтобы получать токены для рабочей нагрузки и внешних сервисов, а также работать с согласиями.

Шаг 1. Получение токена

Рабочая нагрузка начинается с запроса токена с использованием JavaScript API без предоставления параметров. Этот вызов может иметь два возможных сценария:

Пользователь видит окно согласия, в котором перечислены все статические разрешения (то, что настроено на вкладке Разрешения API), которые настроены для рабочей нагрузки. Этот сценарий происходит, если пользователь не является частью домашнего клиента приложения, и пользователь не предоставил согласие Microsoft Graph для этого приложения раньше.
Пользователь не видит окно согласия. Этот сценарий происходит, если пользователь уже предоставил согласие на использование Microsoft Graph по крайней мере один раз для этого приложения, или если пользователь является частью домашнего арендатора приложения.

В обоих сценариях рабочая нагрузка не должна принимать во внимание, дал ли пользователь полное согласие для всех зависимостей (и не может знать это на данном этапе). Полученный токен имеет аудиторию серверной части рабочей нагрузки и может использоваться для прямого вызова серверной части рабочей нагрузки из фронтенда рабочей нагрузки.

Шаг 2. Попробуйте получить доступ к внешним службам

Для рабочей нагрузки может потребоваться доступ к службам, которым требуется проверка подлинности. Чтобы получить такой доступ, необходимо выполнить поток OBO, в рамках которого токен, полученный от клиента или от Fabric, обменивается на токен для другого сервиса. Обмен токена может завершиться сбоем из-за отсутствия согласия или из-за политики Условный доступ Microsoft Entra, настроенной для ресурса, для которого рабочая нагрузка пытается обменять этот токен.

Чтобы решить эту проблему, при использовании прямых вызовов между фронтендом и бэкендом приложение должно возвращать ошибку клиенту. Также в обязанности рабочей нагрузки входит передавать ошибку клиенту при работе с вызовами от Fabric, используя механизм передачи ошибок, описанный в Workload communication.

После распространения ошибки рабочая нагрузка может вызвать API JavaScript acquireAccessToken для решения проблемы с политикой согласия или условного доступа и повторить операцию.

Сведения об ошибках API уровня данных см. в разделе Обработка многофакторной аутентификации, условного доступа и добавочного согласия. При сбоях API уровня управления см. Взаимодействие рабочих нагрузок.

Примеры сценариев

Рассмотрим рабочую нагрузку, необходимую для доступа к трем API Fabric:

Список рабочих пространств: GET https://api.fabric.microsoft.com/v1/workspaces
Создайте склад: POST https://api.fabric.microsoft.com/v1/workspaces/{workspaceId}/warehouses
Записать в файл в Lakehouse: PUT https://onelake.dfs.fabric.microsoft.com/{filePath}?resource=file

Чтобы работать с этими API, бэкэнд нагрузки должен обмениваться токенами для следующих областей:

Для перечисления рабочих областей: https://analysis.windows.net/powerbi/api/Workspace.Read.All или https://analysis.windows.net/powerbi/api/Workspace.ReadWrite.All
Для создания склада: https://analysis.windows.net/powerbi/api/Warehouse.ReadWrite.All или https://analysis.windows.net/powerbi/api/Item.ReadWrite.All
Для записи в файл Lakehouse: https://storage.azure.com/user_impersonation

Примечание

Необходимые для каждого API Fabric области действия можно найти в этой справочной статье.

Области, упомянутые ранее, необходимо настроить в приложении рабочей нагрузки в соответствии с разрешениями API .

Рассмотрим примеры сценариев, с которыми может столкнуться рабочая нагрузка.

Пример 1

Предположим, что серверная часть рабочей нагрузки имеет API уровня данных, который получает рабочие области пользователя и возвращает их клиенту:

Фронтенд рабочей нагрузки запрашивает токен с помощью JavaScript API.
Интерфейс workload запрашивает API серверной части workload, чтобы получить рабочие области пользователя, и передаёт токен в запросе.
Бэкэнд рабочей нагрузки проверяет токен и пытается обменять его на необходимую область действия (скажем https://analysis.windows.net/powerbi/api/Workspace.Read.All).
Рабочая нагрузка не смогла обменять токен для указанного ресурса, так как пользователь не дал приложению согласия на доступ к этому ресурсу (см. коды ошибок AADSTS).
Серверная часть системы управления нагрузкой передает ошибку пользовательскому интерфейсу, сообщив, что необходимо согласие для этого ресурса. Фронтенд рабочей нагрузки вызывает acquireAccessToken JavaScript API и предоставляетadditionalScopesToConsent:

workloadClient.auth.acquireAccessToken({additionalScopesToConsent: ["https://analysis.windows.net/powerbi/api/Workspace.Read.All"]})

Кроме того, рабочая нагрузка может принять решение о предоставлении согласия для всех статических зависимостей, настроенных в приложении, поэтому он вызывает API JavaScript и предоставляет promptFullConsent:

workloadClient.auth.acquireAccessToken({promptFullConsent: true}).

Этот вызов запрашивает окно согласия независимо от того, предоставил ли пользователь согласие на некоторые зависимости. После этого интерфейс управления рабочей нагрузкой может повторить операцию.

Примечание

Если обмен маркерами по-прежнему завершается ошибкой согласия, это означает, что пользователь не предоставил согласие. Рабочая нагрузка должна обрабатывать такие сценарии; Например, уведомите пользователя о том, что этот API требует согласия и не будет работать без него.

Пример 2

Предположим, что бэкенд рабочей нагрузки должен получить доступ к OneLake через API Create Item (вызов из Fabric рабочей нагрузки):

Фронтенд рабочей нагрузки вызывает Create Item JavaScript API.
Серверная часть рабочей нагрузки получает вызов из Fabric, извлекает делегированный токен и проверяет его.
Рабочая нагрузка пытается обменять токен на https://storage.azure.com/user_impersonation, но это не удаётся, поскольку для доступа к служба хранилища Azure требуется многофакторная аутентификация, настроенная администратором клиента для пользователя (см. коды ошибок AADSTS).
Рабочая нагрузка передаёт клиенту ошибку вместе с утверждениями, которые Microsoft Entra ID возвращает в сообщении об ошибке, с использованием механизма распространения ошибок, описанного в разделе Обмен данными с рабочей нагрузкой.
Интерфейсная часть рабочей нагрузки вызывает API JavaScript acquireAccessToken и передаёт утверждения в виде claimsForConditionalAccessPolicy, где claims обозначает утверждения, передаваемые из серверной части рабочей нагрузки:

workloadClient.auth.acquireAccessToken({claimsForConditionalAccessPolicy: claims})

После этого рабочая нагрузка может повторить операцию.

Обработка ошибок при запросе согласия

Иногда пользователь не может предоставить согласие из-за различных ошибок. После запроса согласия ответ возвращается на URI перенаправления. В нашем примере этот код отвечает за обработку ответа. (Его можно найти в файле index.ts.)

const redirectUriPath = '/close'; 
const url = new URL(window.location.href); 
if (url.pathname?.startsWith(redirectUriPath)) { 
    // Handle errors, Please refer to https://learn.microsoft.com/entra/identity-platform/reference-error-codes 
    if (url?.hash?.includes("error")) { 
        // Handle missing service principal error 
        if (url.hash.includes("AADSTS650052")) { 
            printFormattedAADErrorMessage(url?.hash); 
        // handle user declined the consent error 
        } else  if (url.hash.includes("AADSTS65004")) { 
            printFormattedAADErrorMessage(url?.hash); 
        } 
    } 
    // Always close the window  
    window.close(); 
}

Интерфейс рабочей нагрузки может извлечь код ошибки из URL-адреса и обрабатывать его соответствующим образом.

Примечание

В обоих сценариях (в случае ошибки и успешного выполнения) процесс должен всегда немедленно закрывать окно, без какой-либо задержки.

Обратная связь

Были ли сведения на этой странице полезными?

Last updated on 2026-08-30

Обзор рекомендаций по аутентификации рабочей нагрузки в Microsoft Fabric

API плоскости данных и плоскости управления

Отобразить вкладку API в приложении рабочей нагрузки в Microsoft Entra ID

вкладка разрешений API в приложении рабочей нагрузки в Microsoft Entra ID

Работа с токенами и согласиями

Шаг 1. Получение токена

Шаг 2. Попробуйте получить доступ к внешним службам

Примеры сценариев

Пример 1

Пример 2

Обработка ошибок при запросе согласия

Обратная связь

Дополнительные ресурсы