Workspace Access¶
When MetaMiner's service principal must be a member of a workspace, which role it needs, and which features run as the signed-in user instead.
How it works¶
The scheduled inventory uses Microsoft's admin APIs, which see every workspace in the tenant. For that, the service principal needs no workspace membership at all.
A few features call Power BI and Fabric APIs that work only inside a workspace the caller belongs to. For those, add the service principal to the workspace, either directly or through a security group it belongs to (for example the group from Security Group for the App).
When the service principal needs a workspace role¶
| Feature | Workspaces | Role | Without it |
|---|---|---|---|
| Inventory, lineage, scans, activity, apps, capacities, gateways, connections | None | None | - |
| Capacity Metrics | The workspace of the Microsoft Fabric Capacity Metrics app | Contributor or Admin | Test Connection fails at Fabric Capacity Metrics Data, and no capacity metrics are collected |
| Fabric item definitions (reports, semantic models, Dataflow Gen2, notebooks, pipelines and other supported items) | Each workspace whose definitions you want in MetaMiner | Admin, Member or Contributor. Report definitions also need Write permission on the report's semantic model. | Those items are inventoried, but their definitions are not read |
| Dataflow definitions | Workspaces with dataflows | A workspace role | Dataflow definitions are not read |
| Backup | Each workspace in a backup job | Contributor | The backup wizard shows the workspace as needing a grant |
| .pbix export from the Power BI Explorer | The workspace of the report | A workspace role | The export fails for that report |
TODO: confirm the minimum role for dataflow definitions and .pbix export
Source to check: Microsoft Learn for Dataflows - Get Dataflow and Reports - Export Report In Group; test whether Viewer is enough for a service principal.
Grant access for backup from MetaMiner¶
You do not have to add the service principal to each backed-up workspace by hand. The Access page of the backup wizard in the MetaMiner Client checks each selected workspace and can grant the service principal Contributor for you.
- The grant is made as the person signed in to Power BI in the client, so that person must be an Admin of the workspace, or a Fabric administrator.
- MetaMiner records each grant it made (workspace, service principal and MetaMiner user) in the MetaMiner Database.
- If the person is not a workspace Admin, MetaMiner tries the grant through the admin API, which succeeds only for a Fabric administrator.
Image of the backup wizard Access page with one workspace granted and one needing a grant
../images/microsoft-setup/backup-wizard-access-page.png
Features that run as the signed-in user¶
These features never use the service principal's workspace rights. Microsoft checks the signed-in person's own rights on every call.
| Feature | The signed-in person needs |
|---|---|
| Manage Access (list, add, change, remove workspace access) | The right to manage access on that workspace in Power BI; in the Tenant Admin View, the Fabric Administrator role |
| Restore from a backup archive | Admin, Member or Contributor on the target workspace |
| Restore a deleted workspace | The Fabric Administrator role |
| Export Meta Query results to a lakehouse | Write access to the lakehouse |
Steps to add the service principal to a workspace¶
- In the Power BI service or Fabric portal, open the workspace and select Manage access.
- Click Add people or groups.
- Enter the MetaMiner application name (or the security group that contains it).
- Select the role from the table above and click Add.
TODO: re-check the workspace Manage access labels against current Microsoft Learn
Source to check: Microsoft Learn, "Give users access to workspaces".
You can also do this from the MetaMiner Client with Manage Access, signed in as a workspace Admin. See Manage Workspace Access.
Verify¶
- The workspace's access list shows the application (or its group) with the expected role.
- For Capacity Metrics: Test Connection passes Fabric Capacity Metrics Data.
- For backup: the wizard's Access page shows the workspace as granted.