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 Okta as the external provider.

If you run into any issues please contact Digital Pigeon at help@digitalpigeon.com for assistance. 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.

Note: To configure Okta 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 Okta account as an Administrator

Note: We recommend that you assign users to the Digital Pigeon SAML application via three Okta groups, that also control the user's role within Digital Pigeon (i.e.: User / Power User / Admin).  We find this makes user management easier, particularly in larger organisations.  This guide continues with this assumption, however if you instead would prefer to assign users to the application individually, it will be noted where to do this.

Configure Okta SSO Integration

1. Sign in to the Okta Admin Portal. Expand the Applications menu branch, and click the Applications child menu item:

2. Click Browse App Catalog:

3. In the app search field, start typing 'digital pigeon', then click the Digital Pigeon app:

4. Click Add Integration:

4. Click Done:

4. Click the Sign On tab:

5. Click Edit:

6. In another browser window, using the SAML bypass link (https://digitalpigeon-staging.com/login?samlBypass=true), sign in to your Digital Pigeon account as an Owner,  then click on Manage | SSO.  Note the following values #1 and #2.

7. Copy the values from Digital Pigeon into their respective Okta fields in the Applications | Digital Pigeon | Sign On | Settings | Advanced Sign-on Settings section.  That is, copy the SP Entity ID from Digital Pigeon, and paste this into the SP Entity ID field in Okta.  Then, copy the SP ACS URL from Digital Pigeon, and paste this into the SP ACS URL field in Okta, as seen below:

8. In Okta, scroll back up to the Sign On | Settings | SAML 2.0 | Configured SAML Attributes section and enter the text Digital Pigeon in the role field, ensuring the role drop down is set to 'Starts with'.  Then, scroll down and click Save.

9. In Okta, scroll back to the Metadata details section and copy the Metadata URL.

10. In Digital Pigeon, paste the Metadata URL into the IDP Metadata URL field:

Note: We do not yet want to click Save in Digital Pigeon since there are still a few tasks left to complete in Okta.  While it will not hurt if you do click Save, it will cause a small period of downtime for new user logins.

11. Setting up groups in Okta for application and role assignment

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

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

Each group will be assigned the Digital Pigeon Application that we just created.

Note: If you do not want to use Okta groups for role management, you will still need to assign the Digital Pigeon application to your users. You can either do this by assigning the application to your users directly, or by assigning it to a group and adding all your users into this group. However, this guide continues with the assumption that groups will be used for role assignment.

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

In Okta Admin Dashboard, navigate to Directory | Groups, then click the Add group button:

12. Enter 'Digital Pigeon User', then click Save:

13. Repeat this process for the other two groups above, so that it looks like the following:

14. Now we need to assign the Digital Pigeon Application to each of these groups.  Click Digital Pigeon Admin, then click the Applications tab, and then click Assign applications:

15. Find the Digital Pigeon application, and click Assign, and then Done:

16. Navigate back to Groups, then repeat those steps for the Digital Pigeon Power User and Digital Pigeon User groups.  The three Digital Pigeon groups should now all have 1 assigned application to them:

22. For your users to access Digital Pigeon, they need to be a member of one of the three groups above. Click on each of these groups, then click 'Assign people' to add your users as is appropriate:

23. In Digital Pigeon, as an Admin or Owner, you can view a list of your users and see which users have each roles. You can replicate these permissions in Okta by adding each user to the equivalent Okta group. Once you are finished, you will see that you have people in your groups, and applications assigned:

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

Note regarding IdP-Initiated Sign-in

IdP-Initiated sign in will only work for known users - i.e.: those that already exist in Digital Pigeon.  To enable IdP-Initiated sign-in for all users, including new users not seen by Digital Pigeon, you need to prove ownership of your email domain.  You can read how to do this via the following KB article:

https://digitalpigeon.zendesk.com/hc/en-us/articles/6979756438031-SSO-Prove-Ownership-of-a-Domain

Testing Okta SSO Sign-In

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

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

27. If required, verify using one of the configured 2FA methods:

28. Once verification has been actioned, Okta will refresh briefly:

29. And you will signed in to Digital Pigeon!

30. Other tests to validate SSO is working correctly:

• In Okta, move a user between groups, and verify that their access changes in Digital Pigeon. Note, it can take a minute or so on Okta's side for changes to be updated.
• Provision a new user in Okta, and test that IdP initiated sign in works. That is, add them to one of the Digital Pigeon groups, login to their Okta End User Dashboard, and select the Digital Pigeon App tile to sign in and provision that user in Digital Pigeon:

• Verify that the first and last names 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