Power BI

Developer in a Day
June 2022 release

© 2022 Microsoft. All rights reserved.

Course aim

• This course aims to empower app developers with the technical

knowledge required to embed Power BI content
• On completion of this course, you will have the skills to:
• Develop with the Power BI REST API
• Embed Power BI content in apps
• Develop intelligent apps using the Power BI JavaScript API
• Enforce row-level security (RLS) for embedded content
• Automate solution management

© 2022 Microsoft. All rights reserved.

Course aim
Prerequisites

• This course has been designed specifically for experienced app

developers
• It is an advantage if you have development experience with:
• .NET
• Visual C#
• HTML
• JavaScript
• Familiarity with Power BI will be beneficial, but not essential

© 2022 Microsoft. All rights reserved.

Course modules

01: Introduction to Power BI embedded analytics

02: Select a Power BI embedded analytics product
03: Set up permissions to embed Power BI content
04: Embed Power BI content
05: Integrate content with the Power BI client APIs
06: Enforce data permissions for Power BI embedded analytics
07: Automate Power BI solution management

© 2022 Microsoft. All rights reserved.

Labs

00A: Get started 45 minutes

01A: Create Power BI content 15 minutes
03A: Set up permissions 15 minutes
04A: Embed Power BI content 60 minutes
05A: Enhance embedded content 15 minutes
06A: Enforce data permissions 30 minutes

© 2022 Microsoft. All rights reserved.

Labs
Scenario

• The labs are based on the sales activities of the fictitious

Tailspin Toys company
• The Tailspin Toys company:
• Represents a specialist toy sales business that sells model airplanes and
helicopters to global markets
• Accumulates core sales data in an Azure SQL Database, and is interested to
explore, discover, and share deeper insight from this data
• In the labs, as an app developer, you will embed
Power BI reports and the Q&A experience

© 2022 Microsoft. All rights reserved.

Labs
PC setup

• You will need a Windows PC

• Windows 10, or later
• The following software must be installed:
• Power BI Desktop, latest version
• Visual Studio Code, latest update
• .NET 6.0
• A supported web browser
• Microsoft Edge (recommended)
• Google Chrome

© 2022 Microsoft. All rights reserved.

Labs
Get setup

• The self-study kit and setup instructions are available from:

• https://aka.ms/deviad-online-course
• Setup instructions:
1. Download the self-study kit (.zip) locally
2. Edit the file properties, and “unblock”
3. Extract the file contents to your file system
• The lab documents will refer to this location as <CourseFolder>
• The presentation is available as a PDF document found in the
<CourseFolder>\PowerBIDevIAD\Presentations folder
• It includes many links to useful reference material
© 2022 Microsoft. All rights reserved.
Labs
Snippet files

• To improve accuracy and reduce typing, many labs involve copying

and pasting from snippet files
• When snippet files are available, do not copy from the lab
documents—rich-formatted text blocks often paste incorrectly
• Tips:
• Avoid the temptation to just copy-and-paste
• Take the time to understand the intention of each snippet

© 2022 Microsoft. All rights reserved.

Feedback

• Your feedback is important to help us understand how well we meet

your needs, and to improve the experience for future attendees
• On completion of the class, you will be asked to complete and hand
in an evaluation form
• If you must leave the class early, please request a form in advance

© 2022 Microsoft. All rights reserved.

Lab 00A
45 minutes

Get started
Lab document available at <CourseFolder>\PowerBIDevIAD\Lab00A

1. Get started

© 2022 Microsoft. All rights reserved.

Resources
Online course

Microsoft learning path: Embed Power BI analytics

https://docs.microsoft.com/learn/paths/power-bi-embedded/

Modules include:
01: Introduction to Power BI embedded analytics
02: Select a Power BI embedded analytics product
03: Set up permissions to embed Power BI content
04: Embed Power BI content
05: Integrate content with the Power BI client APIs
06: Enforce data permissions for Power BI embedded analytics
07: Automate Power BI solution management

© 2022 Microsoft. All rights reserved.

Questions?

© 2022 Microsoft. All rights reserved.

Power BI
Developer in a Day

Module 01

Introduction to Power BI
embedded analytics
© 2022 Microsoft. All rights reserved.
Module outline
01: Introduction to Power BI embedded analytics

• Introduce Power BI
• Power BI roles
• Power BI licensing
• Power BI core concepts
• Introduce embedded analytics

© 2022 Microsoft. All rights reserved.

Introduce Power BI
Experience your data: Any data, any way, anywhere

200+ apps

© 2022 Microsoft. All rights reserved.

Introduce Power BI
Product portfolio

Author Share and Large scale Share and App dev

collaborate deployments collaborate

</>
Power BI
Power BI Power BI Power BI Power BI Power BI
Report
Desktop Service Premium Report Server Embedded
Builder

Free data Cloud-based Capacity for On-premises Visual analytics

analysis modern increased report server embedded in
and report business performance your applications
authoring tools analytics service

© 2022 Microsoft. All rights reserved.

Introduce Power BI
Product portfolio » Power BI Desktop

Get Data
Easily connect, clean, and mashup data

Analyze
Build powerful models and flexible measures

Visualize
Create stunning interactive reports

Publish
Share insights with others

Collaborate
Empower your organization with
self-service analytics
© 2022 Microsoft. All rights reserved.
Introduce Power BI
Product portfolio » Power BI Report Builder

Get Data
From Power BI, or cloud and on-prem sources

Design
Create pixel-perfect report layouts

Visualize
Use mature and rich data regions

Publish
Share insights with others

Print
Produce multi-page report documents

© 2022 Microsoft. All rights reserved.

Introduce Power BI
Product portfolio » Power BI service

Get started quickly

Secure, live connections to data sources,

on-premises and in the cloud

AI-infused insights and intuitive data

exploration using natural language query

Pre-built dashboards and reports for

popular SaaS solutions

Live, real-time dashboard updates

Deliver insights through other services,

like Teams, SharePoint, and Power Apps
© 2022 Microsoft. All rights reserved.
Introduce Power BI
Product portfolio » Power BI Premium

Power BI Premium

Flexibility to license Greater scale Embedded Extending on-

by capacity and performance analytics premises capabilities

Power BI Premium for embedded

analytics is covered in Module 08

© 2022 Microsoft. All rights reserved.

Introduce Power BI
Product portfolio » Power BI Embedded

Spend time focusing on your product instead

of building visual analytic features from scratch

Connect to countless data sources so you can

expose insights to your customers

Visualize data your way, with our rich library of

fully-customizable, open-source data
visualizations—or develop your own

Embed consistent, easy-to-navigate

visualization experiences across any device

Leverage other familiar tools and services

like Visual Studio, Azure Web Apps and other
Azure services
© 2022 Microsoft. All rights reserved.
Power BI roles
No matter what industry, or what role, Power BI is relevant

Business user

Business analyst

BI professional

Developer

Administrator
© 2022 Microsoft. All rights reserved.
Power BI roles
Developer

• Embed and integrate Power BI content in apps

• Automate Power BI solution management
• Develop custom visuals
• Develop custom data connectors
• Develop real-time dashboards
This course focuses only on
embedding and integrating
Power BI content

© 2022 Microsoft. All rights reserved.

Power BI licensing

• Three licenses are available:

• Power BI Free for personal self-service BI
• Power BI Pro for sharing and collaboration
• Power BI Premium Per User (PPU) for premium features on a per-user basis
• Azure Power BI Embedded is a product available for external
embedding
• Power BI Premium is a subscription for scale large deployments
Licensing for Power BI embedded
analytics is covered in Module 02

© 2022 Microsoft. All rights reserved.

Power BI licensing
License comparison

© 2022 Microsoft. All rights reserved.

Power BI core concepts

• Power BI service
• Workspaces
• Datasets
• Reports
• Dashboards
• Q&A

© 2022 Microsoft. All rights reserved.

Power BI core concepts
Power BI service

• Power BI is a collection of software services, apps, and

connectors that work together
• The Power BI service (app.powerbi.com) is the SaaS
(Software as a Service) part of Power BI
• It allows you to create, share, and consume business
insights

© 2022 Microsoft. All rights reserved.

