Skip to content

Onboarding configuration guide#

This document will walk you through the configuration necessary to get up and running with Argus PBI for your organization. If you need any help, please do not hesitate to contact support and we can answer any questions or walk through these steps on a call with you. These permission steps follow Microsoft's guidance for using the Power BI Admin APIs. This process needs the following roles to complete:

  • Microsoft Entra ID administrator (Microsoft Entra ID was previously called Azure Active Directory)
  • Fabric administrator (previously called a Power BI administrator)

1. Create an app registration#

This app registration will act as the service principal that the Argus PBI backend uses to authenticate when interacting with the Power BI APIs in your tenant. This is the entity which will have permissions to call the Power BI APIs in your tenant.

  1. Navigate to the Azure portal.
  2. Search for 'app registrations' and click on the item of the same name. image showing step 2: search for 'app registrations' and select the item of the same name
  3. Select '+ New registration'. image showing step 3: select '+ New registration'
  4. Provide a name for the app registration -- this value can follow any naming convention you like and is for your own internal management.
  5. Leave 'Supported account types' at its default of 'Single tenant only'.
  6. Under 'Redirect URI (optional)', select 'Web' from the 'Select a platform' dropdown and leave the URI field next to it empty.
  7. Click 'Register'. image showing steps 4-7: providing a name, setting the account type, and redirect URI for the registration
  8. Capture the Application (client) ID and Directory (tenant) ID. You will need to provide these to us. image showing step 8 details: Application (client) ID and Directory (tenant) ID
  9. In the left-hand menu, expand 'Manage' and select 'Certificates & secrets'.
  10. Click on '+ New client secret'.
  11. Alter 'Expires' to be '730 days (24 months)'. The dropdown defaults to 'Recommended: 180 days (6 months)', so this must be changed.
    1. Optionally, you can provide a description here which will be displayed in the Azure portal, but is not used anywhere else. image showing steps 9-11: creating new client secret with expiration after 730 days (24 months)
  12. Capture the fields 'Expires', 'Value', and 'Secret ID'. You will need to provide these to us. Note that the 'Value' will not be visible after you refresh your browser or navigate to another page. The 'Value' is equivalent to a password, so keep it secret and keep it safe. In the next section we describe how you can securely share this information with us. You can use the small copy icons next to 'Value' and 'Secret ID' to copy these values if they do not display in full on your browser. image showing step 12: capture the fields 'Expires', 'Value', and 'Secret ID'

2. Share App Registration details with Argus PBI#

Contact Argus PBI support to share the App Registration details. These are the items from steps 8 and 12 above. Do not email the values directly, as these are credentials which allow all API access that Argus PBI will use. When you send the email, simply let us know that you have created the app registration and we will provide a link where you can securely provide the App Registration details. The only person who will be able to access this link will be the person who sends the email, so please have the person who created the app registration and captured its details email us.

3. Create a Security Group and add the App Registration as a member#

Most customers prefer to create a Security Group specifically for this purpose, but you may use any existing Security Group if you prefer. Any members of this security group will be given permissions to call the Power BI Admin APIs in the next configuration step. If you are using a pre-existing Security Group, please go to the section, Alternative to Step 3: an existing Security Group to add the App Registration created above to the security group.

  1. Navigate to the Azure portal.
  2. Search for 'groups' and click on the item of the same name. This opens the 'Groups | Overview' page. image showing step 2: search for and select 'groups'
  3. Click on 'New group'. image showing step 3: click on 'New group'
  4. Leave 'Group type' at its default of 'Security' and provide a name for the security group.
  5. Add an owner to the security group:
    1. Click on 'No owners selected'
    2. Search for the user name you want to be the owner
    3. Click on the user's name
    4. Click on 'Select' image showing steps 4-5: naming the security group and add an owner
  6. Add the App Registration as a member of the group:
    1. Click on 'No members selected'
    2. Search for the App Registration name you created above
    3. Click on the App Registration's name -- it will be listed with a type of 'Enterprise application'
    4. Click on 'Select' image showing step 6: add App Registration as member of the group
  7. Click on 'Create'. image showing step 7: create the security group

Alternative to Step 3: an existing Security Group#

If you would prefer to use an existing Security Group, you can. Note that in the next section, the Security Group will be given permissions to use Power BI's Admin APIs.

  1. Navigate to the Azure portal.
  2. Search for 'groups' and click on the item of the same name. image showing step 2: search for and click on 'groups'
  3. Click on 'All groups', then search for the Security Group you would like to use and click on its name. image showing step 3: search for and click on your group name
  4. In the left-hand menu, expand 'Manage' and click on 'Members'. image showing step 4: expand 'Manage' and click on 'Members'
  5. Add your App Registration as a member of the Security Group:
    1. Click 'Add members'.
    2. Search for your App Registration's name.
    3. Click on your App Registration -- it will be listed with a type of 'Enterprise application'.
    4. Click on 'Select' image showing step 5: adding App Registration as a member

