Configuring Single Sign-On for Digital Pigeon enables your users to authenticate with an external identity provider that you manage, rather than Digital Pigeon itself.

The following steps show the process of configuring SSO for Digital Pigeon using Microsoft Azure AD as the external provider.

If you run into any issues please contact Digital Pigeon at help@digitalpigeon.com for assistance.

 

Note: To configure Azure AD SSO Integration with Digital Pigeon you will need:

• A Digital Pigeon account on the Business plan, or higher (If you are on a trial you may not be able to set up SSO, if that is the case for you please contact the team as well.)
• Access to your Digital Pigeon account as an Owner
• Access to your Azure AD account as an administrative account that has either Global Administrator permissions, or else both Application Administrator and Group Administrator permissions.

 

Configure Azure AD SSO Integration

1. Login to https://portal.azure.com with an administrative account and click Azure Active Directory

 

2. Click Enterprise Applications

 

3. Click New Application

 

4. In the Search Application text field, type 'Digital' and then click Digital Pigeon

 

5. Edit the name if necessary, then click Create:

 

 

6. Select Set up single sign on:

7. Select SAML

Now click edit in the Basic SAML Configuration section

 

8. In a new browser window, log in to Digital Pigeon as an Owner using the SAML Bypass Link: https://digitalpigeon.com/login?samlBypass=true, then navigate to Account Settings | SSO and copy and paste the values as follows:

 

Copy the SP Entity ID (1) from Digital Pigeon, and paste this into the Identifier (Entity ID) (1) field in Azure AD.

Then, copy the SP ACS URL (2) from Digital Pigeon, and paste this into the Reply URL (ACS URL) (2) field in Azure AD, replacing the existing values, as seen below.   Leave the Sign-On, Relay State and Logout URLs blank:

 

Select Save.

 

9. We need to populate either the IDP Metadata XML or the IDP Metadata URL value in Digital Pigeon, from the corresponding fields in Azure AD.

You can use either - the XML is possibly a nanosecond faster as it avoids an additional web query during the sign in process, however it will need to be updated once every three years (before the Azure AD 'Token Signing Certificate' expires).

For this reason, we would generally recommend using the URL.

 

9.a. To provide the IDP Metadata URL - In Azure AD | Enterprise Applications | Digital Pigeon | Single sign-on, scroll down to '(3) SAML Certificates', and copy the App Federation Metadata Url:

Azure AD:

Digital Pigeon:

 

 

9.b. OR... To provide the IDP Metadata XML - In Azure AD | Enterprise Applications | Digital Pigeon | Single sign-on, scroll down to '(3) SAML Certificates', download the Federation Metadata XML and open and copy the entire contents of the file:

Azure AD:

Paste that into the Digital Pigeon IDP Metadata XML field.

Digital Pigeon:

 

10. New users can be created (provisioned) when signing in for the first time via SAML - a process called 'Just-in-Time Provisioning'.  A 'role' claim can be sent as part of the SAML login process, that will determine what permissions they have in Digital Pigeon.  If a role claim is not supplied by the IdP, then the standard 'User' role will be used when creating the account. This can be changed if necessary as seen below.  (Alternatively, the Default Role can be set to 'Disable auto-provisioning when SAML role assertion missing' if you would prefer to not use JiT provisioning.)

Note: We do not yet want to click Save in Digital Pigeon as this will turn on SSO, and there are still a few tasks left to complete in Azure AD!

 

In Azure AD, we need to grant users access to the Digital Pigeon Enterprise Application, and optionally set their role permissions.

How these two tasks are best achieved can vary between Active Directory tenancies, due to different licensing levels and configuration.  For instance, the Azure AD P1 licensing level can utilise group-based application assignment, but Azure AD Free users cannot.  This guide continues with the assumption that Azure AD Premium P1 or greater is in use, and group-based permissions are wanted.  However from this point forward, feel free to use this guide as a reference and customise your own Azure AD configuration as is necessary.

 

STOP: If you do not have Azure AD Premium P1 or P2  licenses, you will need to assign users to the Digital Pigeon Enterprise Application individually, rather than use the group based method as per the following steps 11-16.  In addition, if you want to use group based licensing using a work around, complete steps 11  and 12, then skip forward to step 22.

• Assign users to the Digital Pigeon Enterprise Application individually, including choosing the role, or else
• Use a work-around that will be explained towards the bottom of this article.  Skip forward to Step 22 to read more.

 

11. We now need to create Azure AD groups to assign the application to users and to control role permissions.

We will create three groups in Azure AD, that will correspond to the administrative roles in Digital Pigeon:

• Digital Pigeon User
• Digital Pigeon Power User
• Digital Pigeon Admin

Note: Users of Digital Pigeon who are Owners, will not have their role changed by SSO group assignment.

Navigate to Home | Azure Active Directory | Groups.

Note: It is important to ensure you are no longer configuring the Digital Pigeon Enterprise Application, that also has a Groups page. Confirm that the breadcrumbs menu indicates you are at Home > (Your Directory) | Groups >, and NOT …>Enterprise Applications | All Applications > Digital Pigeon.

