通过 Power BI 工作区集合进行身份验证和授权Authenticating and authorizing with Power BI Workspace Collections

Power BI 工作区集合使用密钥应用令牌进行身份验证和授权,而不是使用显式的最终用户身份验证。Power BI Workspace Collections use Keys and App Tokens for authentication and authorization, instead of explicit end-user authentication. 在此模型中,由应用程序管理对最终用户的身份验证和授权。In this model, your application manages authentication and authorization for your end users. 如有必要,应用将创建并发送应用令牌,以指示服务来呈现所请求的报表。When necessary, your app creates and sends the app tokens that tell our service to render the requested report. 此设计不要求应用使用 Azure Active Directory 进行用户身份验证和授权,但仍然可以这样做。This design doesn't require your app to use Azure Active Directory for user authentication and authorization, although you still can.

Important

Power BI 工作区集合已弃用,到 2018 年 6 月 或合同指示时可用。Power BI Workspace Collections is deprecated and is available until June 2018 or when your contract indicates. 建议你规划到 Power BI Embedded 的迁移以避免应用程序中断。You are encouraged to plan your migration to Power BI Embedded to avoid interruption in your application. 有关如何将数据迁移到 Power BI Embedded 的信息,请参阅如何将 Power BI 工作区集合内容迁移到 Power BI EmbeddedFor information on how to migrate your data to Power BI Embedded, see How to migrate Power BI Workspace Collections content to Power BI Embedded.

进行身份验证的两种方式Two ways to authenticate

密钥 - 对于所有 Power BI 工作区集合 REST API 调用,可以使用密钥。Key - You can use keys for all Power BI Workspace Collections REST API calls. Azure 门户中,可以通过依次选择“所有设置”和“访问密钥”来找到密钥。The keys can be found in the Azure portal by selecting All settings and then Access keys. 请始终像对待密码一样对待密钥。Always treat your key as if it is a password. 这些密钥有权在特定的工作区集合上执行任何 REST API 调用。These keys have permissions to make any REST API call on a particular workspace collection.

若要在 REST 调用中使用密钥,请添加以下授权标头:To use a key on a REST call, add the following authorization header:

Authorization: AppKey {your key}

应用令牌 - 应用令牌用于所有嵌入请求。App token - App tokens are used for all embedding requests. 它们被设计为运行客户端,令牌限用于单个报表,并且最好设置一个过期时间。They’re designed to be run client-side.The token is restricted to a single report and its best practice to set an expiration time.

应用令牌是由某个密钥签名的 JWT(JSON Web 令牌)。App tokens are a JWT (JSON Web Token) that is signed by one of your keys.

应用令牌可以包含下列声明:Your app token can contain the following claims:

声明Claim 说明Description
verver 应用令牌的版本。The version of the app token. 当前版本为 0.2.0。0.2.0 is the current version.
audaud 令牌的目标接收方。The intended recipient of the token. 对于 Power BI 工作区集合,请使用:https://analysis.chinacloudapi.cn/powerbi/apiFor Power BI Workspace Collections use: https://analysis.chinacloudapi.cn/powerbi/api
ississ 一个字符串,指示颁发了令牌的应用程序。A string indicating the application that issued the token.
类型type 要创建的应用令牌的类型。The type of app token that is being created. 当前唯一支持的类型是 embedCurrent the only supported type is embed.
wcnwcn 要为其颁发令牌的工作区集合名称。Workspace collection name the token is being issued for.
widwid 要为其颁发令牌的工作区 ID。Workspace ID the token is being issued for.
ridrid 要为其颁发令牌的报表 ID。Report ID the token is being issued for.
username(可选)username (optional) 与 RLS 一起使用,username 是一个字符串,可以在应用 RLS 规则时帮助标识用户。Used with RLS, username is a string that can help identify the user when applying RLS rules.
roles(可选)roles (optional) 一个字符串,包含当应用行级别安全性规则时可选择的角色。A string containing the roles to select when applying Row Level Security rules. 如果传递多个角色,则应当以字符串数组形式传递它们。If passing more than one role, they should be passed as a sting array.
scp(可选)scp (optional) 一个字符串,包含权限范围。A string containing the permissions scopes. 如果传递多个角色,则应当以字符串数组形式传递它们。If passing more than one role, they should be passed as a sting array.
exp(可选)exp (optional) 指示令牌将过期的时间。Indicates the time in which the token expires. 值应当作为 Unix 时间戳传入。The value should be passed in as Unix timestamps.
nbf(可选)nbf (optional) 指示令牌开始生效的时间。Indicates the time in which the token starts being valid. 值应当作为 Unix 时间戳传入。The value should be passed in as Unix timestamps.

