PowerBI Widget - Configuration Guide

This guide covers two security approaches for deploying the PowerBI widget in enterprise environments.

Overview

The PowerBI widget supports two authentication and authorization patterns:

• Option 1: Direct Service Principal – Simple setup, service principal directly assigned
• Option 2: Security Group – Enterprise-recommended, using Entra ID security groups

Prerequisites (Both Options)

Review the following steps, as they apply to both options.

2. Configure App Registration

After registration, note down:

• Application (client) ID
• Directory (tenant) ID

3. Create Client Secret

1. Go to Manage > Certificates & secrets
2. Click +New client secret
3. Configure:

• Description: PowerBI-Widget-Secret
• Expires: 24 months (recommended)
• Click Add

4. Copy the secret value immediately – you won’t see it again

Once you’ve completed the steps above, choose the option you want to proceed with and follow the corresponding instructions.

Option 1: Direct Service Principal (Simple Setup)

Power BI Admin Center Configuration

1. Go to Power BI Admin Portal > Tenant settings

2. Configure these settings:

Developer Settings

• ✅ Enabled: Service principals can call Fabric public APIs
• Apply to: The entire organization

Embed Content Settings

• ✅ Enabled: Embed content in apps
• Apply to: The entire organization

Workspace Access Configuration

1. Go to your PowerBI Workspace

2. Click Manage access

3. Click +Add people or groups

4. Search for your service principal:

• Format: [App Name] (AppId: [Application-client-ID])

5. Select permission level:

• Member (recommended) – Full access to workspace content
• Contributor – Can create/edit content
• Viewer – Read-only access (minimum required)

6. Click Add

Option 2: Security Group (Enterprise Recommended)

Step 3: Power BI Admin Center Configuration

1. Go to Power BI Admin Portal > Tenant settings

2. Configure these settings:

Developer Settings

• ✅ Enabled: Service principals can call Fabric public APIs
• Apply to: Specific security groups
• Security groups: Add your security group:
  • PowerBI-Service-Principals

Embed Content Settings

• ✅ Enabled: Embed content in apps
• Apply to: Specific security groups
• Security groups: Same security group as above:
  • PowerBI-Service-Principals

Step 4: Workspace Access Configuration

1. Go to your PowerBI Workspace

2. Click Manage access

3. Click +Add people or groups

4. Search for your security group:

• PowerBI-Service-Principals

5. Select permission level:

• Member (recommended) – Full access to workspace content
• Contributor – Can create/edit content
• Viewer – Read-only access (minimum required)

6. Click Add

Widget Configuration

Parameters Required

{
“tenantID”: “your-tenant-id”,
“clientID”: “your-application-client-id”,
“clientSecret”: “your-client-secret”,
“inputUrl”: “https://app.powerbi.com/groups//reports/”
}

Supported URL Formats

• Reports: https://app.powerbi.com/groups//reports/
• Specific Pages: https://app.powerbi.com/groups//reports//ReportSection
• Dashboards: https://app.powerbi.com/groups//dashboards/

Security Comparison

Troubleshooting

Common Issues

Error: “Unauthorized” or “Token expired”

• Verify client secret hasn’t expired
• Check API permissions are granted with admin consent
• Ensure service principal/security group has workspace access

Error: “Service principal not found”

• Wait 10-15 minutes after creating the app registration
• Verify the service principal is added to security group (Option 2)
• Check Power BI admin settings allow service principals

Error: “Access denied to workspace”

• Verify workspace permissions (minimum: Viewer)
• Check workspace visibility (must not be personal workspace)
• Ensure security group has proper workspace access (Option 2)

Error: “At least 1 dataset is required” (Dashboards)

• This is handled automatically by the widget
• Occurs with static dashboards (images, text only)
• Widget includes fallback handling

Best Practices

1. Use Security Groups for enterprise environments

2. Rotate client secrets regularly (every 12-24 months)

3. Grant minimum required permissions (Viewer level sufficient for embedding)

4. Monitor service principal usage through Azure AD audit logs

5. Document security group membership for compliance

6. Test with non-admin users to verify permissions are correct

Security Notes

• Client credentials flow provides application-level access (not user-specific)
• Workspace-scoped permissions limit access to assigned workspaces only
• No interactive authentication required – suitable for server-side widgets
• Security groups provide better governance and audit capabilities
• Regular secret rotation maintains security posture