Click New group:

 

12. Enter the Group Name exactly as: Digital Pigeon User

You may also add members who should have the Digital Pigeon base level 'User' role permissions, by clicking No members selected. Once you are finished adding users, click Create.

 

Repeat this process for the two other groups: Digital Pigeon Power User and Digital Pigeon Admin, ensuring the names are correct and the users are populated as necessary, so it looks like the following:

 

13. In Azure AD, navigate back to Home | Enterprise Applications | Digital Pigeon | Users and Groups. Click on Add user/group:

 

Assuming you have Azure AD P1 licensing level or above, you can now add the three Digital Pigeon groups that you created in the previous step, matching their corresponding role as seen below.

 

Starting with Digital Pigeon Admin, select the group:

 

Then, select the corresponding role:

 

Now, click Assign:

 

14. Repeat the steps above for the other two roles, ensuring that the role assigned matches the group name.  You should end up with the following displayed in your Enterprise Applications | Digital Pigeon | Users and Groups:

 

15. We now need to add an additional role claim.  Navigate back to Enterprise Applications | Digital Pigeon | Single Sign-On, scroll down to (2) Attributes & Claims, and click Edit.

Then, click Add a group claim:

16. Select Groups assigned to the application as the group type, and Cloud-only group display names as the Source attribute.  Then tick the Customize the name of the group claim checkbox, and type role into the Name field, as seen below.  Now click Save.

 

 

STOP: The following Steps 17-22 are only relevant for Azure AD Free users that couldn't complete the group based assignment above.  If you have Azure AD P1 / P2 and have successfully completed those steps, please skip directly to Step 23.

 

17. To control the role permission in Digital Pigeon from Azure AD we need to pass a 'role' claim that contains one of the three Digital Pigeon permission group names. Currently, Azure AD is not able to natively pass the group name in its claim, only a cryptic GroupID attribute that is unique between Azure AD customer tenants. This is an outstanding feature request with Microsoft that may change in future, however as at October 2022, we need to use a work-around to pass the group name, that is detailed in the following steps. (As mentioned previously, if your Azure AD groups have been synchronised from Azure AD on premise, you will be able to access and pass the SAM account name value, that you can ensure matches the group names that we created above).

Add a new claim with the name 'role', and expand the Claim conditions:

Claim 3:

 

18. For the User type, choose Members, and then click Select groups. Click the Digital Pigeon User group, then click Select:

 

19. Click the Transformation radio button, then click Undefined:

 

20. Select IfNotEmpty() from the Transformation list, user.userprincipalname from the Parameter 1 (Input) list, then type and select Digital Pigeon User in the Parameter 2 (Output) field. (It will add the quotes by itself).

 

So, what have we just created? Our work-around rule tests if the field user.userprincipalname has a value. (All Azure AD Users must have a UPN, so this will always be true). Then, we are supplying the output "Digital Pigeon User", however are only sending this claim when the user is in the AD group "Digital Pigeon User".

 

21. We must add two more claims and repeat steps 18 through 20 for the other two groups: Digital Pigeon Power User, and Digital Pigeon Admin, remembering to match each scoped group name to the transformation output. When you're done, if the role claim conditions match the following, click Save:

 

22. The Attributes & Claims for the Digital Pigeon application should now look like this:

 

23. Now switch back to the Digital Pigeon SSO settings page, and click Save to activate SSO

 

Testing Azure AD SSO Sign-In

24. In a new Private/Incognito browser window, test out one of your users to check that the sign in process works correctly:

 

25. Because the user's email address is associated with an account that has SSO enabled, the Azure AD login page appears in a new window:

 

26. Enter the password (+ 2FA if configured in that user's Azure AD profile):

 

27. Optionally, if signing on from a trusted device, allow Azure AD to stay signed in to reduce authentication prompts. (In this case, as we are just testing, we will choose No.)

 

28. You will now be signed in to Digital Pigeon!

 

29. Other tests to confirm SSO is working correctly:

• In Azure AD, move a user between groups, and verify that their access changes in Digital Pigeon. Note, it can take a minute or so on Azure AD's side for changes to be updated.

• Provision a new user in Azure AD, and test that IdP initiated sign in works. That is, add a new user to one of the Digital Pigeon groups but do not create them within Digital Pigeon, login to their Azure AD Application Dashboard (https://myapps.microsoft.com/), and select the Digital Pigeon App tile to sign in and provision that user in Digital Pigeon:

• Verify that the first and last names of your users are being sourced from your Identity Provider

 

Troubleshooting

If you need to modify the SSO configuration (e.g. verify/correct a mistake, or update/disable SSO due to  an IdP issue) remember that you can bypass SSO for owner logins. Use the following URL to login with Digital Pigeon internal authentication:

https://digitalpigeon.com/login?samlBypass=true

If you're experiencing issues with SSO setup, please refer to our dedicated SSO Troubleshooting KB guide:

SSO - Troubleshooting – Digital Pigeon (zendesk.com)

If you're still having trouble, don't hesitate to contact Digital Pigeon support at help@digitalpigeon.com