示例应用令牌如下所示:A sample app token looks like:

eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJ2ZXIiOiIwLjIuMCIsInR5cGUiOiJlbWJlZCIsIndjbiI6Ikd1eUluQUN1YmUiLCJ3aWQiOiJkNGZlMWViMS0yNzEwLTRhNDctODQ3Yy0xNzZhOTU0NWRhZDgiLCJyaWQiOiIyNWMwZDQwYi1kZTY1LTQxZDItOTMyYy0wZjE2ODc2ZTNiOWQiLCJzY3AiOiJSZXBvcnQuUmVhZCIsImlzcyI6IlBvd2VyQklTREsiLCJhdWQiOiJodHRwczovL2FuYWx5c2lzLndpbmRvd3MubmV0L3Bvd2VyYmkvYXBpIiwiZXhwIjoxNDg4NTAyNDM2LCJuYmYiOjE0ODg0OTg4MzZ9.v1znUaXMrD1AdMz6YjywhJQGY7MWjdCR3SmUSwWwIiI

当解码后,它如下所示:When decoded, it looks something like:

Header

{
    typ: "JWT",
    alg: "HS256:
}

Body

{
  "ver": "0.2.0",
  "wcn": "SupportDemo",
  "wid": "ca675b19-6c3c-4003-8808-1c7ddc6bd809",
  "rid": "96241f0f-abae-4ea9-a065-93b428eddb17",
  "iss": "PowerBISDK",
  "aud": "https://analysis.chinacloudapi.cn/powerbi/api",
  "exp": 1360047056,
  "nbf": 1360043456
}

SDK 中提供了可以更轻松地创建应用令牌的方法。There are methods available within the SDKs that make creation of app tokens easier. 例如,对于 .NET,可以查看 Microsoft.PowerBI.Security.PowerBIToken 类和 CreateReportEmbedToken 方法。For example, for .NET you can look at the Microsoft.PowerBI.Security.PowerBIToken class and the CreateReportEmbedToken methods.

对于 .NET SDK,可以参考 ScopesFor the .NET SDK, you can refer to Scopes.

作用域Scopes

使用 Embed 令牌时,对于允许对其进行访问的资源,你可能希望限制其使用。When using Embed tokens, you may want to restrict usage of the resources you give access to. 为此,可以生成一个包含带作用域的权限的令牌。For this reason, you can generate a token with scoped permissions.

下面是针对 Power BI 工作区集合的可用作用域。The following are the available scopes for Power BI Workspace Collections.

作用域Scope 说明Description
Dataset.ReadDataset.Read 提供对指定数据集进行读取的权限。Provides permission to read the specified dataset.
Dataset.WriteDataset.Write 提供向指定数据集进行写入的权限。Provides permission to write to the specified dataset.
Dataset.ReadWriteDataset.ReadWrite 提供对指定数据集进行读取以及向其进行写入的权限。Provides permission to read and write to the specified dataset.
Report.ReadReport.Read 提供对指定报表进行查看的权限。Provides permission to view the specified report.
Report.ReadWriteReport.ReadWrite 提供对指定报表进行查看和编辑的权限。Provides permission to view and edit the specified report.
Workspace.Report.CreateWorkspace.Report.Create 提供在指定工作区中创建新报表的权限。Provides permission to create a new report within the specified workspace.
Workspace.Report.CopyWorkspace.Report.Copy 提供对指定工作区内的现有报表进行克隆的权限。Provides permission to clone an existing report within the specified workspace.