Power BI core concepts
Workspaces

• Power BI workspaces are containers for Power BI content

• Two types:
• Personal workspace
• Workspace
• Content types:
• Dataflows
• Datasets
• Workbooks
• Reports
• Dashboards
© 2022 Microsoft. All rights reserved.
Power BI core concepts
Workspaces (Continued)

• Workspace architecture has changed, and by default all workspaces

are the new workspace experiences
• They are no longer based on Office 365 groups
• New workspaces are required for certain types of embedding
• Creating and publishing content to non-personal workspaces
requires a Power BI Pro or Power BI Premium Per User license
• They are a recommended practice for production content

© 2022 Microsoft. All rights reserved.

Power BI core concepts
Datasets

• Power BI datasets represent a source of data ready for reporting and

visualization
• A Power BI report is based on a single dataset
• A dataset can be used by multiple reports
Datasets will be discussed in more
detail when describing data
permissions in Module 06

© 2022 Microsoft. All rights reserved.

Power BI core concepts
Reports

• Power BI supports two different report types:

• Power BI reports
• Power BI paginated reports

© 2022 Microsoft. All rights reserved.

Power BI core concepts
Reports » Power BI reports

• Power BI reports are optimized for exploration and interactivity

• They present your data using a comprehensive range of ultra-
modern visuals
• They are:
• Ideal for analytic reports, enabling your report users to explore data, and to
discover relationships and patterns
• Developed in the Power BI service or Power BI Desktop
• The most commonly embedded report type
• You can refer to these reports as interactive analytic reports

© 2022 Microsoft. All rights reserved.

Power BI core concepts
Reports » Power BI reports » Example

Can be multi-
page, but fixed
page size

© 2022 Microsoft. All rights reserved.

Power BI core concepts
Reports » Power BI paginated reports

• Power BI paginated reports are optimized for printing, or PDF

generation
• They provide you with the ability to produce highly formatted, pixel-
perfect layouts
• They are:
• Based on SQL Server Reporting Services (SSRS) Report Definition Language
(RDL) reports
• Ideal for operational reports like sales invoices
• Developed using Power BI Report Builder
• You can refer to these reports as pixel-perfect reports
© 2022 Microsoft. All rights reserved.
Power BI core concepts
Reports » Power BI paginated reports » Example

Can
overflow
to multiple
pages

© 2022 Microsoft. All rights reserved.

Power BI core concepts
Dashboards

• A Power BI dashboard is
intended to monitor data
• Displays a collection of
up-to-date data in tiles on a
single pane
• Typically, tiles are pinned from
report visuals or Q&A responses

© 2022 Microsoft. All rights reserved.

Power BI core concepts
Q&A

• Use Q&A to explore data using intuitive, natural language

capabilities
• Power BI responds with answers as data visualizations
• The feature is available:
• On Power BI dashboards
• As a visual in Power BI reports
• Supported languages are English and Spanish (in preview)
• The Q&A experience can be embedded in apps

© 2022 Microsoft. All rights reserved.

Power BI core concepts
Q&A » Example

Enter a
question

© 2022 Microsoft. All rights reserved.

Introduce embedded analytics

Power BI content can be

embedded into apps to
deliver stunning, fully
interactive reports into apps
without the time and expense
of having to build controls
from the ground up

© 2022 Microsoft. All rights reserved.

Introduce embedded analytics

• Power BI content can be embedded in any app

• iFrame works in any modern browser control
• Relies on web standards: HTML5 and JavaScript
• Works in web applications, mobile applications, and even thick client
applications
• Seamlessly integrate Power BI content with the Power BI Client APIs
The Client APIs are
introduced in Module 05

© 2022 Microsoft. All rights reserved.

Introduce embedded analytics

• SDK resources support different development platforms and

languages
• Officially: .NET, .NET Core, JavaScript, and TypeScript
• Samples are also available for NodeJS, Python, and Java

© 2022 Microsoft. All rights reserved.

Introduce embedded analytics
Embeddable content

• Power BI reports • Dashboards

• View, edit or create • View—any interaction must be developed
• Fully interactive, including • Real-time dashboards
Q&A Explorer
• Dashboard tiles
• Power BI report visuals • View—but no interaction
• View • Real-time tiles
• Fully interactive
• Q&A experience
• Paginated reports • Can be interactive (like in the service), or
• View • Visual response only
• Fully interactive
© 2022 Microsoft. All rights reserved.
Demo 01A

Explore embedded Power BI content

http://aka.ms/pbieplayground

© 2022 Microsoft. All rights reserved.

Demo 01A

Create Power BI content

© 2022 Microsoft. All rights reserved.

Lab 01A
15 minutes

Create Power BI content

You must successfully complete Lab 00A before commencing this lab
Lab document available at <CourseFolder>\PowerBIDevIAD\Lab01A

1. Create a workspace
2. Publish a report
3. Create a report

© 2022 Microsoft. All rights reserved.

Resources

Power BI site
http://powerbi.com

Power BI community
http://community.powerbi.com/

Power BI ideas
http://ideas.powerbi.com/

Power BI blog
https://blog.powerbi.com/
Tip: Power BI is evolving at a
Power BI documentation rapid rate—one of the best ways
to keep pace with updates is to
https://docs.microsoft.com/power-bi/ subscribe to the Power BI blog

© 2022 Microsoft. All rights reserved.

Resources
Power BI developer resources

Power BI developer center

https://dev.powerbi.com/

Power BI developer documentation

https://docs.microsoft.com/power-bi/developer/

Power BI guidance documentation

https://docs.microsoft.com/power-bi/guidance/

Power BI guided learning

https://docs.microsoft.com/power-bi/guided-learning/

Microsoft Learn
https://docs.microsoft.com/learn/

© 2022 Microsoft. All rights reserved.

Resources
Online course

Online course: Power BI Paginated Reports in a Day

https://aka.ms/priad-online-course

This resource provides access

to a free online course and its
downloadable self-study kit

© 2022 Microsoft. All rights reserved.

Questions?

© 2022 Microsoft. All rights reserved.

Power BI
Developer in a Day

Module 02

Select a Power BI embedded

analytics product
© 2022 Microsoft. All rights reserved.
Module outline
02: Select a Power BI embedded analytics product

• Embed scenarios
• Select a Power BI embedded analytics product
• Manage resources and scale requirements
• Set up a development environment
• Development methodology

© 2022 Microsoft. All rights reserved.

Embed scenarios

• Two embedding scenarios:

• For your organization
• For your customers

© 2022 Microsoft. All rights reserved.

Embed scenarios
For your organization

• Applies when the app audience comprises internal users

• Internal users have organizational accounts and must authenticate
with Microsoft Azure Active Directory (Azure AD)
• To access Power BI content, app users require Power BI licenses and
permissions to consume (or create or edit) content
• Reasons:
• Internal BI portal
• Interal app
• Customized logging

© 2022 Microsoft. All rights reserved.

Embed scenarios
For your customers

• Applies when the app audience comprises external users

• The app is responsible for authenticating users
• To access Power BI content, the app relies on an embedding identity
(Azure AD service principal or master user account) to authenticate
with Azure AD
• External users aren't required to have a Power BI license or content
permissions
• Even when external users do have Power BI licenses, they aren't used by this
scenario

© 2022 Microsoft. All rights reserved.

Embed scenarios
Scenario comparison

For your organization For your customers

• Internal users • External users
• Authentication to Azure AD • Use your own authentication
• End-users require Power BI license • No end-user license
• Interactive authentication flow • Non-interactive authentication flow
• Also known as User owns data (using Service Principal or Master User)
• Also known as App owns data

© 2022 Microsoft. All rights reserved.

Select a Power BI embedded product

• Selecting a product to embed Power BI content depends on the

scenario:
• For your organization
• For you customer

© 2022 Microsoft. All rights reserved.

Select a Power BI embedded product
Scenario » For your organization

• All end users have a Power BI Pro license

• All end users have a Power BI Premium Per User (PPU) license
• The workspace is assigned to a capacity (P SKU)

© 2022 Microsoft. All rights reserved.

Select a Power BI embedded product
Scenario » For your customer

• The workspace is assigned to a capacity (P or A SKU)

