設定有效的身分識別

  • 8 分鐘

在產生內嵌權杖時，您可以在使用適用於您的客戶案例時設定有效的身分識別。

您的應用程式邏輯會先建立一或多個 effectiveidentity 物件清單。 每個物件都可以包含下列參數。

  • Datasets： (必要) 數據集標識符清單。

  • Username： (選擇性) 針對內部裝載的模型，它是 或 USERPRINCIPALNAME 函式所傳回的USERNAME文字值。 對於外部裝載的模型，這是連接到模型的使用者名稱。

  • Roles： (選擇性) 角色名稱清單。

  • CustomData： (選用) 函式所傳回的 CUSTOMDATA 文字值。

  • IdentityBlob： (選擇性) Azure AD 存取令牌，用於具有與 Microsoft Azure SQL 資料庫 之 DirectQuery 連線的令牌型身分識別。 這允許您在沒有資料模型 RLS 的情況下強制執行資料存取權限。 本單元稍後將說明本主題。

您可能會傳入數據集清單，因為內嵌令牌將用來內嵌許多連線到不同數據集的 Power BI 成品，或因為儀錶板是由連接到多個數據集的磚所組成。 傳入包含多個角色的清單時，會同時強制執行所有角色，這表示使用者可以檢視角色授與資料的聯集。

下列範例會建立包含一個 effectiveidentity 物件的清單。 它會傳入目前應用程式使用者的使用者名稱、 區域 角色，以及第一個 (，而且可能只) 工作區中找到的數據集：

// Create effective identity for the first dataset
var datasetId = datasets[0].Id.ToString();
var effectiveIdentities = new List<EffectiveIdentity>() {
	new EffectiveIdentity(
		username: userProfile.Username,
		roles: new List<string> {"Region"},
		datasets: new List<string> {datasetId})
};

接下來，若要產生內嵌權杖，應用程式會將清單傳遞至 GenerateTokenRequestV2 方法的 identities 參數。 其他方法會產生內嵌令牌，每個方法都可讓您傳入有效的身分識別清單。

// Bundle token requests for the reports, datasets, and the workspace
var tokenRequest = new GenerateTokenRequestV2(
    reports: reportTokenRequests,
    datasets: datasetTokenRequests,
    targetWorkspaces: workspaceRequests,
    identities: effectiveIdentities
) ;

針對每個 Power BI 資料集類型設定有效身分識別，下列主題提供進一步詳細資料。

為內部裝載的匯入資料表設定有效的身分識別

當您傳遞有效身分識別以連線至具有匯入資料表的內部裝載模型時，請考慮下列參數：

  • 模型中必須至少定義一個角色。

  • 必須傳遞使用者名稱，不過不需要是真正的使用者名稱。 傳入的值是由 或 USERPRINCIPALNAME 函式傳USERNAME回。

  • 有效的身分識別必須至少定義一個角色。

為內部裝載的 DirectQuery 資料表設定有效的身分識別

若要設定內部裝載 DirectQuery 資料表的有效身分識別，您也能針對內部裝載的匯入資料表使用相同指導方針。

此外，您可以使用權杖型身分識別。 權杖型身分識別可讓您使用 Azure AD 存取權杖來指定內嵌權杖的有效身分識別，但只有在來源是 Azure SQL Database 時。 在產生內嵌權杖時，您的應用程式會將存取權杖傳遞至 IdentityBlob 參數。 在此情況下，您不需要將值傳遞至 username 參數。

使用權杖型身分識別需要資料集擁有者設定資料來源，才能使用使用者的 OAuth2 認證。 如此一來，Power BI 會使用有效的身分識別使用者名稱來連線到資料來源。 這表示資料庫可以強制執行 RLS，而不是資料模型。

如需令牌型身分識別的詳細資訊，請參閱 Power BI Embedded 中的安全性功能。

設定 Azure Analysis Services 的有效身分識別

若要在使用 Azure Analysis Services 模型時設定有效的身分識別，您必須確保內嵌身分識別 (服務主體或主要使用者帳戶) 至少具有模型的讀取權限。

當未傳遞有效的身分識別，且內嵌身分識別帳戶是 Analysis Services 系統管理員時，所有應用程式使用者都能檢視所有模型資料。 當內嵌身分識別帳戶不是 Analysis Services 系統管理員時，資料可見度會受限於該帳戶獲指派的角色。

注意

在搭配 Azure Analysis Services 模型使用服務主體時，服務主體本身必須具有 Azure Analysis Services 執行個體權限。 基於此目的使用包含服務主體的安全性群組將無法正常運作。

在傳遞有效的身分識別以使用 Azure Analysis Services 模型時，請考慮下列參數：

  • 模型中必須至少定義一個角色。

  • 使用者名稱必須是主使用者帳戶 (UPN 格式) 或服務主體 (ObjectID)。

  • 當沒有任何角色構成有效身分識別的一部分時，會套用指派給有效身分識別帳戶的角色。

  • 函 USERNAME 式會傳回有效的身分識別用戶名稱。

設定 SQL Server Analysis Services 的有效身分識別

若要在使用 SQL Server Analysis Services 模型時設定有效的身分識別，您必須確保閘道資料來源認證設定為 Analysis Services 系統管理員。

有效的身分識別 (服務主體或主要使用者帳戶) 必須是閘道管理員，或具有閘道資料來源的 ReadOverrideEffectiveIdentity 權限。 您只能使用 Power BI REST API 設定此權限。

當未傳遞有效的身分識別，且內嵌身分識別帳戶是 Analysis Services 系統管理員時，所有使用者都可以檢視所有模型數據。 當內嵌身分識別帳戶不是 Analysis Services 系統管理員時，資料可見度會受限於該帳戶獲指派的角色。

在傳遞有效的身分識別以使用 SQL Server Analysis Services 模型時，請考慮下列參數：

  • 模型中必須至少定義一個角色。

  • 使用者名稱必須是 Windows 帳戶，使用 UPN 或 DOMAIN\username 格式。

  • 使用者名稱必須具有模型的讀取權限。

  • 當沒有任何角色構成有效身分識別的一部分時，會套用指派給有效身分識別使用者名稱的角色。

  • 函 USERNAME 式會傳回有效的身分識別用戶名稱。

  • 不支援使用函 CUSTOMDATA 式。

比較資料集類型

下表比較四種資料集類型的有效識別參數設定。

參數 內部裝載的匯入資料表 內部裝載的 DirectQuery 數據表 Azure Analysis Services SQL Server Analysis Services
使用者名稱 和 USERPRINCIPALNAME 函式將傳USERNAME回的任何文字值 和 USERPRINCIPALNAME 函式將傳USERNAME回的任何文字值 它用來向服務進行驗證。 它必須是主用戶帳戶， (UPN 格式) 或服務主體， (ObjectID) 。 它用來向服務進行驗證。 它必須是 Windows 帳戶，使用 UPN 或 DOMAIN\username 格式。
CustomData 支援 支援 支援 不支援
角色 有效的身分識別必須至少定義一個角色 有效的身分識別必須至少定義一個角色 未傳遞任何角色時，會套用指派給有效身分識別帳戶的角色 未傳遞任何角色時，會套用指派給有效身分識別帳戶的角色
IdentityBlob No 是，當源數據是應強制執行 RLS 需求的 Azure SQL 資料庫 (時) No 否
其他資訊 需要閘道。 有效的身分識別帳戶必須是閘道管理員。