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.

Veri düzlemi ve kontrol düzlemi API'leri

  • 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. Veri düzlemi API'leri için, iş yükü arka ucu hangi API'lerin sunulacağına karar verebilir.

  • Denetim düzlemi API'leri Fabric üzerinden geçen API'lerdir. İşlem, iş yükü ön ucunun JavaScript API’si'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:

  • Kontrol düzlemi API'leri için eklenen kapsamların, uygulama kimliği d2450708-699c-41e3-8077-b0c8341509aa olan Fabric Client for Workloads uygulamasını önceden yetkilendirmesi gerekir. Bu kapsamlar, Fabric çağrısı yaptığında iş yükü arka uçunun aldığı tokena dahil edilir.

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

  • Veri düzlemi API'leri için eklenen kapsamlar, uygulama kimliği 871c010f-5e61-4fb1-83ac-98610a7e9110ile Microsoft Power BI önceden yetkilendirmelidir. Bunlar, acquireAccessToken JavaScript API’si'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. Örneğin:

    • İş yükü istemciye iki API sunar: ReadData ve WriteData.
    • İş yükü, data.read ve data.write olmak üzere iki veri düzlemi kapsamını kullanıma sunar.
    • 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.

Tokenlar ve onaylarla çalışma

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.

Aşağıdaki bölümler, iş yükü ön yüzünün iş yükü ve harici hizmetler için belirteç almak ve onaylarla çalışmak amacıyla JavaScript API’si ile adına (OBO) akışlarını nasıl kullanması gerektiğini açıklar.

1. Adım: Jeton alma

İş yükü, herhangi bir parametre sağlamadan JavaScript API’si'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). Alınan token, iş yükü arka uç kitlesine sahiptir ve iş yükünün ön uçundan doğrudan iş yükü arka uçunu çağırmak için kullanılabilir.

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

İş yükünün kimlik doğrulaması gerektiren hizmetlere erişmesi gerekebilir. Bu erişim için, müşterisinden veya Fabric'ten aldığı tokenı başka bir servise takas ederek OBO akışını gerçekleştirmesi gerekir. Token değişimi, onay eksikliği veya iş yükünün token takas etmeye çalıştığı kaynağa yapılandırılmış bir Microsoft Entra Koşullu Erişim politikası nedeniyle başarısız olabilir.

Bu sorunu çözmek için, ön uç ile arka uç arasında doğrudan çağrılar yapılırken hatayı istemciye iletmek iş yükünün sorumluluğudur. 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’si'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

  • Bir depo oluşturun: POST https://api.fabric.microsoft.com/v1/workspaces/{workspaceId}/warehouses

  • Bir göl evi dosyasına yazın: PUT https://onelake.dfs.fabric.microsoft.com/{filePath}?resource=file

Bu API'lerle çalışabilmesi için, iş yükü arka uçunun aşağıdaki kapsamlar için token değiştirmesi gerekir:

  • Ç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
  • Lakehouse dosyasına yazmak için: https://storage.azure.com/user_impersonation

Note

Her Fabric API için gereken kapsamları bu referans makalesinde bulabilirsiniz.

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.

Örnek 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’si'sini kullanarak bir belirteç ister.

  2. İş yükü ön sendi, kullanıcının çalışma alanlarını almak için iş yükü arka uç API'sini çağırır ve tokenı isteğe ekler.

  3. İş yükü arka ucu, belirteci doğrular ve bunu gerekli kapsamla takas etmeye çalışır (diyelim ki 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. İş yükü ön yüzü JavaScript API’si'sini acquireAccessToken çağırır ve şunları sağlaradditionalScopesToConsent:

    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’si'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. Ardından, iş yükü ön ucu işlemi yeniden deneyebilir.

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.

Örnek 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’si'sini çağırır.

  2. İş yükü arka uçu, Fabric'ten bir çağrı alır ve delege edilen tokenı çıkarır ve doğrular.

  3. İş yükü, belirteci https://storage.azure.com/user_impersonation ile değiştirmeyi dener, ancak Azure Depolama’a erişmek için kiracı yöneticisinin kullanıcı tarafından yapılandırılmış çok faktörlü kimlik doğrulaması gerektirmesi nedeniyle başarısız olur (AADSTS hata kodları).

  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. İş yükü ön ucu, acquireAccessToken JavaScript API’si’sini çağırır ve claim’leri claims olarak sağlar; burada claimsForConditionalAccessPolicy, iş yükü arka ucundan aktarılan claim’leri ifade eder:

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

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

Rıza talep ederken hataların ele alınması

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.

  • Son güncelleştirme: