共用方式為

使用服務主體和應用程式祕密內嵌 Power BI 內容

  • 發行項

服務主體是一種驗證方法，可用來讓 Microsoft Entra 應用程式存取 Power BI 服務內容和 API。

在建立 Microsoft Entra 應用程式時，會建立服務主體物件。 服務主體物件 (也稱為「服務主體」) 可讓 AMicrosoft Entra ID 驗證您的應用程式。 經過驗證後，應用程式就可以存取 Microsoft Entra 租用戶資源。

為了進行驗證，服務主體會使用 Microsoft Entra 應用程式的「應用程式識別碼」，以及下列其中一項：

  • 憑證
  • 應用程式祕密

本文說明如何使用「應用程式識別碼」和「應用程式祕密」來進行服務主體驗證。

注意

建議您使用憑證來保護您的後端服務，而不是使用祕密金鑰。

方法

若要使用服務主體和應用程式識別碼來進行內嵌式分析，請採取下列步驟。 後續各節會詳細說明這些步驟。

  1. 建立 Microsoft Entra 應用程式。

    1. 為您的 Microsoft Entra 應用程式建立秘密。
    2. 取得應用程式的「應用程式識別碼」和「應用程式祕密」。

    注意

    步驟 1中描述這些步驟。 如需如何建立 Microsoft Entra 應用程式的詳細資訊，請參閱建立 Microsoft Entra 應用程式 (部分機器翻譯)。

  2. 建立 Microsoft Entra 安全性群組。

  3. 啟用 Power BI 服務系統管理員設定。

  4. 將服務主體新增至您的工作區。

  5. 內嵌內容。

重要

在為服務主體建立 Microsoft Entra 應用程式時，您不需要在 Azure 入口網站中設定任何委派權限或應用程式權限。 當您為服務主體建立 Microsoft Entra 應用程式以存取 Power BI REST API 時，建議您避免新增權限。 您永遠不會使用這些權限，這些權限反而可能會導致難以疑難排解的錯誤。

步驟 1 - 建立 Microsoft Entra 應用程式

使用下列其中一種方法建立 Microsoft Entra 應用程式：

在 Azure 入口網站中建立 Microsoft Entra 應用程式

  1. 登入 Azure 入口網站。

  2. 搜尋並選取 [應用程式註冊]。

    Azure 入口網站的螢幕擷取畫面，搜尋方塊中已有「應用程式註冊」。醒目提示該方塊和應用程式註冊圖示。

  3. 選取新增註冊。

    Azure 入口網站中 [應用程式註冊] 頁面的螢幕擷取畫面。醒目提示 [新增註冊]。

  4. 填寫必要資訊：

    • 名稱 - 輸入應用程式的名稱。
    • 支援的帳戶類型 - 選取支援的帳戶類型。
    • (選擇性) 重新導向 URI - 必要時輸入 URI。

  5. 選取註冊。

  6. 註冊應用程式之後，即可從 [概觀] 索引標籤取得 [應用程式識別碼]。複製並儲存「應用程式識別碼」以供稍後使用。

    新應用程式 [概觀] 頁面的螢幕擷取畫面。應用程式識別碼難以辨識，並已醒目提示。

  7. 選取 [憑證和秘密]。

    新應用程式 [概觀] 頁面的螢幕擷取畫面。在瀏覽窗格中，已醒目提示 [憑證和秘密]。

  8. 選取 [新用戶端密碼]。

    此螢幕擷取畫面顯示應用程式的 [憑證和秘密] 頁面一部分。在 [用戶端密碼] 底下，會醒目提示 [新增用戶端密碼] 按鈕。

  9. 在 [新增用戶端密碼] 視窗中，輸入描述，指定您要讓用戶端密碼到期的時間，然後選取 [新增]。

  10. 複製並儲存用戶端密碼值。

    應用程式 [憑證和秘密] 頁面的螢幕擷取畫面。在 [用戶端密碼] 底下，會顯示新的秘密。會醒目提示其難以辨識的值。

    注意

    離開此視窗之後，用戶端密碼值會隱藏，而且您無法再次檢視或複製此值。

使用 PowerShell 建立 Microsoft Entra 應用程式

