Configure your Fabric tenant

The connector signs in to Fabric as a Microsoft Entra application (a service principal), never as a user. What it can catalog depends on the permissions you give that application. This page explains each permission, what it allows the connector to do, and which features need it, so you can grant exactly what you want to use.

Permissions at a glance

#	What you set up	What it allows	Features that need it	Required
1	Entra application with a client secret	The connector signs in to Fabric, OneLake, SQL endpoints and Power BI.	Everything	Yes
2	Tenant setting: Service principals can call Fabric public APIs	Calls to the Fabric REST API.	Everything	Yes
3	Tenant setting: Service principals can access read-only admin APIs	Listing every workspace and item in the tenant, and the Power BI metadata scan.	Tenant-wide discovery, incremental runs, Power BI	For tenant-wide discovery and Power BI
4	Tenant settings: Enhance admin APIs responses with detailed metadata	Power BI table, column, measure and Power Query details in the metadata scan.	Power BI catalog and Power BI lineage	For Power BI
5	Tenant setting: Download reports	Downloading a report to read its layout.	Fields used by each report visual	Optional
6	Workspace role: Contributor	Reading item definitions, OneLake data and SQL endpoints in the workspace.	Everything inside a workspace beyond the item list	Yes, on each workspace to catalog in depth
7	OneLake data access roles	Reading lakehouses protected by OneLake security.	Tables and files of those lakehouses	Only if you use OneLake security
8	Access to Fabric connections	Reading where a pipeline or shortcut connects to.	Lineage to external systems	Optional

The application never needs write permissions on your data. The Contributor role is needed because Fabric only returns item definitions (pipelines, notebooks, dataflows) to callers that hold it.

Register the Entra application

Allows: the connector to authenticate. Needed by: every feature.

1. In the Microsoft Entra admin center , create a single-tenant app registration. No redirect URI is needed.
2. Under Certificates & secrets, create a client secret and copy its value. When the secret expires, the job and the connection test stop working until you set a new one.
3. Note the Application (client) ID and the Directory (tenant) ID. You will enter them, with the secret, in the connection .

You do not need to add API permissions to the app registration. Access is controlled by the Fabric tenant settings and workspace roles below. Depending on your tenant policies, an administrator may still need to consent to the application.

With these credentials the connector requests one access token for each Microsoft service it reads:

Service	What the token allows	Used for
Fabric REST API	Listing workspaces and items, reading item definitions, run history and connections, and the admin APIs	Discovery, pipelines, notebooks, dataflows, shortcuts, runtime lineage
OneLake	Reading lakehouse tables and the Files/ area	Lakehouse tables, columns and files
SQL analytics endpoint	Running read-only catalog queries on warehouses, lakehouse SQL endpoints and SQL databases	T-SQL column types, views, stored procedures and functions
Power BI REST API	The Power BI metadata scan, Gen1 dataflows and report downloads	Power BI catalog and lineage

Put the application in a security group

Allows: you to grant the tenant settings to the connector only, instead of to the whole organization.

Create a security group, for example blindata-fabric-readers, and add the application’s service principal to it. Use this group in the next steps.

When you assign roles through the API, use the object ID of the Enterprise application (the service principal), not the one of the app registration.

Enable the tenant settings

In the Fabric admin portal, open Tenant settings, enable the settings below and apply each one to the security group. Changes can take some time to apply, usually 15 to 30 minutes.

To open the admin portal, click the settings gear at the top right of the Fabric portal, then Admin portal. Tenant settings is the first tab. Each setting has an Enabled toggle and an Apply to choice. For every setting below, choose Specific security groups, enter the group you created in Step 2, and save. Do not leave it on The entire organization.

Service principals can call Fabric public APIs

• Where: Tenant settings, section Developer settings.

• Do: turn it on, apply it to the security group, and save.

• Note: Microsoft has split this setting in some tenants. If you see Service principals can create workspaces, connections, and deployment pipelines as well, that one is not required by the connector.

• Allows: any call to the Fabric REST API. In older tenants this setting is named Service principals can use Fabric APIs.

• Enables: the connector as a whole. Without it, nothing can be read.

Service principals can access read-only admin APIs