• Trial embed tokens are generated using a Power BI Pro or Power BI
Premium Per User (PPU) license
• Provided strictly for evaluation or development purposes
• Trial embed tokens are not permitted to be used for production workloads
• It is possible to use the Power BI REST API to determine usage percentage

© 2022 Microsoft. All rights reserved.

Select a Power BI embedded product
Power BI Premium (P SKUs)

• Power BI Premium is a capacity-based license

• One product: P SKU
• It includes:
• Flexibility to publish reports broadly across an enterprise, without requiring
recipients to be licensed individually per user
• Greater scale and performance from a capacity in the Power BI service
• The ability to maintain BI assets on-premises with Power BI Report Server
• One API surface, a consistent set of capabilities and access to the latest
features for embedded analytics

© 2022 Microsoft. All rights reserved.

Select a Power BI embedded product
Azure Power BI Embedded (A SKUs)

• Azure Power BI Embedded is targeted at ISVs or developers who

are building apps and want to embed visuals into those apps
• One product: A SKUs
• Limitations:
• Capacity content cannot be consumed in the Power BI service
• Capacity content cannot be consumed be a Power BI Free licensed user
• Capacity content cannot be shared through one-click publish to web or one-
click publish to SharePoint
• No license for Power BI Report Server

© 2022 Microsoft. All rights reserved.

Select a Power BI embedded product
Azure Power BI Embedded (Continued)

• The resource is managed through Azure portal (or PowerShell):

• Scale up/down
• Add capacity admins
• Pause/resume of service
• There is integration with Azure Analytics
• Analyze diagnostic events to understand root causes

© 2022 Microsoft. All rights reserved.

Select a Power BI embedded product
Product comparison

A SKU P SKU
Product Power BI Embedded Power BI Premium
Purchase Azure portal Office 365
Use cases • Embed content in apps • Embed content in apps
• Share content with Power BI free users outside the
Power BI service
• Embed in other SaaS apps (Teams and SharePoint)
• Share content with Power BI free users through the
Power BI service
Billing Hourly Monthly
Commitment None Monthly/Yearly
Difference Full elasticity: scale up, scale down, pause, Combine embedding in apps and use the Power BI
resume. Service in the same capacity.
ARM API with PowerShell. Power BI Report Server included.

© 2022 Microsoft. All rights reserved.

Select a Power BI embedded product
Selection guidance

• Typically:
• Enterprises buy Power BI Premium
• ISVs buy Azure Power BI Embedded
• However, there are no restrictions on which product a customer buys
• Examples:
• Enterprises may decide to use A SKUs if they are only interested in building line of business
apps and embedding analytics into them, and are not interested in using the pre-packaged
Power BI service
• ISV (typically large) may want to use a P SKU to get the additional benefits of the pre-
packaged Power BI service within their organization, as well as embed in their apps

© 2022 Microsoft. All rights reserved.

Licensing guidance
Selection guidance » A1 is a good choice

• An A1 node may be a viable option

• Competitively priced: Currently USD 1/hour ≈ USD 720/month
• Ideal for evaluation, development and test
• Ideal to establish benchmarks when capacity sizing
• May be suitable for apps with small—or ad hoc—workloads
• Can be programmatically scaled up/down according to known usage patterns
• Can be paused if app has offline period (billing ceases when paused)

© 2022 Microsoft. All rights reserved.

Manage resources and scale requirements

• To ensure good responsiveness and performance of Power BI

embedded analytics, you need to buy the right capacity size
• Capacity size relates to the product SKU
• For Premium, SKUs range from P1 to P5
• For Power BI Embedded, SKUs range from A1 to A8
• The larger the SKU, the more memory and computing power and
cost
• Buying the right product SKU is a matter of optimization
• Too few resources can result in slow performance and, worse, an inability for
Power BI to render analytics, yet too many resources can result in wasted
money
© 2022 Microsoft. All rights reserved.
Manage resources and scale requirements
Premium

• Premium is about scale and performance

• Premium Gen2 supports a new feature called Autoscale
• When enabled, Autoscale automatically adds compute capacity to
avoid slowdowns under heavy use

© 2022 Microsoft. All rights reserved.

Manage resources and scale requirements
Power BI Embedded

• Power BI Embedded does not support the Autoscale feature

• Instead, you can set up flexible scaling by using the following
components:
• Power BI Embedded Azure Resource Manager (ARM) REST API – specifically
the Capacity operations
• The Power BI Embedded Gen2 capacity metrics
• Azure alerts

© 2022 Microsoft. All rights reserved.

Set up a development environment

• Purchasing licenses involves cost, so it is important that you avoid or

minimize cost when evaluating or developing (or testing) a Power BI
embedded analytics solution
• Several options are available for you to consider:
• Create a trial tenant
• Use an existing tenant without a capacity-based license
• Use an existing tenant with a capacity-based license

© 2022 Microsoft. All rights reserved.

Set up a development environment
Trial tenant

• Create an Office 365 E5 trial tenant, which is available at no cost for

one month, if it's not used for production purposes
• Two main advantages of using a trial tenant are:
• It is isolated from the organization's tenant (or the customer's tenant)
• You have full tenant privileges as the Global Administrator
• Power BI offers a 60-day free trial of the PPU license to individual
users
The labs in this course
depend upon an Office
365 E5 trial tenant

© 2022 Microsoft. All rights reserved.

Set up a development environment
Existing tenant without a capacity-based license

• It might make sense to use your organization's tenant (or customer's

tenant) to achieve embedding for your customers at no cost
• This option requires you to create a workspace with its license mode
set to Pro or Premium per user
• It relies on generating trial embed tokens, as described in the
previous option

© 2022 Microsoft. All rights reserved.

Set up a development environment
Existing tenant with a capacity-based license

• When longer evaluation periods are needed, or when a permanent

development environment is required, consider a low-cost setup
• In this case, create a Power BI Embedded A1 node
• It is the smallest node type, comprised of a single core with limited memory,
and 0.5 front-end and 0.5 back-end cores
• This low-resourced node:
• Is ideal for evaluation, development, and test workloads
• Is helpful to establish benchmarks when capacity sizing
• Can be scaled up or down when needed
• Can be paused when not needed (billing ceases when paused)
© 2022 Microsoft. All rights reserved.
Development methodology

1. Create a workspace
2. Add Power BI content
3. Register an Azure AD application
4. Import NuGet packages
5. Add app settings
6. Embed Power BI content
7. Enhance end user experience This methodology is simply a guide. In
this course it is also used to provide
8. Configure data permissions structure for the modules and lessons.

© 2022 Microsoft. All rights reserved.

Development methodology
1: Create a workspace

• When embedding Power BI content for customers, a workspace is

required
• It can only be created and accessed by users with a Power BI Pro license
• It can be created by automation
• Preferably, it is a new workspace experience (non-Office 365 group)
• Only new workspaces are supported by service principal
• Each workspace is uniquely identified by its Group ID (GUID)

© 2022 Microsoft. All rights reserved.

Development methodology
2: Add Power BI content

• Power BI content is added to workspaces

• Any Power BI content can be embedded
• Datasets, reports, dashboards and tiles are uniquely identified by their
resource ID (GUID)
• The Power BI REST API allow enumerating resources to retrieve IDs

© 2022 Microsoft. All rights reserved.

Resources

Power BI Embedded Playground

https://aka.ms/pbieplayground

© 2022 Microsoft. All rights reserved.

Resources
(Continued)

Power BI pricing
https://powerbi.microsoft.com/pricing/

Power BI Premium calculator

https://powerbi.microsoft.com/calculator/

Power BI Premium FAQ

https://docs.microsoft.com/power-bi/admin/service-premium-faq

Azure Power BI Embedded pricing

https://azure.microsoft.com/pricing/details/power-bi-embedded/

Frequently asked questions about Power BI Embedded

https://docs.microsoft.com/power-bi/developer/embedded/embedded-faq

© 2022 Microsoft. All rights reserved.

Resources
(Continued)

Capacity and SKUs in Power BI embedded analytics​

https://docs.microsoft.com/power-bi/developer/embedded/embedded-capacity

Capacity planning in Power BI embedded analytics​

