Microsoft Fabric'te iş yükü kimlik doğrulaması yönergelerine genel bakış

Bu makalede, Microsoft Fabric iş yüklerini oluştururken kimlik doğrulamasıyla çalışma yönergeleri sağlanır. Belirteçler ve onaylarla çalışma hakkında bilgiler içerir.

Başlamadan önce Kimlik Doğrulamasına genel bakış ve Kimlik Doğrulaması kurulumukavramları hakkında bilgi sahibi olduğunuzdan emin olun.

Data plane and control plane APIs

• Veri düzlemi API'leri, iş yükü arka ucu tarafından kullanıma sunulan API'lerdir. İş yükü ön ucu bunları doğrudan çağırabilir. For data plane APIs, the workload backend can decide on what APIs to expose.

• Denetim düzlemi API'leri Fabric üzerinden geçen API'lerdir. İşlem, iş yükü ön ucunun JavaScript API'sini çağırmasıyla başlar ve Fabric'in iş yükü arka ucunu çağırmasıyla sona erer. Böyle bir API'ye örnek olarak Öğe Oluştur örnek olarak verilmiştir.

  Denetim düzlemi API'leri için iş yükünün iş yükü arka uçta tanımlanan sözleşmeleri izlemesi ve bu API'leri uygulaması gerekir.

Microsoft Entra Id'de iş yükünün uygulamasında api sekmesini kullanıma sunma

Bir API'yi Ortaya Çıkarma sekmesinde, kontrol düzlemi API'leri için kapsamlar ve veri düzlemi API'leri için kapsamlar eklemeniz gerekir:

• The scopes added for control plane APIs should preauthorize the Fabric Client for Workloads application with application ID d2450708-699c-41e3-8077-b0c8341509aa. Those scopes are included in the token that the workload backend receives when Fabric calls it.

  Akışın çalışması için denetim düzlemi API'sine en az bir kapsam eklemeniz gerekir.

• The scopes added for data plane APIs should preauthorize Microsoft Power BI with application ID 871c010f-5e61-4fb1-83ac-98610a7e9110. Bunlar, acquireAccessToken JavaScript API'sinin döndürdüğü belirteçte yer alır.

  Veri düzlemi API'leri için bu sekmeyi kullanarak iş yükünüzün her API'si için ayrıntılı izinleri yönetebilirsiniz. İdeal olarak, iş yükü arka ucu tarafından kullanıma sunulan her API için bir kapsam kümesi eklemeniz ve bu API'ler istemciden çağrıldığında alınan belirtecin bu kapsamları içerdiğini doğrulamanız gerekir. For example:

  • İş yükü istemciye iki API sunar: ReadData ve WriteData.
  • The workload exposes two data plane scopes, data.read and data.write.
  • ReadData API'sinde iş yükü, akışa devam etmeden önce belirteçte data.read kapsamının bulunduğunu doğrular. Aynı durum WriteDataiçin de geçerlidir.

Microsoft Entra Id'de iş yükünün uygulamasında API izinleri sekmesi

API izinleri sekmesinde, iş yükünüzün belirteç değişimi için ihtiyaç duyduğu tüm kapsamları eklemeniz gerekir. Eklenmesi gereken bir zorunlu kapsam, Power BI hizmeti altında Fabric.Extend'dır. Fabric'e yönelik istekler bu kapsam olmadan başarısız olabilir.

Working with tokens and consents

Veri düzlemi API'leriyle çalışırken, iş yükü ön uçunun iş yükü arka ucuna yapılan çağrılar için bir belirteç alması gerekir.

The following sections describe how the workload frontend should use the JavaScript API and on-behalf-of (OBO) flows to acquire tokens for the workload and external services, and to work with consents.

1. Adım: Jeton alma

İş yükü, herhangi bir parametre sağlamadan JavaScript API'sini kullanarak belirteç istemeyle başlar. Bu çağrı iki senaryoya neden olabilir:

• Kullanıcı, iş yükünün yapılandırıldığı tüm statik bağımlılıkları (API izinleri sekmesinde yapılandırılanlar) içeren bir onay penceresi görür. Bu senaryo, kullanıcı uygulamanın ev kiracısının bir parçası değilse ve kullanıcı daha önce bu uygulama için Microsoft Graph'a onay vermemişse gerçekleşir.

• Kullanıcı bir onay penceresi görmez. Bu senaryo, kullanıcı bu uygulama için Microsoft Graph'a en az bir kez onay vermişse veya kullanıcı uygulamanın ev kiracısının bir parçasıysa gerçekleşir.

Her iki senaryoda da iş yükü, kullanıcının tüm bağımlılıklar için tam onay verip vermediğini umursamamalıdır (ve bu noktada bunu bilemez). The received token has the workload backend audience and can be used to directly call the workload backend from the workload frontend.

2. Adım: Dış hizmetlere erişmeyi deneyin

İş yükünün kimlik doğrulaması gerektiren hizmetlere erişmesi gerekebilir. For that access, it needs to perform the OBO flow, where it exchanges the token that it received from its client or from Fabric to another service. The token exchange might fail because of lack of consent or some Microsoft Entra Conditional Access policy that's configured on the resource that the workload is trying to exchange the token for.

