Skip to Content
IntegrationMicrosoft Tenant Integration via Service Principal

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 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

  • Microsoft Graph: GroupMember.Read.All, User.Read.All, ExternalConnection.Read.All, TeamsAppInstallation.ReadForUser.All, AiEnterpriseInteraction.Read.All

  • Office 365 Management APIs: ActivityFeed.Read

  • 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 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 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 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 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](/img/integration/power-platform-spn/pp-spn-image10.png)
   9. At the request tab that got opened, press _Send_
      ![image](/img/integration/power-platform-spn/pp-spn-image11.png)
   10.  You should get the following response. Copy the value under _access_token_ and keep it aside:
       ![image](/img/integration/power-platform-spn/pp-spn-image12.png)

2. Register the application you created as _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