It is possible to set up Microsoft Entra ID as an OpenID provider with the planning app. With this setup, your existing Microsoft Entra ID users can log in to the planning app without a different account.

The generic instructions are also available on the Microsoft Docs website.

Setting up Microsoft Entra ID

1. Go to the Azure portal: https://portal.azure.com/#home

2. Select Microsoft Entra ID in the menu
   
   

   Open

   

3. Go to App Registrations and click on New Registration.
   
   

   Open

   

4. Insert the application's name (e.g. piplanning app) and the callback URL.
   
   Please note: Depending on how your Microsoft Entra ID is configured and which users you want to give access to the piplanning app, you might have to select a different option in the Supported account types section. If login for some users doesn't work, try changing this configuration option.
   
   
   

   
   The callback URL can be found on the "Identity Provider" page in the Cockpit.
   
   

5. Double-check that the permissions are correct. You need the Microsoft Graph User.Read permissions to log in successfully. If you want to map Microsoft Entra ID groups to piplanning app teams automatically, you need to add Microsoft Graph Group.Read.All permissions as well.
   
   

6. Next is the creation of a client secret. This can be done by going to the "Certificates & Secrets" menu item and clicking on "New client secret"
   
   

7. The secret can now be copied and saved. This information is needed in the piplanning app to set the Identity Provider.
   
   

In order to set up group mapping from Microsoft Entra ID to piplanning.io teams you need to execute the following steps:

1. Navigate to Microsoft Entra ID → App registration → piplanning app → Token configuration. Click on “Add group claim“ and select the “Groups assigned to the application (recommended for large enterprise companies to avoid exceeding the limit on the number of groups a token can emit)“ option. Click on the “Save” button.
   
   

2. Navigate to Microsoft Entra ID → App registration → piplanning app → Manifest. Find “optionalClaims“ and modify the “idToken“ property to include “cloud_displayname“ under “additionalProperties“. Click on the “Save“ button.
   
   

    

3. Navigate to Microsoft Entra ID → Enterprise applications → piplanning app → Users and groups. Click on the “Add user/group“ button and select all groups you want to map to the piplanning.io teams.

4. In the piplanning.io cockpit go to Organizations → Teams and select a team you want to map to the Microsoft Entra ID group. Click on the “Edit Team” button and select “OpenID Connect group“. Fill the “Group name“ field and click save.

Setting up the piplanning app

1. Login to the Cockpit and click the "Identity Provider" menu item. The OpenID Connect configuration page will open.
   
   

2. Fill in a connection name of your choice. This name will appear on your users' login button. (e.g. "Microsoft Entra ID")

3. Leave the "Automatically discover endpoints" option enabled and enter as Issuer the following URL: https://login.microsoftonline.com/{tenantId}/v2.0
   The tenant ID must be substituted with the value found on the Microsoft Entra ID application registration overview as Directory (tenant) ID:

   Please note: Depending on your configuration, you might have to use the older API version. If login doesn't work with your setup, try to remove /v2.0 from the issuer URL:
   https://login.microsoftonline.com/{tenantId}
   
   

4. Fill in the client ID that you can also find in the application registration overview as Application (client) ID

5. Fill in the client secret from the value you previously generated under "Certificates & Secrets"

6. Fill the Scope field with the following values: openid email profile

7. At this point, the form should be complete, and the connection should be saved by clicking "Save."
   
   

    

8. If you want to automatically map Microsoft Entra ID groups to piplanning app teams, you need to add a “groups“ value to the Groups Claim field. For a Group claim to work correctly, you need to use v2.0 at the end of the Issuer string. Older versions are not supported. (Example: https://login.microsoftonline.com/<id>/v2.0)
   
   

   
   The login screen will now add the option to log in with Microsoft Entra ID.

FAQ

Q: During login, I get the error: "A request to the OpenID Connect Token API has failed. Unable to complete this login request" [Backend error: AADSTS700025 - invalid_client]
A: Make sure you have selected "Web" (instead of a single page application) for the redirect URI in Azure.