Configuring Okta SSO and SCIM

Introduction

This guide walks you through configuring Single Sign-On (SAML) and automatic user provisioning (SCIM) in your OKTA for the Hoxhunt service.

  • Single Sign-On allows your employees to login to e.g. Hoxhunt Dashboard at https://game.hoxhunt.com and Admin portal at https://admin.hoxhunt.com/.
  • Automatic user provisioning creates users to Hoxhunt and keeps their user data up to date. Provisioning service also deactivates users who are unassigned from the enterprise application or are deactivated in Azure AD.
    • Importing users to Hoxhunt does not yet start the training for the employee, they need access to the Hoxhunt button to be able to start the training. 

NOTE: Setting up SSO is optional. Single Sign-On is not required to report emails with Hoxhunt button. If you don't wish to configure SSO, employees can log in to Hoxhunt App via Magic Links.

NOTE: Setting up SCIM is optional. If you don't wish to configure SCIM, you can manage your Hoxhunt users via Hoxhunt Admin Portal

Contents

Supported Features

The Okta/Hoxhunt SAML integration currently supports the following features:

  • IdP-initiated SSO
  • SP-initiated SSO
  • JIT (Just In Time) Provisioning

The Okta/Hoxhunt SCIM integration currently supports the following features:

  • Create users

  • Update user attributes

  • Deactivate users

For more information on the listed features, visit the Okta Glossary.

Before you start