https://docs.microsoft.com/power-bi/developer/embedded/embedded-capacity-planning

Power BI Embedded performance best practices

https://docs.microsoft.com/power-bi/developer/embedded/embedded-performance-best-practices

Office 365 E5 trial tenant setup

https://go.microsoft.com/fwlink/p/?LinkID=698279

© 2022 Microsoft. All rights reserved.

Resources
Whitepapers

Microsoft Power BI Premium white paper

https://aka.ms/pbipremiumwhitepaper

Capacity planning in Power BI embedded analytics

https://aka.ms/pbiewhitepaper

Deploying and managing Power BI Premium capacities

https://docs.microsoft.com/power-bi/guidance/whitepaper-powerbi-premium-deployment

© 2022 Microsoft. All rights reserved.

Questions?

© 2022 Microsoft. All rights reserved.

Power BI
Developer in a Day

Module 03

Set up permissions to embed

Power BI content
© 2022 Microsoft. All rights reserved.
Module outline
03: Set up permissions to embed Power BI content

• Describe token types

• Acquire an access token

© 2022 Microsoft. All rights reserved.

Describe token types

• Access is granted using two different token types:

• Azure AD token
• Embed token

© 2022 Microsoft. All rights reserved.

Describe token types
Azure AD token

• An Azure Active Directory token—or Azure AD token—must must be

acquired to access Power BI content
• It is acquired from:
• App user, for the For your organization scenario
• A dedicated Azure identity, for the For your customers scenario
• It contains claims to identify granted permissions to the Power BI REST API
• A valid Azure AD token must be present in all API operations

© 2022 Microsoft. All rights reserved.

Describe token types
Embed token

• An Embed token must be acquired to embed Power BI content and

query data when using the For your customers scenario
• It is generated by the Power BI REST API
• It contains claims to access specific Power BI content and other facts

© 2022 Microsoft. All rights reserved.

Acquire an access token

• All Power BI REST API calls require a valid Azure AD token

• By default, it expires after an hour
• Authentication flow differs based on the scenario, either:
• For your organization
• For your customers

© 2022 Microsoft. All rights reserved.

Acquire an access token
Scenario » For your organization

• App users have Power BI accounts and appropriate licenses

• The app user’s account is used to authenticate with Power BI
• The app user’s identity is used to access content and query datasets
• It is supported for any Power BI content the app user can view
• Licensing: A SKUs not supported
Licensing is covered in Module 08

© 2022 Microsoft. All rights reserved.

Acquire an access token
Scenario » For your organization » Authentication flow

1 App user 2 App caches the

authenticates access token
with Azure AD and uses it to
to acquire an embed any
access token Power BI
content the
app user has
permission to
view

Interactive
auth flow
© 2022 Microsoft. All rights reserved.
Acquire an access token
Scenario » For your customers

• When using your app, the app user does not require a Power BI
account or license
• Any authentication method can be used by the app
• A dedicated Azure AD identity is used to authenticate with Power BI:
• Service principal
• Master user account
• An embed token is required to embed Power BI content when using
an effective identity
• Requires specific product (SKUs: A or P)

© 2022 Microsoft. All rights reserved.

Acquire an access token
Scenario » For your customers

• An embed token represents several facts:

• Power BI content that can be accessed
• Access level (to allow edit for reports)
• Optionally, effective identities used to access content, and in turn, query data
• Optionally, target workspace (for “save as” of reports)
• The embed token expires when the access token expires
• An app can be developed to silently regenerate the embed token when it
expires

© 2022 Microsoft. All rights reserved.

Acquire an access token
Scenario » For your customers » Authentication flow

1 App user 2 App uses a 3 App caches the

authenticates dedicated access token
with app (any Azure AD and uses it to
authentication identity to generate an
method can be acquire an embed token
used) access token to embed Power
BI content

This course
focuses mainly
Non-interactive on this scenario
auth flow
© 2022 Microsoft. All rights reserved.
Acquire an access token
Scenario » For your customers » Embedding identity types

• There are two types of embedding identities:

• Service principal
• Master user

© 2022 Microsoft. All rights reserved.

Acquire an access token
Scenario » For your customers » Identity type » Service principal

• An Azure service principal is a security identity used by apps

• It can authenticate using an app secret or certificate
• When used to access Power BI content:
• The app will use the service principal to acquire an access token
• The service principal must be an admin or member of the workspace that
contains content to be embedded
• It does not need a Power BI Pro or PPU license
• A Power BI tenant admin must enable use of service principals, and
register service principal security groups

© 2022 Microsoft. All rights reserved.

Acquire an access token
Scenario » For your customers » Identity type » Service principal

• Admin portal
» Tenant settings
» Developer settings
• Power BI admin
permissions are
required

© 2022 Microsoft. All rights reserved.

Acquire an access token
Scenario » For your customers » Identity type » Master user account

• A master user is a regular Azure AD user

• When used to access Power BI content:
• The app will use the user account to acquire an access token
• It must belong to the admin or member roles of the workspace that contains
content to embed
• It must have either a Power BI Pro or Power BI Premium Per User license

© 2022 Microsoft. All rights reserved.

Acquire an access token
Scenario » For your customers » Identity type » Comparison

Service principal Master user

Azure AD object type Service principal User
Credential management Secret/certificate rotation Frequent password changes
management
Power BI tenant settings Must be enabled, and service -
principal must belong to a
declared security group
Power BI API usage All except: All
• Some Admin operations
• Some dataflows operations
Power BI service sign in Not supported Supported
Licensing Power BI Pro license not required Power BI Pro license required
Azure AD recommendation
© 2022 Microsoft. All rights reserved.
Acquire an access token
Proxy method guidance

• Generally:
• Service principal is a good choice for production:
• It is the recommended approach by Azure AD
• It supports better automation and scale
• There is less management overhead
• But—it requires Azure AD and Power BI admin rights to setup and manage
• Master user is a good choice for dev/test:
• It is easy to setup
• It can be used to sign in to the Power BI service to help troubleshoot issues
• But—it requires a Power BI Pro license

© 2022 Microsoft. All rights reserved.

Acquire an access token
Review » For your customers

1 App user 2 App uses a 3 App caches the

authenticates dedicated access token
with app (any Azure AD and uses it to
authentication identity to generate an
method can be acquire an embed token
used) access token to embed Power
BI content

This course
focuses mainly
Non-interactive on this scenario
auth flow
© 2022 Microsoft. All rights reserved.
Demo 03A

Set up permissions

© 2022 Microsoft. All rights reserved.

Lab 03A
15 minutes

Set up permissions
You must successfully complete Lab 01A before commencing this lab
Lab document available at <CourseFolder>\PowerBIDevIAD\Lab03A

1. Set up permissions

© 2022 Microsoft. All rights reserved.

Resources

Application and service principal objects in Azure Active Directory

https://docs.microsoft.com/azure/active-directory/develop/app-objects-and-service-principals

Power BI Developers Guide to Azure AD Security

Six video covering in-depth theory
https://www.youtube.com/playlist?list=PLRdjRuxYJMKdCxo-OZ275K_dLJMoi_BnT

© 2022 Microsoft. All rights reserved.

Resources
Conference session

Microsoft Business Applications Summit 2020

Session: Authentication patterns for Power BI embedding
Presented by Ted Pattison
https://mymbas.microsoft.com/sessions/7857bfc2-86b7-4211-b27a-ffb0494f7c3c
The session examines common development scenarios with Power BI embedding and the different ways in
which an application developer can interact with Azure Active Directory to authenticate users and to
implement a custom security policy. Learn the differences between user tokens versus app-only tokens. The
session demonstrates how to design an application that uses the app-own-data model with embed tokens
and Row Level Security (RLS) to implement a custom security scheme. The session also demonstrates
common patterns for developing applications that use the user-owns-data model including developing
MSAL.JS to support the OAuth2 implicit flow and developing with OWIN and MSAL.NET to support the
OAuth2 authorization code flow.

© 2022 Microsoft. All rights reserved.

Questions?

© 2022 Microsoft. All rights reserved.

Power BI
Developer in a Day

Module 04

Embed Power BI content

© 2022 Microsoft. All rights reserved.

Module outline
04: Embed Power BI content