• Where: Tenant settings, section Admin API settings.
• Do: turn it on, apply it to the security group, and save.
• Allows: listing every workspace and item in the tenant, finding the workspaces modified recently, and running the Power BI metadata scan.
• Enables:
  • Tenant-wide discovery (discovery.mode = TENANT_ADMIN, the default): the catalog includes every workspace, even the ones the application has not been added to, which appear as inventory only.
  • Incremental runs (discovery.modifiedSinceDays).
  • Power BI: the Power BI catalog always comes from the metadata scan.
  • Item relations between items, in tenant-wide discovery.
• Without it: use workspace-scoped discovery and turn off Power BI. The connector then reads only the workspaces the application belongs to. See Configure the job .

Enhance admin APIs responses with detailed metadata

• Where: Tenant settings, section Admin API settings, right below the read-only admin APIs setting.
• Do: turn it on, apply it to the security group, and save. The read-only admin APIs setting must be on too, or the metadata scan is refused.
• Allows: the Power BI metadata scan to return the tables and columns of semantic models.
• Enables: semantic model tables and columns in the catalog, and column-level Power BI lineage.

Enhance admin APIs responses with DAX and mashup expressions

• Where: Tenant settings, section Admin API settings.
• Do: turn it on, apply it to the security group, and save.
• Allows: the Power BI metadata scan to return measure expressions and Power Query (M) code.
• Enables: measures with their DAX expressions, and the lineage from each semantic model to its sources.

Download reports

• Where: Tenant settings, section Export and sharing settings, setting Download reports.
• Do: turn it on, apply it to the security group, and save. Skip this only if you turn off products.powerBi.analyzeReportsPbix in the job.
• Allows: exporting a Power BI report to read its layout.
• Enables: the fields used by each page and visual of a report (products.powerBi.analyzeReportsPbix, on by default). If you do not grant it, turn that option off.

Setting names can change between Fabric releases. If you cannot find one, look for the setting that matches the description.

Add the application to the workspaces

Allows: reading the content of a workspace. Needed by: every feature beyond the item list.

Add the security group as Contributor to each workspace you want to catalog in depth. The role allows the connector to:

Inside the workspace, the connector can…	…which enables
Read item definitions	Pipelines, Copy jobs, Dataflows Gen2, notebooks, Spark job definitions, eventstreams, KQL databases, graph models, and their lineage
Read OneLake	Lakehouse tables, columns, files and shortcuts
Query the SQL analytics endpoints	T-SQL column types, views, stored procedures and functions, and the lineage of views and procedures
Read pipeline run history	Runtime lineage (opt-in)

With tenant-wide discovery, workspaces where the application has no role still appear in Blindata, as an inventory of their items without tables or lineage. The run report lists them under unreadableItems.

OneLake data access roles

Only if some lakehouses use OneLake security (folder or table level access roles). If a lakehouse has no OneLake security roles, skip this step.

Allows: reading the tables and folders those roles protect. Enables: their tables, columns and files in the catalog.

Who can do this: a workspace Admin or Member. Since August 2025, Contributors can no longer view or manage OneLake security roles, so ask an Admin or Member if you only have Contributor.

Steps:

1. Open the workspace in the Fabric portal and click the lakehouse to catalog.
2. Click Manage OneLake security (also shown as Manage OneLake data access in some releases). If the button is missing, the feature is not enabled for this lakehouse yet. Turn it on there first.
3. Check the DefaultReader role. If it grants access to all data, it lets everyone read the whole lakehouse, so the custom roles below cannot restrict it. Remove the users or groups from DefaultReader that should only get restricted access.
4. Click New, give the role a name (start with a letter, letters and numbers only, unique in the lakehouse), and set the permission to Read.
5. Choose the scope: All data (every table and file, including folders added later) or Selected folders and tables (only the ones the connector must read).
6. Under members, add the security group from Step 2 that contains the service principal. Use the group rather than the bare service principal, if the portal allows it.
7. Save the role. The change applies immediately to new requests.

Service principal caveat: Microsoft’s documentation lists users and security groups as role members, and does not clearly confirm that a service principal can be added directly. If the portal does not let you add the group or the service principal, a vendor guide reports this workaround: give the service principal the Viewer role on the workspace and read access on the capacity, then create a role that grants read access to the tables and files. Confirm this against the current Microsoft docs before relying on it.

If you skip this: the run reports a OneLake security denial for that lakehouse, and its tables and files are missing from the catalog. The rest of the lineage is still published.

