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 firstname.lastname@example.org for assistance.
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
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 Create App Integration:
3. Select SAML 2.0 and click Next:
4. Give the App a name, e.g. 'Digital Pigeon', then optionally, upload a logo
5. Feel free to use this Digital Pigeon logo at the following location: https://www.digitalpigeon.com/wp-content/uploads/2022/10/service-logo.png then click Apply:
6. Click Next:
7. In another browser window, sign in to your Digital Pigeon account as an Owner, then click on Manage | SSO:
8. Copy the SP Entity ID from Digital Pigeon, and paste this into the Audience URI (SP Entity ID) field in Okta.
Then, copy the SP ACS URL from Digital Pigeon, and paste this into the Single sign on URL field in Okta, as seen below:
9. Optional: To provision/replace the First and Last names for SSO users from your identity provider rather than those defined within Digital Pigeon - Under Attribute Statements, ensure there are two records with both 'user.firstName' and 'user.lastName' in both the Name and Value fields, as seen below:
10. Optional: To control the Digital Pigeon Role (i.e.: privilege level) of SSO users via groups in your identity provider rather than those defined within Digital Pigeon, under Group Statements, enter 'role' in the Name field, set Filter to Starts with, and enter 'Digital Pigeon' in the filter text entry, as seen below:
11. Click Next. If prompted, select you're an Okta customer adding an internal app, then click Finish:
12. In Okta, you should now be viewing the Applications | Digital Pigeon | Sign On tab. We need to copy and paste two pieces of information from Okta to the Digital Pigeon | Account Settings | SSO | SAML Identity Provider Settings page.
In Okta | Applications | Digital Pigeon | Sign On | SAML Signing Certificates, click the View SAML setup instructions:
13. In the new window that appears, copy the Identity Provider Issuer, and paste that into the Digital Pigeon IDP Entity ID field:
14. Now we need to provide either the IDP Metadata XML or the IDP Metadata URL in Digital Pigeon.
14a. To provide the IDP Metadata XML - In the same Okta SAML Setup Instructions webpage that is already open from the previous step, copy the whole of the IDP metadata, and paste that into the Digital Pigeon IDP Metadata XML field.
14b. OR, to provide the IDP Metadata URL - Navigate to Okta | Applications | Digital Pigeon | Sign On | SAML Signing Certificates, click the Actions drop down of the Active SHA-2 certificate, then click View IdP metadata. That will open a new browser tab - copy the URL and paste that into the IDP Metadata URL field.
15. 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 Okta!
16. 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:
17. Enter 'Digital Pigeon User', then click Save:
18. Repeat this process for the other two groups above, so that it looks like the following:
19. 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:
20. Find the Digital Pigeon application, and click Assign, and then Done:
21. 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
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
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:
If you have any other issues, don't hesitate to contact support at email@example.com