可以通过在作用域之间使用空格来提供多个作用域,如下所示。You can supply multiple scopes by using a space between the scopes like the following.

string scopes = "Dataset.Read Workspace.Report.Create";

必需的声明 - 作用域Required claims - scopes

scp: {scopesClaim} scopesClaim 可以是一个字符串或字符串数组,指明允许对工作区资源(报表、数据集,等等)具有的权限。scp: {scopesClaim} scopesClaim can be either a string or array of strings, noting the allowed permissions to workspace resources (Report, Dataset, etc.)

已定义了作用域的已解码令牌将类似于以下内容:A decoded token, with scopes defined, would look similar to:

Header

{
    typ: "JWT",
    alg: "HS256:
}

Body

{
  "ver": "0.2.0",
  "wcn": "SupportDemo",
  "wid": "ca675b19-6c3c-4003-8808-1c7ddc6bd809",
  "rid": "96241f0f-abae-4ea9-a065-93b428eddb17",
  "scp": "Report.Read",
  "iss": "PowerBISDK",
  "aud": "https://analysis.chinacloudapi.cn/powerbi/api",
  "exp": 1360047056,
  "nbf": 1360043456
}

操作和作用域Operations and scopes

操作Operation 目标资源Target resource 令牌权限Token permissions
基于数据集创建(在内存中)新报表。Create (in-memory) a new report based on a dataset. 数据集Dataset Dataset.ReadDataset.Read
基于数据集创建(在内存中)新报表并保存该报表。Create (in-memory) a new report based on a dataset and save the report. 数据集Dataset * Dataset.Read* Dataset.Read
* Workspace.Report.Create* Workspace.Report.Create
查看和浏览/编辑(在内存中)现有报表。View and explore/edit (in-memory) an existing report. Report.Read implies Dataset.Read.Report.Read implies Dataset.Read. Report.Read 不允许保存编辑的内容。Report.Read does not allow saving of edits. 报表Report Report.ReadReport.Read
编辑和保存现有报表。Edit and save an existing report. 报表Report Report.ReadWriteReport.ReadWrite
保存报表的副本(另存为)。Save a copy of a report (Save As). 报表Report * Report.Read* Report.Read
* Workspace.Report.Copy* Workspace.Report.Copy

下面是流的工作原理Here's how the flow works

  1. 将 API 密钥复制到应用程序中。Copy the API keys to your application. 可以在 Azure 门户中获取密钥。You can get the keys in Azure portal.

    在 Azure 门户中可以在哪里找到 API 密钥

  2. 令牌将发布声明,并且有过期时间。Token asserts a claim and has an expiration time.

    应用令牌流 - 令牌断言声明

  3. 令牌使用 API 访问密钥获得签名。Token gets signed with an API access keys.

    应用令牌流 - 对令牌进行签名

  4. 用户请求查看报表。User requests to view a report.

    应用令牌流 - 用户请求查看报表

  5. 使用 API 访问密钥验证令牌。Token is validated with an API access keys.

    应用令牌流 - 对令牌进行验证

  6. Power BI 工作区集合将报表发送给用户。Power BI Workspace Collections sends a report to user.

    应用令牌流 - 服务将报表发送给用户

Power BI 工作区集合将报表发送给用户后,用户可以在自定义应用中查看报表。After Power BI Workspace Collections sends a report to the user, the user can view the report in your custom app. 例如,如果导入了分析销售数据 PBIX 示例,该示例 Web 应用将如下所示:For example, if you imported the Analyzing Sales Data PBIX sample, the sample web app would look like:

应用中嵌入的报表的示例

另请参阅See Also

CreateReportEmbedTokenCreateReportEmbedToken
Power BI 工作区集合入门示例Get started with Power BI Workspace Collections sample
常见 Power BI 工作区集合方案Common Power BI Workspace Collections scenarios
Power BI 工作区集合入门Get started with Power BI Workspace Collections
PowerBI-CSharp Git 存储库PowerBI-CSharp Git Repo

有更多问题?More questions? 试用 Power BI 社区Try the Power BI Community