To solve this problem, it's the workload's responsibility to propagate the error to the client when working with direct calls between the frontend and the backend. Ayrıca, İş yükü iletişimibölümünde açıklanan hata yayma özelliğini kullanarak Fabric'ten gelen çağrılarla çalışırken hatanın istemciye iletilmesi iş yükünün sorumluluğundadır.

İş yükü hatayı yaydıktan sonra acquireAccessToken JavaScript API'sini çağırarak onay veya Koşullu Erişim ilkesi sorununu çözebilir ve işlemi yeniden deneyebilir.

Veri düzlemi API hataları için bkz. Çok faktörlü kimlik doğrulamasını işleme, Koşullu Erişim ve artımlı onay. Kontrol düzlemi API hataları için bkz. İş yükü iletişimi.

Örnek senaryolar

Haydi üç Fabric API'sine erişmesi gereken bir iş yüküne göz atalım:

• Çalışma alanlarını listeleme: GET https://api.fabric.microsoft.com/v1/workspaces

• Create a warehouse: POST https://api.fabric.microsoft.com/v1/workspaces/{workspaceId}/warehouses

• Write to a lakehouse file: PUT https://onelake.dfs.fabric.microsoft.com/{filePath}?resource=file

To be able to work with those APIs, the workload backend needs to exchange tokens for the following scopes:

• Çalışma alanlarını listelemek için: https://analysis.windows.net/powerbi/api/Workspace.Read.All veya https://analysis.windows.net/powerbi/api/Workspace.ReadWrite.All
• Ambar oluşturmak için: https://analysis.windows.net/powerbi/api/Warehouse.ReadWrite.All veya https://analysis.windows.net/powerbi/api/Item.ReadWrite.All
• For writing to a lakehouse file: https://storage.azure.com/user_impersonation

Note

You can find scopes needed for each Fabric API in this reference article.

Daha önce bahsedilen kapsamlarınAPI izinleri altında iş yükü uygulamasında yapılandırılması gerekir.

Şimdi iş yükünün karşılaşabileceği senaryo örneklerine göz atalım.

Example 1

İş yükü arka ucuna kullanıcının çalışma alanlarını alan ve bunları istemciye döndüren bir veri düzlemi API'si olduğunu varsayalım:

1. İş yükü ön ucu JavaScript API'sini kullanarak bir belirteç ister.

2. The workload frontend calls the workload backend API to get the workspaces of the user and attaches the token in the request.

3. The workload backend validates the token and tries to exchange it for the required scope (let's say https://analysis.windows.net/powerbi/api/Workspace.Read.All).

4. Kullanıcı uygulamanın bu kaynağa erişmesine izin vermediğinden iş yükü belirtilen kaynak için belirteci değiştiremiyor (bkz. AADSTS hata kodları).

5. İş yükü arka ucu, bu kaynak için izin gerektiğini belirterek hatayı iş yükü ön ucuna iletir. The workload frontend calls the acquireAccessToken JavaScript API and provides additionalScopesToConsent:

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

   Alternatif olarak iş yükü, uygulamasında yapılandırılan tüm statik bağımlılıkları için onay istemeye karar verebilir, bu nedenle JavaScript API'sini çağırır ve promptFullConsentsağlar:

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

Bu çağrı, kullanıcının bazı bağımlılıklara onay verip vermediğinden bağımsız olarak bir onay penceresi ister. After that, the workload frontend can retry the operation.

Note

Belirteç değişimi hala bir onay hatasıyla başarısız oluyorsa, kullanıcının onay vermemiş olduğu anlamına gelir. İş yükünün bu tür senaryoları işlemesi gerekir; örneğin, kullanıcıya bu API'nin onay gerektirdiğini ve bu api olmadan çalışmayacağını bildirin.

Example 2

İş yükü arka uç, Öğe Oluşturma API'si aracılığıyla (Fabric'den iş yüküne çağrı) OneLake'e erişmesi gerektiğini varsayalım.

1. İş yükü ön ucu Öğe Oluştur JavaScript API'sini çağırır.

2. The workload backend receives a call from Fabric and extracts the delegated token and validates it.

3. The workload tries to exchange the token for https://storage.azure.com/user_impersonation but fails because the tenant administrator of the user-configured multifactor authentication needed to access Azure Storage (see AADSTS error codes).

4. İş yükü, İş yükü iletişimibölümünde açıklanan hata yayılımını kullanarak Microsoft Entra ID'den istemciye, hatayla döndürülen taleplerle birlikte hatayı iletir.

5. The workload frontend calls the acquireAccessToken JavaScript API and provides claims as claimsForConditionalAccessPolicy, where claims refers to the claims propagated from the workload backend:

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

Bundan sonra iş yükü işlemi yeniden deneyebilir.

Handling errors when requesting consents

Bazen kullanıcı çeşitli hatalar nedeniyle onay veremiyor. Onay isteğinden sonra yanıt yeniden yönlendirme URI'sine döndürülür. Örneğimizde bu kod yanıtı işlemeden sorumludur. (index.ts dosyasında bulabilirsiniz.)

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(); 
} 

İş yükü ön ucu URL'den hata kodunu ayıklayabilir ve uygun şekilde işleyebilir.

Note

Her iki senaryoda da (hata ve başarı), iş yükü her zaman gecikme olmadan pencereyi hemen kapatmalıdır.