• Development methodology
1. Create a workspace
2. Add Power BI content
3. Register an Azure AD application
4. Import NuGet packages
5. Add app settings
6. Embed Power BI content
7. Enhance end user experience
8. Configure data permissions

© 2022 Microsoft. All rights reserved.

Development methodology
3: Register an Azure AD application

• An Azure AD app is required to establish an identity for your app and

to specify permissions to Power BI REST resources
• It is required when requesting an access token
• Two registration tools:
• Azure portal
• Embed setup tool
• Permissions can also be granted programmatically

© 2022 Microsoft. All rights reserved.

Development methodology
3: Register an Azure AD application » Azure Portal

• Use the Azure Portal to register an app

• Advantages:
• Exposes all supported permissions
• Allows “granting permissions”
• Allows reviewing/modifying/deleting an app
• Allows setting a service principal
• Disadvantage:
• Requires accessing the Azure portal, and can be time consuming and complex

© 2022 Microsoft. All rights reserved.

Development methodology
3: Register an Azure AD application » Azure Portal » Granting permissions

• Granting permissions for the master

user is required to avoid being
prompted for consent by Azure AD
• A Global Admin can grant permissions to all users
within the organization for this application
• The master user (not a Global Admin) can grant
permissions only to the master account for this
application

Granting permissions is not

required when using a service
principal embedding identity

© 2022 Microsoft. All rights reserved.

Development methodology
3: Register an Azure AD application » Embed setup tool

• Use the Embed setup tool to accelerate embedding:

• https://app.powerbi.com/embedsetup
• It provides two paths:
• Embed for your customers
• Embed for your organization

© 2022 Microsoft. All rights reserved.

Development methodology
3: Register an Azure AD application » Embed setup tool

© 2022 Microsoft. All rights reserved.

Development methodology
3: Register an Azure AD application » Embed setup tool

• The Embed setup tool can:

• Register an Azure AD app, allowing delegation of common permissions
• Create a workspace
• Import a PBIX file (select a sample or your own file)
• Grant permissions for the Azure AD app
• It provides resources:
• Configuration values (Application ID, Workspace ID, and Report ID)
• Downloadable sample solution, with your configuration values inserted into its
config file
• Open the sample app in Visual Studio, insert your password into the config file, and simply
run to achieve your first embed! ☺
© 2022 Microsoft. All rights reserved.
Development methodology
3: Register an Azure AD application » Embed setup tool » Embed for your organization

• Accelerated embedding for your organization

• Targeted at enterprises that want to embed
analytic content on behalf of their internal users
• Workflow:
1. Sign in to Power BI
2. Register your application
3. Create a workspace
4. Import content

© 2022 Microsoft. All rights reserved.

Development methodology
3: Register an Azure AD application » Embed setup tool » Embed for your customers

• Accelerated embedding for your customers

• Targeted at any app that wants to embed
analytic content
• Workflow:
1. Sign in to Power BI
2. Register your application
3. Create a workspace
4. Import content This tool does not
support using
5. Grant permissions service principal
embedding identity

© 2022 Microsoft. All rights reserved.

Development methodology
4: Import NuGet packages

• Having created a web project, import packages:

> Install-Package Microsoft.Identity.Web
> Install-Package Microsoft.PowerBI.Api

• The powerbi.js script can be imported using npm or CDN

© 2022 Microsoft. All rights reserved.

Development methodology
4: Import NuGet packages

• Microsoft.Identity.Web package:
• Enables ASP.NET Core web apps and web APIs to use the Microsoft identity
platform
• Microsoft.PowerBI.Api package:
• A .NET Client library for Microsoft Power BI public REST endpoints
• Provides access to Power BI workspaces, and content identifiers (GUIDS) for
datasets, reports, dashboards, tiles, etc.

© 2022 Microsoft. All rights reserved.

Development methodology
5: Add app settings

• Add app settings to appsettings.json

• Azure AD:
• Domain
• Tenant ID
• Client (application) ID
• Client secret
• Power BI
• Service root URL
• Optionally, workspace IDs

© 2022 Microsoft. All rights reserved.

Development methodology
5: Add app settings » Example