下列範例 PowerShell 指令碼會建立新的 Microsoft Entra 應用程式和服務主體。 執行此指令碼之前：

指令碼執行之後，請記下指令碼輸出中的下列資訊：

  • 新應用程式的用戶端識別碼
  • 新服務主體的物件識別碼
  • 服務主體秘密的值
# Sign in as a user who's allowed to create an app.
Connect-MgGraph -Scopes "Application.ReadWrite.All" 

# Create a new Azure AD web application.
$web = @{
    RedirectUris = "https://localhost:44322"
    HomePageUrl = "https://localhost:44322"
}
$params = @{
    DisplayName = "myAzureADApp"
    Web = $($web)
}
$app = New-MgApplication @params
Write-Host "Client ID of new app: " $($app.AppId)

# Create a service principal.
$ServicePrincipalID=@{
  "AppId" = $($app.AppId)
  }
$sp = New-MgServicePrincipal -BodyParameter $($ServicePrincipalId)
Write-Host "Object ID of new service principal: " $($sp.Id)

# Create a key for the service principal.
$credential = Add-MgServicePrincipalPassword -ServicePrincipalId $($sp.Id)
Write-Host "Credential of new service principal: " $($credential.SecretText)

步驟 2 - 建立 Microsoft Entra 安全性群組

您的服務主體沒有任何 Power BI 內容和 API 的存取權。 為了向服務主體提供存取權，請在 Microsoft Entra ID 中建立安全性群組。 然後，將您建立的服務主體新增至該安全性群組。

注意

如果您想要為整個組織啟用服務主體存取，請略過此步驟。

有兩種方式可以建立 Microsoft Entra 安全性群組：

手動建立安全性群組

若要手動建立 Azure 安全性群組，請依照建立基本群組並新增成員中的指示進行。

使用 PowerShell 建立安全性群組

下列範例指令碼會建立新的安全性群組。 其也會將您稍早建立的服務主體新增至新的安全性群組。

  • 在執行指令碼之前，請將 <app-client-ID> 取代為您稍早為新應用程式所記錄的用戶端識別碼。
  • 執行指令碼之後，請記下新安全性群組的物件識別碼，此值可於指令碼輸出中找到。
# Sign in as an admin.
Connect-MgGraph -Scopes "Application.ReadWrite.All"

# Get the service principal that you created earlier.
$servicePrincipal = Get-MgServicePrincipal -Filter "AppId eq '<app-client-ID>'"

# Create an Azure AD security group.
$group = New-MgGroup -DisplayName "securitygroup1" -SecurityEnabled -MailEnabled:$False -MailNickName "notSet"
Write-Host "Object ID of new security group: " $($group.Id)

# Add the service principal to the group.
New-MgGroupMember -GroupId $($group.Id) -DirectoryObjectId $($servicePrincipal.Id)

步驟 3 - 啟用 Power BI 服務系統管理員設定

為了讓 Microsoft Entra 應用程式存取 Power BI 內容和 API，Power BI 系統管理員必須啟用下列設定：

  • 在應用程式中內嵌內容
  • 允許服務主體使用 Power BI API

在 Power BI 管理入口網站中，移至 [租用戶設定]，然後向下捲動至 [開發人員設定]。

  • 針對整個組織或針對您在 Microsoft Entra ID 中建立的特定安全性群組，啟用 [在應用程式中內嵌內容]。

    管理入口網站 [租用戶設定] 區段中 [開發人員設定] 的螢幕擷取畫面。[在應用程式中內嵌內容] 的選項會開啟。

  • 針對整個組織或針對您在 Microsoft Entra ID 中建立的特定安全性群組，啟用 [允許服務主體使用 Power BI API]。

    [開發人員設定] 區段的螢幕擷取畫面。針對某個安全性群組開啟了 [允許服務主體使用 Power BI API] 的選項。

    重要

    服務主體可以存取針對其啟用的任何租用戶設定。 根據您的系統管理員設定而定，這包括特定安全性群組或整個組織。

    若要將服務主體存取限制為特定的租用戶設定，僅允許存取特定安全性群組。 或者，您可以為服務主體建立專用的安全性群組，並將其從所需的租用戶設定中排除。

步驟 4 - 將服務主體新增至您的工作區