Access to Fabric connections

Optional. Allows: reading the Fabric connections used by pipelines, Copy jobs, dataflows and external shortcuts.

Enables: lineage to systems outside Fabric, such as an Azure SQL database or an ADLS account, once you also map those connections to Blindata systems (connectionMappings in the job configuration ).

Only do this for connections that point to systems you want as lineage nodes. Every shared connection is one more source the connector can read, so skip the ones you do not need.

Who can do this: the owner of the connection, or a Fabric admin. A connection created by another user cannot be shared by you, so ask its owner.

Steps:

1. In the Fabric portal, click the settings gear at the top right, then Manage connections and gateways.
2. Open the Connections tab and find the connection the pipeline, Copy job, dataflow or shortcut uses. The Type and Server or URL columns help you match it to the system, for example an Azure SQL database or an ADLS account.
3. Select the connection, then open its Settings (or Manage users, in some releases).
4. Under Users, add the security group from Step 2, and give it the User role. The User role lets the connector read the connection without changing it. Do not give it Owner.
5. Save. Repeat for each connection.

Known limit: some connection types do not accept service principals. For example, Fabric SQL Database connections used by Data Pipelines were reported as not supported. Those endpoints are skipped, so check the run report.

If you skip this: the connector cannot read the connection, the affected endpoints are listed under skippedEndpoints in the run report, and the rest of the lineage is still published. The lineage to the external system is missing, and so is the link between that system and the Fabric items that use it.

After you share: map the connection to its Blindata system in connectionMappings in the job configuration . Without a mapping, the connection is read but not linked to a system in Blindata.

Capacity

The workspaces must run on a Fabric capacity (F SKU or trial). Warehouses, SQL endpoints and SQL databases answer only while their capacity is running: on a paused capacity, their column types, views and routines cannot be read.

Check your setup

Run these checks in order. Each one confirms one step.

1. Credentials. Request a token with the application’s credentials. A response containing access_token confirms the client ID, secret and tenant ID.

   curl -s -X POST "https://login.microsoftonline.com/<tenant-id>/oauth2/v2.0/token" \
     -d "client_id=<client-id>" \
     --data-urlencode "client_secret=<client-secret>" \
     -d "scope=https://api.fabric.microsoft.com/.default" \
     -d "grant_type=client_credentials" | jq -r '.token_type'
   

2. Fabric API. Save the token in a variable, then call GET https://api.fabric.microsoft.com/v1/workspaces. A 200 confirms Service principals can call Fabric public APIs.

   TOKEN=$(curl -s -X POST "https://login.microsoftonline.com/<tenant-id>/oauth2/v2.0/token" \
     -d "client_id=<client-id>" \
     --data-urlencode "client_secret=<client-secret>" \
     -d "scope=https://api.fabric.microsoft.com/.default" \
     -d "grant_type=client_credentials" | jq -r '.access_token')
   
   curl -s -o /dev/null -w "%{http_code}\n" \
     -H "Authorization: Bearer $TOKEN" \
     "https://api.fabric.microsoft.com/v1/workspaces"
   

3. Admin APIs. Call GET https://api.fabric.microsoft.com/v1/admin/workspaces with the same token. A 200 confirms Service principals can access read-only admin APIs. A 401 or 403 means the setting or the security group is missing.

   curl -s -o /dev/null -w "%{http_code}\n" \
     -H "Authorization: Bearer $TOKEN" \
     "https://api.fabric.microsoft.com/v1/admin/workspaces"
   

4. Workspace role. Call GET https://api.fabric.microsoft.com/v1/workspaces/<workspace-id>/items on a workspace to catalog. A 200 confirms the Contributor role. A 403 means the security group is not added to that workspace.

   curl -s -o /dev/null -w "%{http_code}\n" \
     -H "Authorization: Bearer $TOKEN" \
     "https://api.fabric.microsoft.com/v1/workspaces/<workspace-id>/items"
   

   To see the workspace IDs, run the step 2 call without -o /dev/null -w ... and pipe it to jq '.value[] | {id, displayName}'.

5. Dry run. Run the job as a dry run (see Configure the job ) and check the run report: the counts, unreadableItems, skippedEndpoints and warnings. A warning that discovery fell back to workspace scope means the admin APIs are not granted.

Updated on 13 Oct 2026