{
"AzureAd": {
"Instance": "https://login.microsoftonline.com/",
"Domain": "deviad.onmicrosoft.com",
"TenantId": "c01bee20-ed93-4b74-80f8-23144cf2a62b",
"ClientId": "d1c92721-a353-4f6e-a16d-a1ee8f67b0b1",
"ClientSecret": "OTZkM2NmNjAtMWNlZC00YjEyLWI0MzEtMjM2YmE3MmRiYzQ3="
},
"PowerBi": {
"ServiceRootUrl": "https://api.powerbi.com/",
"WorkspaceId": "abcd1234-0123-4567-8901-abcdef123456"
}
…

© 2022 Microsoft. All rights reserved.

Development methodology
6: Embed Power BI content

• The embedding web page must include:

• script element to source the client-side library
<script src="https://cdn.jsdelivr.net/npm/powerbi-client@2.18.0/dist/powerbi.min.js"></script>

• div element for embedding

<div id="embed-container"></div>

© 2022 Microsoft. All rights reserved.

Development methodology
6: Embed Power BI content

• Server-side, the web app should:

• Generate an access token
• Generate an embed token Only for Power BI reports
• List of Dataset IDs (i.e., not paginated)
• List of Report IDs
• Access level (to allow edit for reports)
• Optionally, effective identities used to access content, and in turn, query data
• Optionally, target workspace (for “save as” of reports)
• Retrieve the resource IDs (ReportID, DashboardID, or TileID)
• Retrieve the embed URLs

© 2022 Microsoft. All rights reserved.

Development methodology
6: Embed Power BI content

• Client-side, first output embed artifacts inside a script element

<script>
var reports = @Html.Raw(Model.ReportsJson)
var datasets = @Html.Raw(Model.DatasetsJson)
var embedToken = "@Model.EmbedToken";
</script>

© 2022 Microsoft. All rights reserved.

Development methodology
6: Embed Power BI content » Configuration object

• The configuration object is used to describe what and how to embed

var config = {
type: 'report', Artifact type: report | visual | dashboard | tile | qna
id: report.Id,
embedUrl: report.EmbedUrl, Object unique ID:
accessToken: embedToken, report | dashboard | tile
tokenType: models.TokenType.Embed,
permissions: models.Permissions.All, Token type: Aad | Embed
viewMode: editMode ? models.ViewMode.Edit : models.ViewMode.View,
settings: {
panes: {
filters: { visible: false },
Resource-specific settings
pageNavigation: { visible: false }
}
}
};

© 2022 Microsoft. All rights reserved.

Development methodology
6: Embed Power BI content » Configuration object » Resource-specific settings

• Reports
• type: report
• settings*:
• panes: filters, pageNavigation, and other panes
• localeSettings: language and formatLocale (e.g., “en”)
• And many others…
• pageName*
• permissions*: Read | ReadWrite | Copy | Create | All
• viewMode*: View | Edit
Embed token must have
acquired relevant privileges

* Optional
© 2022 Microsoft. All rights reserved.
Development methodology
6: Embed Power BI content » Configuration object » Resource-specific settings

• Report visuals
• type: visual
• pageName
• visualName
• settings*:
• localeSettings: language and formatLocale (e.g., “en”)
• And many others…
• height*
• width*

* Optional
© 2022 Microsoft. All rights reserved.
Development methodology
6: Embed Power BI content » Configuration object » Resource-specific settings

• Dashboards:
• type: dashboard
• pageView*: actualSize | fitToWidth | oneColumn
• Dashboard tiles:
• type: tile

* Optional
© 2022 Microsoft. All rights reserved.
Development methodology
6: Embed Power BI content » Configuration object » Resource-specific settings

• Q&A experience:
• type: qna
ResultOnly mode uses a pre-
• viewMode: Interactive | ResultOnly populated question
• question: Q&A question
Interactive: optional
ResultOnly: mandatory

* Optional
© 2022 Microsoft. All rights reserved.
Development methodology
6: Embed Power BI content » Embedding

• To embed the resources, invoke the powerbi.embed method,

passing in:
• div element
• Configuration object
// Get a reference to the embed container
var embedContainer = document.getElementById('embed-container');

// Embed the report

var embeddedReport = powerbi.embed(embedContainer, config);

© 2022 Microsoft. All rights reserved.

Development methodology
6: Embed Power BI content » Phased Embedding

• To improve the end-user experience, and provide more flexibility for

developers, API calls can add phases to the embedding process
• Functions:
• load(): Retrieves info on the embedded object, and dynamically changes any
settings or the containing div element in the background, before the object
appears
• render(): When load() was called, makes the object visible

© 2022 Microsoft. All rights reserved.

Development methodology
6: Embed Power BI content » Phased Embedding

powerbi.embed(…);

powerbi.load(…); report.on("loaded", ...); powerbi.render(…);

© 2022 Microsoft. All rights reserved.

Development methodology
6: Embed Power BI content » Other performance enhancement

• Consider using bootstrap() to prepare and initialize the iFrame

• Prepare the iframe
• Report ID, embed URL, and access token are not required

powerbi.bootstrap(…) Server-side calls powerbi.embed(…)

(Get reports, generate token)

powerbi.bootstrap(divElement, { type: 'report' });

© 2022 Microsoft. All rights reserved.

Development methodology
6: Embed Power BI content » Report layout customizations

• A custom layout allows you to set a personalized layout for the

report visuals at runtime or on load
• Display option can be: FitToPage | FitToWidth | ActualSize
• A report with a default layout will render in the given div size
• To avoid scroll bars, adjust the div size to the size of the report
• To seamlessly integrate a report in your application, consider:
• Removing the iframe border
• Setting the report background to transparent in order to
reveal the web application background

© 2022 Microsoft. All rights reserved.

Demo 04A

Embed Power BI content

© 2022 Microsoft. All rights reserved.

Lab 04A
60 minutes

Embed Power BI content

You must successfully complete Lab 03A before commencing this lab
Lab document available at <CourseFolder>\PowerBIDevIAD\Lab04A

1. Create an ASP.NET Core MVC app

2. Develop the embedding logic

© 2022 Microsoft. All rights reserved.

Resources

Embed Setup Tool

https://app.powerbi.com/embedsetup

© 2022 Microsoft. All rights reserved.

Resources
NuGet packages

Microsoft Authentication Library for .NET (MSAL.NET)

https://www.nuget.org/packages/Microsoft.Identity.Client/

Microsoft Power BI API

https://www.nuget.org/packages/Microsoft.PowerBI.Api/

Microsoft.PowerBI.JavaScript
https://www.nuget.org/packages/Microsoft.PowerBI.JavaScript/

© 2022 Microsoft. All rights reserved.

Resources
Samples

Announcement: New developer samples for Power BI embedded

analytics
https://powerbi.microsoft.com/blog/new-developer-samples-for-power-bi-embedded/

Samples (do not work in Internet Explorer):

App owns data
User owns data
.NET Core Sample
API samples – NodeJS
https://github.com/microsoft/powerbi-developer-samples

© 2022 Microsoft. All rights reserved.

Resources
Samples

Samples apply Power BI Embedded best practices, including bootstrap

They use the latest libraries, including the latest Microsoft
Authentication Library: MSAL

Single page app

© 2022 Microsoft. All rights reserved.

Questions?

© 2022 Microsoft. All rights reserved.

Power BI
Developer in a Day

Module 05

Integrate content with the

Power BI client APIs
© 2022 Microsoft. All rights reserved.
Module outline
05: Integrate content with the Power BI client APIs

• Development methodology
1. Create a workspace
2. Add Power BI content
3. Register an Azure AD application
4. Import NuGet packages
5. Add app settings
6. Embed Power BI content
7. Enhance end user experience
8. Configure data permissions

© 2022 Microsoft. All rights reserved.

Development methodology
7: Enhance end user experience

• Integrate and enhance embedded Power BI content with the Power

BI Client APIs

© 2022 Microsoft. All rights reserved.

Development methodology
7: Enhance end user experience » How the Power BI Client APIs work

© 2022 Microsoft. All rights reserved.

Development methodology
7: Enhance end user experience » What is possible

• The Power BI Client APIs support many capabilities:

• User interactions are natively supported by the report view
• User interactions can trigger subscribable events
• Programmatic interaction
• Dynamic report layouts
• Capture and share bookmarks
• Report visual creation and personalization
• Embed token regeneration, when expired (SetAccessToken method)

© 2022 Microsoft. All rights reserved.

Development methodology
7: Enhance end user experience » Packages

• powerbi-client package:
• Contains a suite of JavaScript web components and APIs for integrating Power
BI into apps
• powerbi-models package:
• Contains JavaScript and TypeScript object models
• powerbi-report-authoring package:
• Contains functionality to help edit Power BI reports programmatically
• It is an extension of powerbi-client library
• powerbi-client-react package:
• Helps easily embed Power BI content in a React web application
© 2022 Microsoft. All rights reserved.
Development methodology
7: Enhance end user experience » In-context analytics workflow

• The Power BI Client APIs can drive an in-context analytics workflow

User App shows a User User clicks a App responds

navigates report filtered interactively button to by running
within the to a specific filters data in perform an some custom
app view the report action code

© 2022 Microsoft. All rights reserved.

Demo 05A

Exploring an In-context Analytics Workflow

http://aka.ms/pbieplayground – Go from insights to quick action

© 2022 Microsoft. All rights reserved.

Demo 05B

Enhance embedded content

© 2022 Microsoft. All rights reserved.

Lab 05A
15 minutes

Enhance embedded content

You must successfully complete Lab 04A before commencing this lab
Lab document available at <CourseFolder>\PowerBIDevIAD\Lab05A

1. Add client-side filtering

2. Add a context menu

© 2022 Microsoft. All rights reserved.

Resources

Power BI embedded analytics Client APIs

https://docs.microsoft.com/javascript/api/overview/powerbi/

Refresh the access token

https://docs.microsoft.com/javascript/api/overview/powerbi/refresh-token

© 2022 Microsoft. All rights reserved.

Resources
Samples

Ted Pattison, a member of Power BI CAT, has published a sample

application of Power BI Embedded in GitHub
It shows the basics you need to embed a report and demonstrates
many of the newer capabilities offered through the JavaScript API to
enrich the user’s interactions with analytics
Capabilities include report visual embedding, bookmarks, phased loading, and many more…
https://github.com/CriticalPathTraining/PowerBiEmbeddedScratchpad

© 2022 Microsoft. All rights reserved.

Resources
Samples

Microsoft Power BI embedded analytics playground

Use the sample application work with JavaScript API operations for Power BI reports, Power BI
report visuals, paginated reports, dashboards, dashboard tiles, and Q&A
The sample also describes new features with showcases
https://aka.ms/pbieplayground

© 2022 Microsoft. All rights reserved.

Questions?

© 2022 Microsoft. All rights reserved.

Power BI
Developer in a Day

Module 06

Enforce data permissions for

Power BI embedded analytics
© 2022 Microsoft. All rights reserved.
Module outline
06: Enforce data permissions for Power BI embedded analytics

• Development methodology
1. Create a workspace
2. Add Power BI content
3. Register an Azure AD application
4. Import NuGet packages
5. Add app settings
6. Embed Power BI content
7. Enhance end user experience
8. Configure data permissions

© 2022 Microsoft. All rights reserved.

Configure data permissions

• App developers can restrict

access to data by mapping
users to roles at run-time
• A single secured master User 1 Report
User 2
report can be delivered to
many users, each with
different data access
requirements

Model data

© 2022 Microsoft. All rights reserved.

Configure data permissions
Things to consider

• By default, models (datasets) allow all users to see “all data”

• However, that “all data” may already be restricted by what the
embedding identity account can access
• Data source user (e.g., Azure SQL Database supports RLS by the username that
was used to connect)
• Filters applied to model queries (DirectQuery mode)
• Implementation is affected by the type of Power BI dataset

© 2022 Microsoft. All rights reserved.

Configure data permissions
Power BI dataset types

• RLS implementation will depend on the type of dataset:

• Internal-hosted (hosted in the Power BI service):
• Import (cached) model
• DirectQuery or Composite model
• External-models (live connections):
• Azure Analysis Services
• SQL Server Analysis Services (via gateway to on-premises or IaaS)

© 2022 Microsoft. All rights reserved.

Configure data permissions
Power BI dataset types

Power BI

Composite/ Live Connection

Import
DirectQuery to AS

Azure AS

SQL Server
Import DirectQuery Analysis Services
can also be used

© 2022 Microsoft. All rights reserved.

Configure data permissions
Terminology

• Roles
• Rules
• Static rules
• Dynamic rules

© 2022 Microsoft. All rights reserved.

Configure data permissions
Terminology » Roles

• Roles are designed to restrict access to model data by surfacing only

specific rows to specific users, supported by:
• Analysis Services live connections (roles defined in external models)
• Power BI Desktop developed models (roles defined in Power BI hosted models)
• Roles define one or more rules

There is no need to
create any roles if
all users require
access to all data

© 2022 Microsoft. All rights reserved.

Configure data permissions
Terminology » Roles (Continued)

• Users can be assigned to more than one role, in which case

permission sets are combined
• However, it is generally not a good practice to assign users to multiple roles as
it can result in unexpected results—test thoroughly
• Strive to encapsulate all rules into a single role

© 2022 Microsoft. All rights reserved.

Configure data permissions
Terminology » Rules

• Rules enforce table row filters, defined by using DAX expressions

• Expressions must evaluate to true or false
• Expressions can be static or dynamic (i.e., use runtime information)
• When the expression evaluates as true, the row is retrieved
• Commonly, rules are assigned to “dimension” type tables, and
relationship filter propagation ensures restricted access to data in
related tables

© 2022 Microsoft. All rights reserved.

Configure data permissions
Terminology » Rules » Static rules

• Static rules apply filter expressions by using constant values

• To retrieve no table rows, set the expression to false

© 2022 Microsoft. All rights reserved.

Configure data permissions
Terminology » Rules » Dynamic rules

• Dynamic rules apply filters based on DAX functions:

• USERNAME() function returns the effective username, which is any value
passed by the app
• CUSTOMDATA() function returns any string value, applicable only to Azure AS

These functions are not

supported for all
dataset types—details
will be provided later
in this topic

© 2022 Microsoft. All rights reserved.

Configure data permissions
Role validation

• In Power BI Desktop, it is possible to validate permissions by viewing

the report using one or more roles
• Validation also allows passing
in a value for the effective username
(but not custom data)

Effective username
value is passed as
“other user”

© 2022 Microsoft. All rights reserved.

Pass effective identity

• To enforce RLS, at least one EffectiveIdentity object must be passed

when generating the embed token
• The object must include:
• Username
• A list of one or more Dataset IDs
• The object can optionally include:
• A list of one or more role assignments
• Custom data value
• Multiple EffectiveIdentity objects may be required to embed a
dashboard (when tiles source data from multiple datasets)
© 2022 Microsoft. All rights reserved.
Pass effective identity
Pass EffectiveIdentity » Example

// Create effective identity for the first dataset

var datasetId = datasets[0].Id.ToString();
var effectiveIdentities = new List<EffectiveIdentity>() {
new EffectiveIdentity(
username: _configuration["CurrentUser:UserName"],
roles: new List<string> {"AppUser"},
datasets: new List<string> {datasetId})
};

// Generate token request for the workspace

var workspaceRequests = new GenerateTokenRequestV2TargetWorkspace[] {
new GenerateTokenRequestV2TargetWorkspace(_workspaceId)
};

© 2022 Microsoft. All rights reserved.

Pass effective identity
Pass EffectiveIdentity » Dataset type

• Recall that RLS implementation will depend on the type of dataset:

• External models (live connections):
• Azure Analysis Services
• SQL Server Analysis Services (via gateway to on-premises or IaaS)
• Internal models (hosted in the Power BI service):
• Import (cached) model
• DirectQuery model

© 2022 Microsoft. All rights reserved.

Pass effective identity
Pass EffectiveIdentity » Dataset type » Azure Analysis Services

Azure Analysis Services

• Master user account or service principal must have at least read
permission on the model
• For service principal, pass the ObjectID as the username
• If no EffectiveIdentity is passed:
• When the embedding identity account is an Analysis Services admin, all users
can view all model data
• When the embedding identity account is not an Analysis Services admin, data
visibility will be limited by roles assigned to that account
It is a recommended practice that the effective identity of the master
user account is passed explicitly, even when RLS is not being enforced
© 2022 Microsoft. All rights reserved.
Pass effective identity
Pass EffectiveIdentity » Dataset type » Azure Analysis Services

Azure Analysis Services

• To enforce RLS, pass EffectiveIdentity:
• Username must be a master user account (UPN format) or service principal
(object ID)
• One or more roles must be defined in the model
• Role(s) must be passed to limit data visibility by enforcing rules
• DAX USERNAME function will always return the master user account
• DAX CUSTOMDATA function will return any string value passed by
EffectiveIdentity through the CustomData property

© 2022 Microsoft. All rights reserved.

Pass effective identity
Pass EffectiveIdentity » Dataset type » SQL Server Analysis Services

SQL Server Analysis Services

• Gateway data source credentials must be an Analysis Services admin
• Embedding identity account must be a gateway admin or have
ReadOverrideEffectiveIdentity permissions on the AS gateway source
• Service principal can only be added by using the API
• If no EffectiveIdentity is passed:
• When the embedding identity account is an It is a recommended practice
Analysis Services admin, all users can view all model data that the effective identity of
the master user account is
• When the embedding identity account passed explicitly, even when
is not an Analysis Services admin, data RLS is not being enforced
visibility will be limited by roles
assigned to the master user account
© 2022 Microsoft. All rights reserved.
Pass effective identity
Pass EffectiveIdentity » Dataset type » SQL Server Analysis Services

SQL Server Analysis Services

• To enforce RLS, pass EffectiveIdentity:
• Username must be a Windows account (UPN or Windows format)
• Username must have read permission on the model
• One or more roles must be defined in the model
• Role(s) can be passed to limit data visibility by enforcing rules
• DAX USERNAME function will return the username passed by EffectiveIdentity
• DAX CUSTOMDATA function is not supported

© 2022 Microsoft. All rights reserved.

Pass effective identity
Pass EffectiveIdentity » Dataset type » Power BI Import model

Power BI Import model

• Embedding identity account already has access to all data in the
model
• If no EffectiveIdentity is passed:
• All users can view all model data

© 2022 Microsoft. All rights reserved.

Pass effective identity
Pass EffectiveIdentity » Dataset type » Power BI Import model

Power BI Import model

• To enforce RLS, pass EffectiveIdentity:
• Username must be passed, but does not need to be a real username
• One or more roles must be defined in the model
• Role(s) must be passed to limit data visibility by enforcing rules
• DAX USERNAME function will return the “username” passed by
EffectiveIdentity (any text value)
• DAX CUSTOMDATA function is not supported
The USERNAME function can behave
as the CUSTOMDATA function

© 2022 Microsoft. All rights reserved.

Pass effective identity
Pass EffectiveIdentity » Dataset type » Power BI DirectQuery model

Power BI DirectQuery model

• Embedding identity account already has access to all data in the
model
• Data source (e.g., Azure SQL) is queried by the credentials stored for
the data source
• If no EffectiveIdentity is passed:
• All users can view all model data according to the permissions of the data
source account

© 2022 Microsoft. All rights reserved.

Pass effective identity
Pass EffectiveIdentity » Dataset type » Power BI DirectQuery model

Power BI DirectQuery model

• To enforce RLS, pass EffectiveIdentity:
• [The same facts as presented for import models apply]
• Username must be passed, but does not need to be a real username
• One or more roles must be defined in the model
• Role(s) must be passed to limit data visibility by enforcing rules
• DAX USERNAME function will return the username
passed by EffectiveIdentity (any text value)
• DAX CUSTOMDATA function is not supported
The USERNAME function can behave
as the CUSTOMDATA function
© 2022 Microsoft. All rights reserved.
Good design practices

• Strive to enforce data permissions through roles, not app logic

• Strive to reach scale by authoring secure master reports, delivering
different data to different users
• Strive to define fewer models, with well-designed roles
• Strive to define fewer roles, leveraging dynamic filters
• When possible, create roles/rules on “dimension” type tables, rather
than “fact” type tables (more efficient)
• Verify that the model design, including relationships and relationship
properties, are correctly configured
© 2022 Microsoft. All rights reserved.
Good design practices
(Continued)

• When using Power BI Desktop, rigorously validate role security

• Ensure that the data source connection uses the same database user
that will be applied when uploaded to Power BI
• Test also scenarios with invalid values (i.e., that do not exist in the
data source) passed as the username
• Document roles, their purpose and expected username values for
handover to the app developer

© 2022 Microsoft. All rights reserved.

Considerations and limitations

• If a model does not define roles, the GenerateToken() request

must not be passed EffectiveIdentity, other than the embedding
identity account
• If a Power BI hosted model defines roles, EffectiveIdentity
must include at least one role
• The list of EffectiveIdentity objects defines multiple identity tokens
for dashboard embedding—for all other resources, the list contains a
single identity

© 2022 Microsoft. All rights reserved.

Demo 06A

Enforce data permissions

© 2022 Microsoft. All rights reserved.

Lab 06A
30 minutes

Enforce data permissions

You must successfully complete Lab 05A before commencing this lab
Lab document available at <CourseFolder>\PowerBIDevIAD\Lab06A

1. Create a dynamic role

2. Develop a data-driven security design

© 2022 Microsoft. All rights reserved.

Resources

Use row-level security with Power BI embedded content

https://docs.microsoft.com/power-bi/developer/embedded-row-level-security

© 2022 Microsoft. All rights reserved.

Questions?

© 2022 Microsoft. All rights reserved.

Power BI
Developer in a Day

Module 07

Automate Power BI solution

management
© 2022 Microsoft. All rights reserved.
Module outline
07: Automate Power BI solution management

• Automate solution management

• Automation libraries
• Use workspace separation

© 2022 Microsoft. All rights reserved.

Automate solution management

• Developing an automation solution is typically useful when you need

to reproduce management steps
• Results in faster and more accurate management
• It can be used for:
• Lifecycle management
• Onboarding new customer to a multi-tenancy app
• IT operations

© 2022 Microsoft. All rights reserved.

Automation libraries

• Microsoft Graph API

• Power BI API
• Azure Resource Management (ARM) API

© 2022 Microsoft. All rights reserved.

Automation libraries
Microsoft Graph API

• Use the Microsoft Graph API to manage cloud service resources

• Examples:
• Create an app
• Create a service principal
• Create a service principal secret

These operations are also

available with the Azure CLI

© 2022 Microsoft. All rights reserved.

Automation libraries
Microsoft Graph API » Example

$authResult = Connect-AzureAD

$tenantId = $authResult.TenantId.ToString()
$tenantDomain = $authResult.TenantDomain

$userAccountId = $authResult.Account.Id
$user = Get-AzureADUser -ObjectId $userAccountId
…

© 2022 Microsoft. All rights reserved.

Automation libraries
Microsoft Graph API » Example

…
# Create the app secret
$newGuid = New-Guid
$appSecret = ([System.Convert]::ToBase64String([System.Text.Encoding]
::UTF8.GetBytes(($newGuid))))+"="
$startDate = Get-Date
$passwordCredential = New-Object -TypeName
Microsoft.Open.AzureAD.Model.PasswordCredential
$passwordCredential.StartDate = $startDate
$passwordCredential.EndDate = $startDate.AddYears(1)
$passwordCredential.KeyId = $newGuid
$passwordCredential.Value = $appSecret
…

© 2022 Microsoft. All rights reserved.

Automation libraries
Microsoft Graph API » Example

…
# Create the Azure AD app
$replyUrl = "https://localhost:5001/signin-oidc"

$aadApplication = New-AzureADApplication `
-DisplayName $appDisplayName `
-PublicClient $false `
-AvailableToOtherTenants $false `
-ReplyUrls @($replyUrl) `
-Homepage $replyUrl `
-PasswordCredentials $passwordCredential
…

© 2022 Microsoft. All rights reserved.

Automation libraries
Microsoft Graph API » Example

…
# Create the app's service principal
$appId = $aadApplication.AppId
$appObjectId = $aadApplication.ObjectId
$serviceServicePrincipal = New-AzureADServicePrincipal -AppId $appId
$serviceServicePrincipalObjectId = $serviceServicePrincipal.ObjectId

# Assign the current user as the app owner

Add-AzureADApplicationOwner -ObjectId $aadApplication.ObjectId
-RefObjectId $user.ObjectId

# Add the service principal of the new app as member of thesecurity group
Add-AzureADGroupMember -ObjectId $($adSecurityGroup.ObjectId) `
-RefObjectId $($serviceServicePrincipalObjectId)

© 2022 Microsoft. All rights reserved.

Automation libraries
Power BI REST API

• Use the Power BI API to access and manage Power BI content

• Examples:
• Create a workspace
• Assign a workspace to a capacity
• Grant workspace access
• Import content

© 2022 Microsoft. All rights reserved.

Automation libraries
Power BI REST API » Example

…
Connect-PowerBIServiceAccount | Out-Null

$workspace = New-PowerBIWorkspace -Name $workspaceName

$workspaceId = $workspace.Id

# Add the service principal as a workspace admin

Add-PowerBIWorkspaceUser -Scope Organization `
-Id $workspaceId `
-AccessRight Admin `
-Identifier $serviceServicePrincipalObjectId `
-PrincipalType App

# Import the Power BI Desktop file

$import = New-PowerBIReport -Path $pbixFilePath -Workspace $workspace
© 2022 Microsoft. All rights reserved.
Automation libraries
Azure Resource Management API

• Use the Azure Resource Management API to manage a capacity

• Examples:
• Create or delete capacities
• Suspend or resume a capacity
• Scale a capacity up or down
• Test for the existence of a capacity

© 2022 Microsoft. All rights reserved.

Use workspace separation

• The separation of tenants can be achieved in the Power BI service by

creating one workspace per tenant
• Each workspace contains the relevant datasets, reports, and
dashboards for that tenant
• Also, each workspace is connected only to that tenant's data
• To add additional isolation and scalability, define a dedicated service
principal for each tenant/workspace
• The setup of each tenant can be achieved with automation scripts

© 2022 Microsoft. All rights reserved.

Use workspace separation
Onboard a new tenant

• Steps:
• Create a service principal
• Add the service principal as a contributor to golden workspace
• Using the new service principal:
• Create a new workspace for the new tenant
• Publish the golden content into the new workspace
• Update the dataset to connect to real tenant data (either update the data
source or import a new dataset)
• Assign the new workspace to a capacity

© 2022 Microsoft. All rights reserved.

 Contributor
Golden Workspace

Test Dataset Service Principal 1

Report 1 Admin

Report 2
Tenant 1 Workspace
Report 3
Tenant 1 Dataset
Admin
Report 1

Report 2
Content
publishers Report 3

Capacity Assigned

© 2022 Microsoft. All rights reserved.

 Contributor
Golden Workspace

Test Dataset Service Principal 1 Service Principal 2

Report 1 Admin Admin

Report 2
Tenant 1 Workspace Tenant 2 Workspace
Report 3
Tenant 1 Dataset Tenant 2 Dataset
Admin
Report 1 Report 1

Report 2 Report 2
Content
publishers Report 3 Report 3

Capacity Assigned Capacity Assigned

© 2022 Microsoft. All rights reserved.

Resources

Overview of Microsoft Graph

https://docs.microsoft.com/graph/overview

What can developers do with the Power BI API?

https://docs.microsoft.com/power-bi/developer/automation/overview-of-power-bi-rest-api

Azure REST API reference

https://docs.microsoft.com/rest/api/azure/

Power BI developer samples

https://github.com/Microsoft/PowerBI-Developer-Samples

Service principal profiles for multi-customer apps in Power BI Embedded

https://docs.microsoft.com/power-bi/developer/embedded/embed-multi-tenancy

© 2022 Microsoft. All rights reserved.

Questions?

© 2022 Microsoft. All rights reserved.

© 2022 Microsoft. All rights reserved.