您的 Microsoft Entra 應用程式只有在可以存取 Power BI 工作區時，才能存取 Power BI 報表、儀表板和語意模型。 您可以藉由將應用程式的服務主體或其安全性群組新增至工作區作為成員或系統管理員，以提供該存取權。

有三種方式可將服務主體或其安全性群組新增至您的工作區：

手動新增服務主體或安全性群組

  1. 在 Power BI 服務中，捲動至您想要為其啟用存取權的工作區。 從 [更多] 功能表中，選取 [工作區存取]。

    顯示工作區已展開 [更多] 功能表的螢幕擷取畫面。在該功能表上，會醒目提示 [工作區存取]。

  2. 在 [存取] 窗格的 [新增系統管理員、成員或參與者] 底下，新增下列其中一項：

    • 服務主體。 服務主體的名稱是 Microsoft Entra 應用程式的顯示名稱，和 Microsoft Entra 應用程式的 [概觀] 索引標籤中所出現的值一樣。
    • 包含服務主體的安全性群組。

  3. 在下拉式功能表上，選取 [成員] 或 [系統管理員]。

  4. 選取 [新增]。

使用 PowerShell 新增服務主體或安全性群組

下列各節會提供將服務主體和安全性群組新增至 Power BI 工作區作為成員的範例 PowerShell 指令碼。

使用 PowerShell 將服務主體新增為工作區成員

下列指令碼會將服務主體新增為工作區成員。 在執行指令碼之前：

  • 將 <service-principal-object-ID> 取代為您稍早為新服務主體所記錄的物件識別碼。
  • 將 <workspace-name> 取代為您想要向服務主體提供其存取權的工作區名稱。
# Sign in to Power BI.
Login-PowerBI

# Set up the service principal ID.
$SPObjectID = "<service-principal-object-ID>"

# Get the workspace.
$pbiWorkspace = Get-PowerBIWorkspace -Filter "name eq '<workspace-name>'"

# Add the service principal to the workspace.
Add-PowerBIWorkspaceUser -Id $($pbiWorkspace.Id) -AccessRight Member -PrincipalType App -Identifier $($SPObjectID)

使用 PowerShell 將安全性群組新增為工作區成員

下列指令碼會將安全性群組新增為工作區成員。 在執行指令碼之前：

  • 將 <security-group-object-ID> 取代為您稍早為新安全性群組所記錄的物件識別碼。
  • 將 <workspace-name> 取代為您想要向安全性群組提供其存取權的工作區名稱。
# Sign in to Power BI.
Login-PowerBI

# Set up the security group object ID.
$SGObjectID = "<security-group-object-ID>"

# Get the workspace.
$pbiWorkspace = Get-PowerBIWorkspace -Filter "name eq '<workspace-name>'"

# Add the security group to the workspace.
Add-PowerBIWorkspaceUser -Id $($pbiWorkspace.Id) -AccessRight Member -PrincipalType Group -Identifier $($SGObjectID)

步驟 5 - 內嵌內容

您可將內容內嵌至範例應用程式或您自己的應用程式。

您的內容內嵌之後，您就可以移至生產環境。

注意

若要使用憑證來保護內容，請遵循使用服務主體和憑證內嵌 Power BI 內容中所述的步驟。

考量與限制

  • 使用服務主體時，不支援 [我的工作區]。
  • 需要容量才能移至實際執行環境。
  • 您無法使用服務主體登入 Power BI 入口網站。
  • 需有 Power BI 管理員權限，才能在 Power BI 管理入口網站的開發人員設定中啟用服務主體。
  • 為組織內嵌應用程式無法使用服務主體。
  • 不支援資料流程管理。
  • 服務主體僅支援一些唯讀系統管理員 API。 若要為唯讀系統管理員 API 啟用服務主體支援，您必須在租用戶中啟用 Power BI 服務系統管理員設定。 如需詳細資訊，請參閱為唯讀系統管理員 API 啟用服務主體驗證 (部分機器翻譯)。
  • 搭配 Azure Analysis Services 資料來源使用服務主體時，服務主體本身必須具有 Azure Analysis Services 執行個體權限。 基於此目的使用包含服務主體的安全性群組將無法正常運作。

相關內容