Общие сведения о рекомендациях по проверке подлинности рабочей нагрузки в Microsoft Fabric

Статья
12/15/2024

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

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

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

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

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

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

На вкладке Открытие 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 уровня данных фронтенд рабочей нагрузки должен получить токен для вызовов бэкенда рабочей нагрузки.

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

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

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

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

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

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

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

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

После распространения ошибки рабочая нагрузка может вызвать 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

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

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

Фронтенд рабочей нагрузки вызывает 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-адреса и обрабатывать его соответствующим образом.

Примечание.

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

Поделиться через

Общие сведения о рекомендациях по проверке подлинности рабочей нагрузки в Microsoft Fabric

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

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

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

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

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

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

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

Пример 1

Пример 2

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

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

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