Before you start configuring Okta, make sure you meet the following technical requirements:

  • you have an Okta account with admin privileges

  • your organization has a SCIM provisioning subscription/licence for Okta. Contact your Okta representative to ensure your organization has the appropriate subscription. (NOTE: Only required for SCIM)

  • you have Admin access to Hoxhunt in order to gather necessary setup information (if you don't have access, please reach out to your Onboarding Manager or Customer Success Manager)

In addition, configuration is easier if you:

  • make sure you know which users or groups you need to assign to Hoxhunt Okta application.
  • check which employees already have an account in Hoxhunt. You can utilise Data Inspector or ask Hoxhunt Support to provide a full user list. You may also identify users who have already left your company or shouldn't be part of Hoxhunt anymore.

After you are finished

After you have completed Okta configuration for SSO and/or SCIM, please check the following:

  • make sure the provisioned user data meets your expectations, and all user attributes are properly mapped between Okta and Hoxhunt. Adjust if necessary.
  • Double-check you don't have users in Hoxhunt who are outside of Okta's provisioning. Correct as necessary.
  • double-check you haven't provisioned unwanted users (e.g. technical accounts) to Hoxhunt. Adjust your assignments as necessary.

 

A. Getting started

1. Installing the Hoxhunt Okta Application

1.1 Login to Okta admin interface.

1.2. Go to the Applications tab.

1.3. Enter Hoxhunt to the search field and click Add application.

1.4. In the General settings, complete the following:

1.5. Application Label: Specify the display name for the service.

1.6. Click Done.

 

B. Configure Okta SSO

2. SAML Configuration steps

2.1. Go to Single Sign-On in Hoxhunt Admin Portal.

2.2. Copy the ACS Url (Entity ID). 

SSO_-_Retrieve_ACS_Url__Entity_ID_.png

2.3. Go  to the Sign On tab in the Hoxhunt Okta application and click View Setup Instructions.

okta_sso_1.png

2.4. Find your organization ID from the end of ACS Url (Entity ID) (string after https://app.hoxhunt.com/saml/consume/*) you retrieved from Hoxhunt Admin Portal and Add it to the Organization ID field in Okta. 

2.5. Retrieve the Identity Provider Single Sign-On URL and X.509 Certificate and save them for future use.

2.6. Change Application username format to Email.

2.7. Click Save.

2.8. Go back to Single Sign-On in Hoxhunt Admin Portal.

2.9. Add the Identity Provider Single Sign-On URL you obtained earlier from Okta and paste it to SAML 2.0 endpoint (HTTP) field.

SSO_-_Enter_SSO_URL.png

2.10. Paste the X.509 certificate you obtained earlier from Okta and paste it to Public certificate field.

TIP: If needed, you can reformat the X.509 certificate with free online tools like https://www.samltool.com/format_x509cert.php

SSO_-_Enter_certificate.png

2.11. Click Save.

2.12. You can now proceed to testing the SSO integration.

 

3. Test SSO integration

3.1. Go back to the Hoxhunt Okta application.

3.2. Navigate to Assignments tab and click Assign to add yourself to the application.

3.3. You can now test SSO by either of the following methods:

  • by logging in to Hoxhunt via https://game.hoxhunt.com with a Incognito/InPrivate browser window.
  • by accessing Hoxhunt Okta app through the Okta Apps menu (only if made visible to your employees).

3.4. If you will configure also SCIM user provisioning, don't add more users at this point.

3.5. Otherwise, add rest of the users by going to Assignments tab in the Hoxhunt Okta application and clicking on Assign. Then add users to the application.

 

Okta SCIM

NOTE: Okta supports Just In Time (JIT) provisioning. As soon as user's data changes in Okta, the change is provisioned to Hoxhunt.

 

C. Configure OKTA automatic user provisioning (SCIM)

4. Retrieve your SCIM token from Hoxhunt Admin Portal

4.1. Go to Automated user provisioning in Hoxhunt Admin Portal.

4.2. Retrieve the SCIM token by clicking Generate new token.

IMPORTANT: Once generated, the token cannot be seen on the page anymore. If for any reason you lose your SCIM token, you must generate a new one. Hoxhunt cannot retrieve the current SCIM token for you.

SCIM_-_Retrieve_token.png

4.3. A warning will appear, letting you know that the token you are generating will replace the existing one. If this is your first time setting up SCIM for Hoxhunt, you can ignore this message.

SCIM_-_warning.png

4.4. Copy the SCIM authentication token from the Hoxhunt Admin Portal.

IMPORTANT: Once generated, the token cannot be seen on the page anymore. If for any reason you lose your SCIM token, you must generate a new one. Hoxhunt cannot retrieve the current SCIM token for you.

SCIM_-_Copy_token.png

4.5. Go back to Hoxhunt Okta application and navigate to Provisioning tab and click Configure API Integration.

okta_scim_step_2.png4.6. Check the Enable API integration box.
4.7. Enter the SCIM authentication token to API Token field.
4.8. Click Test credentials and then click Save.okta_scim_step_3.png

4.9. Enable Create UsersUpdate User Attributes and Deactivate Users, then click Save.okta_scim_step_4.png

4.10. If you want to edit the default attribute mappings, choose the Provisioning tab and scroll down to the mappings.SCIM_attribute_mappings.png

4.11. Attributes supported by Hoxhunt are shown in the picture above. You can change the source attribute to match the location of the respective data in Okta, or unmap any attributes that you don't want to sync to Hoxhunt. If you need help, contact support@hoxhunt.com.

NOTE: For more information about provisioning manager information from Okta to Hoxhunt, please refer to: Manager information

If you are unsure of any attribute mappings, you can unmap if for now and re-map it later.

 

5. Test provisioning

5.1. Click Force Sync button under Hoxhunt Attribute Mappings.

5.2. Navigate to the Hoxhunt Admin portal at https://admin.hoxhunt.com/ to confirm that test users have been synced correctly before assigning rest of the users.

 

D. Assign users to the Hoxhunt application for SSO and SCIM

6.1. Go to Assignments tab in the Hoxhunt Okta application and click on Assign and add users to the application.
NOTE! Each time provisioning runs, any user attribute such as country, department or preferredLanguage is updated in the Hoxhunt system to match that of Okta. This means that if an end user has manually updated their settings to differ from what is attributed to them in Okta, those changes will be overwritten by the data synced through Okta SCIM.

 

6.2. Congratulations, you are done!

 

7. Known Issues/Troubleshooting

7.1. Contact support@hoxhunt.com in case there are any issues with Okta SSO login or Okta SCIM provisioning. We will add known issues and troubleshooting tips to this section.

User cannot be updated to Hoxhunt

An error occurred while pushing a profile update to this app.
Automatic profile push of user FirstName LastName to app Hoxhunt failed:
Error while trying to push profile update for first.last@company.com:
No user returned for user 1a2b3c4d5e6f7g8h

Okta_scim_user_update_error.png

Explanation: the user was manually removed from Hoxhunt so Okta's provisioning is unable to locate the user anymore.

Resolution: Please remove the user from Hoxhunt's Okta app assignments and re-add the user.

Names cannot contain brackets <>(){}[]

Due to security reasons, user's first name and last name cannot contain any bracket characters.

Was this article helpful?

3 out of 3 found this helpful

Have more questions? Submit a request