Microsoft Tenant Integration via Service Principal

This guide articulates the technical prerequisites to set up an integration between Zenity and a Microsoft tenant (covering multiple services such as power platform, M365 copilot, Copilot Studio, and Azure AI Foundry), using a Service Principal for authentication.

Goal:

  1. Create and set up an application that will be used by Zenity for data collection.
  2. Register the application you created as power platform administrator. Today, the only way to register your application is programmatically using a tenant administrator user.

Notice that we will grant the application "System Administrator" security role on each of the tenant's Power Platform environments.

In this document, you will find both a quick guide and a step-by-step guide.

Quick guide

A short summary of the steps required to set up your integration.

Step 1: Create an Azure AD application

  1. Create a single-tenant Azure AD application
  2. Create a client-secret for your application and keep the generated value
  3. Enable the following application permissions under API permissions
  4. Microsoft Graph: GroupMember.Read.All, User.Read.All, ExternalConnection.Read.All, TeamsAppInstallation.ReadForUser.All, AiEnterpriseInteraction.Read.All
  5. Office 365 Management APIs: ActivityFeed.Read
  6. Power BI Service: Tenant.Read.All
  1. Grant admin consent for your organization

Step 2: Register your application as Power Platform administrator

Choose one of the following options to register your application as Power Platform administrator:

  • Using PowerShell for Power Platform administrators - We highly recommend using this option for Windows users.

    • Register the application you created as Power Platform administrator - Reference

  • Using Power Platform API

    • Generate a token using your tenant's administrator user using username and password authentication - Reference
    • Register the application you created as Power Platform administrator - Reference

Step-by-step guide

Detailed instructions on how to set up your integration.

Step 1: Create an Azure AD application

Open Azure AD portal

  1. Create an Azure AD application

    1. Select App registration
    2. Click New registration
    3. Select a display name
    4. Under Supported account types choose Accounts in this organizational directory only (\<tenant> only - Single tenant)
    5. Click Register to complete image

  2. Get the application's client ID

    1. Open the application page in Azure AD
    2. Copy the ID under Application (client) ID image

  3. Create a client-secret to your application

    1. Open the application page in Azure AD
    2. Select Certificates & secrets
    3. Select Client secrets tab
    4. Click on New client secret image
    5. At Description choose a descriptive name to represent the secret
    6. At Expires choose an expiration time of 24 months (once the secret is expired you will need to create a new one and update it at your Zenity's integration)
    7. Click Add to complete image
    8. Keep the generated secret

  4. Set up permissions

    1. Open the application page in Azure AD
    2. Select API permissions
    3. Click Add a permission and enable the following permissions:
    • Under Microsoft Graph, Application permissions, choose User.Read.All, Group.Read.All image
    • Under Power BI Service, Application permissions, choose Tenant.Read.All image
    • Under Office 365 Management APIs, Application permissions, choose ActivityFeed.Read image

  5. Under API permissions, verify that the assigned permission are similar to those on the image below, and click Grant admin consent for \<tenant> image

Step 2: Register your application as Power Platform administrator

Choose one of the following options to register your application as Power Platform administrator:

  • Using PowerShell for Power Platform administrators - We highly recommend using this option for Windows users.

    1. Install PowerShell for Power Platform administrators as explained here, if not already installed.

    2. Change your PowerShell execution policy to allow you to run scripts:

      Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope LocalMachine

    3. Sign in to Microsoft Power Platform interactively with your Power Platform admin user, using the following command:

      Add-PowerAppsAccount -Endpoint prod

    4. Get your CLIENT ID of the application you created at the previous steps.

    5. Register the application you created as Power Platform administrator:

      $appId = "CLIENT_ID_FROM_AZURE_APP" New-PowerAppManagementApp -ApplicationId $appId

  • Using Power Platform API

    1. Obtain an access bearer token using your tenant's administrator user using username and password authentication.

      1. Install a REST API tool. The next steps will be based on Postman application
      2. Open the Postman application.
      3. Press on the Import button image
      4. Choose the Raw text option image

      5. Fill at the following code your Power Platform administrator username and password and the tenant id containing your application. At this request we are using Microsoft Azure CLI First-Party application in order to obtain the token with the requested scope to call the Power Platform admin registration endpoint.

        curl --location --request POST 'https://login.microsoftonline.com/{FILL_YOUR_TENANT_ID}/oauth2/v2.0/token' \ --header 'Content-Type: application/x-www-form-urlencoded' \ --data-urlencode 'grant_type=password' \ --data-urlencode 'client_id=04b07795-8ddb-461a-bbee-02f9e1bf7b46' \ --data-urlencode 'scope=https://api.bap.microsoft.com/.default' \ --data-urlencode 'username={FILL_YOUR_USERNAME}' \ --data-urlencode 'password={FILL_YOUR_PASSWORD}'

      6. Copy the code from the previous step and paste in at Postman under Paste raw text

      7. Press Continue
      8. At the Import Elements window, press Import image
      9. At the request tab that got opened, press Send image
      10. You should get the following response. Copy the value under access_token and keep it aside: image

    2. Register the application you created as Power Platform administrator using the access_token you've obtained

      1. Fill at the following code the application client id (which you created at the previous steps) which you would like to register as Power Platform Administrator:

        curl --location --request PUT 'https://api.bap.microsoft.com/providers/Microsoft.BusinessAppPlatform/adminApplications/{FILL_YOUR_APPLICATION_CLIENT_ID}?api-version=2020-10-01' \ --header 'Authorization: Bearer {FILL_THE_TOKEN_YOU_OBTAINED_IN_THE_PREVIOUS_STEP}'

      2. Copy the code from the previous step and import it to Postman as explained at the acquiring token step,

      3. Press Send
      4. Now your application is registered as Power Platform Administrator.

IPs Whitelisting Consideration

In our ongoing efforts to enhance the security and reliability of our software, we will be updating the public IP addresses used by our Services and APIs. If your company policy requires you to safelist IP Addresses for your inbound integrations then please make sure the below IPs are safelisted.

  • 18.200.62.37
  • 52.31.196.233
  • 108.128.206.229
  • 99.81.56.225

US (Ohio) Region

  • 18.116.189.61
  • 3.147.9.237

In addition, here are the service endpoints for the US region. * Zenity API endpoint: api.us1.zenity.io * Zenity portal endpoint: app.us1.zenity.io