Azure AD SSO Configuration

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 [e-mail] 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
• 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, 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 copy and paste two pieces of information from Azure AD to the Digital Pigeon | Account Settings | SSO | SAML Identity Provider Settings page.

In Azure AD | Enterprise Applications | Digital Pigeon | Single sign-on, scroll down to 'Set up Digital Pigeon' and copy the Azure AD Identifier value.

Azure AD:

Paste that into the Digital Pigeon | SSO | SAML Identity Provider Settings IDP Entity ID field:

Digital Pigeon:

10. Now we need to provide either the IDP Metadata XML or the IDP Metadata URL in Digital Pigeon.

10.a. To provide the IDP Metadata XML - In the same Azure AD window that is already open from the previous step, scroll to scroll to '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.b. OR, to provide the IDP Metadata URL - In the same Azure AD window that is already open from the previous step, scroll to 'SAML Certificates', and copy the App Federation Metadata Url:

Azure AD:

Digital Pigeon:

11. By default, if a role is not supplied by the IDP, then the 'User' role will be used. This can be changed if necessary.

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!

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

Note: The steps that follow describe one way of setting up group-based role assignment that is possible to implement for most Azure AD customers. However, depending on your Azure AD tenant configuration and licensing level, there might be other ways of achieving the same objective that might be more appropriate for your own situation. For instance, the Azure AD P1 licensing level can utilise group-based application assignment, but Azure AD Free users cannot. Additionally, Azure AD groups that were originally synced from Active Directory on-premise instances can pass the samAccountName as part of the role assertion, however native Azure AD instances cannot.

Therefore, from this point forward, feel free to use this guide as a reference and customise your own Azure AD configuration as is necessary.

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:

13. 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:

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

If you have Azure AD P1 licensing level or above, add the three Digital Pigeon groups that you created in the previous step. Otherwise, you can assign the application to your users on an individual basis.

15. To source the first and last names from Azure AD rather than Digital Pigeon, navigate back to Home | Enterprise Applications | Digital Pigeon | Single sign-on, scroll down to (2) Attributes & Claims, then click Edit, then click Add new claim:

We need to add two new claims for the first and last names, using the data below, and leaving the other settings as default values:

Name	Attribute
user.firstName	user.givenname
user.lastName	user.surname

Claim 1:

Claim 2:

16. 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:

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

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

19. 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".

20. We must add two more claims and repeat steps 17 through 19 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:

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

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

Testing Azure AD SSO Sign-In

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

24. 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:

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

26. 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.)

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

28. 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 are having any issues with SSO sign in and you need to modify the SSO configuration (e.g. verify/correct a mistake, or update/disable SSO due to IdP issue) 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 have any other issues, don't hesitate to contact Digital Pigeon support at [e-mail]