Skip to content
  • There are no suggestions because the search field is empty.

Using a Service Principal to create a token for ISOPlanner

Introduction

When connecting to the ISOPlanner API for production purposes, we strongly advice to use a Service Principal.

  • A Service Principal is fully managed by your organization.
  • A Service Principal does not depend on user interaction.
  • A Service Principal has Admin permissions in ISOPlanner at no additional cost.

 

Possible use cases:

  • Load data from ISOPlanner into your datawarehouse by using our BI endpoints.
  • Create custom integrations using your workflow tool of choice.
  • Connect external AI interfaces to ISOPlanner

 

In the following example we create a Service Principal to connect to the ISOPlanner BI endpoints and download data using Postman.

 

Step 1: Create an app registration in the Microsoft Azure Portal

  1. Log into the Azure Portal, Open the Entra ID Service and create a new App Registration.
  2. Give the App Registration a Name ‘BI Service’. (or whatever your use case requires)
  3. Select the option ‘Accounts in this organizational directory only‘
  4. Leave the Redirect URI blank
  5. Click Register.
  6. Go to the section ‘Manage / Certificates & Secrets‘ and create a new Client Secret.
  7. Copy the secret Value (Not the ID).
  8. Copy the Application (client) ID in the Overview section.
  9. Copy the Directory (tenant) ID in the Overview section.
  10. Go to the section ‘Manage / API Permissions‘ and click Add a Permission.
  11. Select tab ‘APIs my organization uses‘ and search for ‘ISOPlanner SVC‘ and select it.
  12. Select Application Permissions and check BI.Read.All.
  13. Click Add Permission
  14. Click Grant consent for {your org}
  15. In the section ‘Manage / Branding & properties‘, set-up a logo, internal notes and update the domain if needed. (Optional)

 

BI.Read.All allows the service principal to have read-only access to all data in ISOPlanner. When you have multiple organizational units, the service principal must be added to each of them to access data.

API.ReadWrite.All allows the service principal to call all public API endpoints including making changes like updating tasks and risks with Admin permissions.

 

Step 2: Create the Service Principal in ISOPlanner

  1. Log into ISOPlanner with a user that has the Admin role.
  2. Go the Administration / Users and click Add.
  3. In the panel that opens, click ‘Add user manually‘.
  4. For field ID, paste the Application (client) ID you copied earlier
  5. For field Name, paste the name of the app registration. This does not have to match the app registration name but it is convenient to enter the same value.
  6. For field Email address, type a dummy email address like ‘bi-service@contoso.app’. You can enter a valid email address but this must be unique for all ISOPlanner users.
  7. For field User type, choose Service Principal.
  8. Click Save. The user is now added to the selected users in the panel.
  9. Click Add selected users. The user should now appear in the list.

 

 

Step 3: Connect using Postman

Start Postman, create a new collection and go to the Auth tab to fill in the authorization details. Use the following details.

  • Type: OAuth 2.0
  • Add auth data to: Request headers
  • Header prefix: Bearer
  • Grant type: Client credentials
  • Access Token URL: https://login.microsoftonline.com/{Directory (tenant) ID}/oauth2/token/
  • Client ID: Application (client) ID you saved earlier
  • Client Secret: The secret value you saved earlier
  • Scope: .default (including the dot)
  • Client Authentication: Send client credentials in body
  • Advanced / Token Request: Add key Resource with Value api://9a056f37-32fc-48b0-8075-e032dec8e3ac
  • Click Get new access token and apply it.

 

Now create a new GET request in your collection, for example for https://svc.isoplanner.app/bi/v1/tasks

After clicking Send, the call should succeed and all tasks are returned.