4. Configure Fabric admin permissions#

In this section, we configure permissions for the App Registration (via the Security Group it belongs to) to be able to call Power BI's Admin APIs. These settings live in the Fabric admin portal, which was previously called the Power BI Admin portal.

  1. Navigate to the Fabric admin portal tenant settings. You can also reach it from the settings menu in the top-right of the Fabric or Power BI service. image for step 1: navigating to the admin portal from the settings menu
  2. Scroll (or search in the page) until you find 'Developer settings'.
  3. Expand the subsection for 'Service principals can call Fabric public APIs'.
  4. Ensure that the setting is toggled to Enabled.
  5. Click on the radio selection for 'Specific security groups (Recommended)'.
  6. Add the Security Group configured above to the allowed list.
  7. Click on 'Apply'. image for steps 2-7: allowing Service Principals in the configured Security Group to use Fabric public APIs
  8. Scroll (or search in the page) until you find 'Admin API settings'.
  9. Expand the subsection for 'Service principals can access read-only admin APIs'.
  10. Ensure the setting is toggled to Enabled.
  11. Click on the radio selection for 'Specific security groups'.
  12. Add the Security Group configured above to the allowed list.
  13. Click on 'Apply'. image for steps 8-13: allowing service principals in the configured Security Group to use read-only Admin APIs
  14. Expand the subsection for 'Enhance admin APIs responses with detailed metadata'.
  15. Ensure the setting is toggled to Enabled.
  16. Click on the radio selection for 'Specific security groups'.
  17. Add the Security Group configured above to the allowed list.
  18. Click on 'Apply'. image for steps 14-18: allowing service principals in the configured Security Group to read detailed metadata from Admin APIs
  19. Expand the subsection for 'Enhance admin APIs responses with DAX and mashup expressions'. This setting can only be enabled if 'Enhance admin APIs responses with detailed metadata' above is also enabled.
  20. Ensure the setting is toggled to Enabled.
  21. Click on the radio selection for 'Specific security groups'.
  22. Add the Security Group configured above to the allowed list.
  23. Click on 'Apply'. image for steps 19-23: allowing service principals in the configured Security Group to read DAX and mashup expressions from Admin APIs

5. Add the Security Group to all Power BI workspaces#

Argus needs workspace-level membership in the Fabric Tenant to pull refresh history from the Fabric API.

This is a separate permission from the Admin API access configured above — it must be granted at the individual workspace level. We provide a PowerShell script that automates this by iterating through every group workspace in your tenant and adding the Security Group as a member.

Download AddGroupToWorkspaces.ps1

Prerequisites#

The script requires the MicrosoftPowerBIMgmt PowerShell module and a Power BI account with admin permissions. If the module is not already installed, run the following in PowerShell:

Install-Module -Name MicrosoftPowerBIMgmt -Scope CurrentUser

Running the script#

  1. Download the script using the link above and save it to a convenient location.
  2. Obtain the Object ID of the Security Group created in step 3. You can find this in the Azure portal under Entra ID > Groups > [Your Group] > Object ID.
  3. Run the script, passing the Object ID as the -groupIdentifier parameter:
./AddGroupToWorkspaces.ps1 -groupIdentifier "<your-security-group-object-id>"
  1. When prompted, sign in with your Power BI admin account.
  2. The script will pull the list of workspaces, then iterate through them.
  3. For each workspace, the script will attempt to add the security group as a member to the workspace using the following command:
 Add-PowerBIWorkspaceUser `
                -Scope Organization  `
                -AccessRight Member  `
                -PrincipalType Group `
                -Id $workspaceId     `
                -Identifier $groupIdentifier `
                -ErrorAction Stop `
                -WarningAction SilentlyContinue
  1. It will then output a checkmark for success, a circle if the group was already a member, and an X for any failures. If a workspace triggers rate limiting, the script retries it automatically up to three times before counting it as a failure.
  2. A summary of successful, already-added, and failed workspaces is printed at the end. If any failures occurred, the script exits with a non-zero code.

Note: If you encounter rate-limiting errors, increase the delay between requests using the -delayMs parameter (default is 2000 ms): powershell ./AddGroupToWorkspaces.ps1 -groupIdentifier "<your-security-group-object-id>" -delayMs 500

Contact Argus PBI Support if you encounter any issues running the script or if workspaces remain inaccessible after it completes.