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:

  • Azure AD administrator
  • Power BI or Office 365 administrator

1. Create an Azure App Registration#

This Azure 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 default.
  6. Set type of 'Web' and leave the redirect URI 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 and Directory IDs. You will need to provide these to us. image showing step 8 details: Application ID and Directory ID
  9. Navigate to 'Certificates & secrets'.
  10. Click on '+ New client secret'.
  11. Alter 'Expires' to be '730 days (24 months)'.
    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 11 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, Use 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. image showing step 2: search for and select 'groups'
  3. Click on 'New group'. image showing step 3: click on 'New group'
  4. 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
    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

Use 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. 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. Click on 'Members'. image showing step 4: 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.
    4. Click on 'Select' image showing step 5: adding App Registration as a member

4. Configure Power BI 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.

  1. Navigate to the Power BI Admin portal.
  2. Scroll (or search in the page) until you find 'Audit and usage settings'.
  3. Expand the subsection for 'Create audit logs for internal activity auditing and compliance'.
  4. Ensure that the setting is toggled to Enabled. image for steps 2-4: finding audit settings and expanding the correct node
  5. Scroll (or search in the page) until you find 'Developer settings' (it should be directly below 'Audit and usage settings' from above).
  6. Expand the subsection for 'Allow service principals to use Power BI APIs.
  7. Ensure that the setting is toggled to Enabled.
  8. Click on the radio selection for 'Specific security groups (Recommended)
  9. Add the Security Group configured above to the allowed list.
  10. Click on 'Apply'. image for steps 5-10: allowing Service Principals in the configured Security Group to use Power BI APIs
  11. Scroll (or search in the page) until you find 'Admin API settings' (it should be directly below 'Developer settings'from above).
  12. Expand the subsection for 'Allow service principals to use read-only admin APIs'.
  13. Ensure the setting is toggled to Enabled.
  14. Click on the radio selection for 'Specific security groups'
  15. Add the Security Group configured above to the allowed list.
  16. Click on 'Apply'. image for steps 11-16: allowing service principals in the configured Security Group to use read-only Admin APIs
  17. Expand the subsection for 'Enhance admin APIs responses with detailed metadata'.
  18. Ensure the setting is toggled to Enabled.
  19. Click on the radio selection for 'Specific security groups'
  20. Add the Security Group configured above to the allowed list.
  21. Click on 'Apply'. image for steps 17-21: allowing service principals in the configured Security Group to read detailed metadata from Admin APIs
  22. Expand the subsection for 'Enhance admin APIs responses with DAX and mashup expressions'.
  23. Ensure the setting is toggled to Enabled.
  24. Click on the radio selection for 'Specific security groups'
  25. Add the Security Group configured above to the allowed list.
  26. Click on 'Apply'. image for steps 22-26: allowing service principals in the configured Security Group to read detailed metadata from Admin APIs