Skip to main content

Okta SSO Configuration

Ian Burrowes
  • Updated

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.

 

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:

mceclip0.png

 

2. Click Create App Integration:

mceclip1.png

 

3. Select SAML 2.0 and click Next:

mceclip2.png

 

4. Give the App a name, e.g. 'Digital Pigeon', then optionally, upload a logo

mceclip3.png

 

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:

mceclip4.png

 

6. Click Next:

mceclip5.png

7. In another browser window, sign in to your Digital Pigeon account as an Owner, then click on Manage | SSO:

mceclip6.png

 

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:

mceclip7.png

 

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:

mceclip8.png

 

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:

mceclip9.png

 

11. Click Next.  If prompted, select you're an Okta customer adding an internal app, then click Finish:

mceclip10.png

 

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:

mceclip11.png

 

13. In the new window that appears, copy the Identity Provider Issuer, and paste that into the Digital Pigeon IDP Entity ID field:

Okta:

mceclip12.png

Digital Pigeon:

mceclip13.png

 

 

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.

Okta:

mceclip14.png

Digital Pigeon:

mceclip15.png

 

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.

Okta:

mceclip16.png

mceclip17.png

Digital Pigeon:

mceclip18.png

 

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.

mceclip19.png

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:

mceclip20.png

 

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

mceclip21.png

 

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

mceclip22.png

 

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:

mceclip23.png

 

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

mceclip24.png

 

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:

mceclip25.png

 

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:

mceclip26.png

 

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:

mceclip27.png

 

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

mceclip28.png

 

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:

mceclip29.png

 

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:

mceclip30.png

 

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

mceclip31.png

 

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

mceclip32.png

 

29. And you will signed in to Digital Pigeon!

mceclip33.png

 

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:

mceclip34.png

  • Verify that the first and last names 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 support at help@digitalpigeon.com

 

 

Related articles

Comments

0 comments

Article is closed for comments.

Powered by Zendesk