Introduction

This guide walks you through configuring Single Sign-On (SAML) and automatic user provisioning (SCIM) in your Entra ID 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 Entra ID.
  • 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

• Before you start
• After you are finished
• A. Getting Started
• B. Configure Single Sign On (SSO)
• C. Configure automatic user provisioning (SCIM)
• D. Assign users to the Hoxhunt application for SSO and SCIM
• E. Further reading and troubleshooting

Before you start

Before you start configuring Entra ID SSO or SCIM for Hoxhunt, make sure you meet the following technical requirements:

• You have an Entra ID tenant

• You have a user account in Entra ID with permissions to configure provisioning (for example, Application Administrator, Cloud Application administrator, Application Owner, or Global Administrator).

• You have Admin access to Hoxhunt (https://admin.hoxhunt.com/) in order to gather the 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:

• Your Entra subscription includes support for assignment groups.
• You know which users or groups you need to assign to Hoxhunt Entra ID application.
• you 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.
  IMPORTANT: This check is especially important if you have users occasionally switching from one email domain to another or you have performed email domain migration recently. If email domain of existing Hoxhunt user doesn't match with your AD information, a duplicate user may be created.

After you are finished

After you have completed configuration of Hoxhunt's Entra ID application 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 Entra ID and Hoxhunt. You can do so by checking the users in the Hoxhunt Admin Portal at https://admin.hoxhunt.com. Adjust if necessary.
• Double-check you don't have users in Hoxhunt who are outside of the 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

The Hoxhunt Entra ID enterprise application can be used for both Single Sign-On (SSO) and automatic user provisioning (SCIM). The Hoxhunt application is preconfigured, but you still need to do some changes that are described later in this article.

1. Add the Hoxhunt application from Entra Gallery

1.1. Log in to your Entra ID portal and then go to Enterprise applications > All applications > New application.

1.2. Search for "hoxhunt". Select the Hoxhunt application and click Create.

You are now ready to move forward to configure SSO and automatic user provisioning (SCIM).

B. Configure Single Sign On (SSO)

2. Assign a test user

This step helps you test SSO login once the configuration is complete.

2.1. Open the new Hoxhunt Entra ID application you created in the previous step.

2.2. Assign yourself to the application by selecting Users and groups under Manage.

3. Basic SAML configuration

3.1. Go to Single Sign-On in the Hoxhunt Admin Portal.

3.2. Copy the ACS Url (Entity ID).

3.3. Go back to Entra ID and open the new Hoxhunt Entra ID application you created earlier.

3.4. Navigate to Manage > Single sign-on.

3.5. Select SAML as your single sign-on method.

3.6. Next to Basic SAML Configuration, click Edit.

3.7. Add the ACS Url (Entity ID) you retrieved from Hoxhunt Admin Portal to Identifier (Entity ID) and Reply URL (Assertion Consumer Service URL) fields as shown below.

3.8. Add https://game.hoxhunt.com/ to Sign on URL field.

3.9. Click Save to close the dialog.

4. User Attributes and Claims

4.1. Still under Manage > Single sign-on, click Edit next to Attributes and Claims.

4.2. Under Additional claims, delete the following claims by clicking the three dots and selecting Delete.

http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress

http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name

4.3. Next, click the row for attribute http://schemas.xmlsoap.org/ws/2005/05/identity/claims/givenname .

4.4. Empty the Namespace field in the Manage claim dialog, and click Save to close the dialog.

4.5. Click the row for attribute http://schemas.xmlsoap.org/ws/2005/05/identity/claims/surname

4.6. Empty the Namespace field in the Manage claim dialog, and click Save to close the dialog.

User Attributes & Claims view should now look like this:

IMPORTANT: As of February 2024, Hoxhunt requires the use of user.mail as the main source attribute for Hoxhunt users instead of userPrincipalName. This is especially important for customers who use non-identical values for userPrincipalName and user.mail.

5. Certificate and Login URL

5.1. Still under Manage > Single sign-on, click Edit next to SAML Signing Certificate.

5.2. Download your SAML signing certificate by clicking Download next to Certificate (Base 64).

5.3. Copy the Login URL to clipboard.

5.4. Switch back to Single Sign-On in Hoxhunt Admin Portal.

5.5. Paste the Login URL to the SAML 2.0 endpoint (HTTP) field.

5.6. Open the .cer file you downloaded in a text editor.

5.7. Paste the entire contents (including -----BEGIN CERTIFICATE----- and -----END CERTIFICATE----- to the 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

5.8. Click Save.

You can now proceed to testing the SSO integration.

6. Test SSO integration

6.1. After completing step 4 above, test the SSO configuration by logging in to Hoxhunt via https://game.hoxhunt.com with a Incognito/InPrivate browser window.

6.2. If you receive any AD errors, please refer to this KB article for assistance.

C. Configure automatic user provisioning (SCIM)

8. Retrieve your SCIM token from Hoxhunt Admin Portal

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

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

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

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

9. Set Provisioning mode and credentials

9.1. Log in to your Entra ID portal and then go to Enterprise applications. Locate Hoxhunt and click to open it.

9.2. Navigate to Manage > Provisioning, and then select Get started.

9.3. Change Provisioning Mode to Automatic.

9.4. Add the Tenant URL (https://app.hoxhunt.com/services/scim).

9.5. Add the SCIM authentication token you retrieved from Hoxhunt Admin portal earlier.

9.6. Click Test Connection. If the connection test is not successful, regenerate a new SCIM token and try again.

9.7. Click Save.

10. Define attribute mappings

IMPORTANT: Before you continue, review the user attributes that you want to sync to Hoxhunt. You can also change them later if needed but it's a good practise to only provision sensible data from your AD.

TIP: If you remove an attribute mapping by mistake, you can always restore default mappings by selecting Restore default mappings checkbox and then clicking Save.

10.1. Expand Mappings and click Provision Azure Active Directory Users.

10.2. Edit the source and target attributes as needed.

10.3. The default attribute mappings defined in Hoxhunt Entra Gallery App are shown below.

10.4. Azure Active Directory Attribute column shows the source attributes that will be provisioned to Hoxhunt. You can change these attributes to match where you have the desired data in your AD.

10.5. Hoxhunt Attribute column shows the target attribute in Hoxhunt where the data from Azure Active Directory Attribute will be synced. Target attributes are explained below.

Mandatory Hoxhunt attributes

10.6. The following attributes are mandatory:

• userName and emails[type eq "work"].value:
  • These two target attributes must use the same source attribute. In most cases we recommend to map mail attribute in your AD to Hoxhunt's userName and emails[type eq "work"].value attributes.
  • IMPORTANT: As of February 2024, you must use mail as source attribute instead of userPrincipalName.
• Not([IsSoftDeleted]) mapped to active:
  • Do not change this mapping! This is related user's deactivation on Hoxhunt side when user is removed from provisioning scope.
• name.givenName and name.familyName:
  • Do not change this mapping! It is mandatory for user to have a name in Hoxhunt.

Optional Hoxhunt attributes

10.7. The following attribute mappings are optional, and the most suitable source attribute on your AD may vary. Syncing country, department and site data usually makes your Hoxhunt reports better.

10.8. You can remove any unused mappings if you don't need that data in Hoxhunt. 

10.9. Example: How to add a new attribute mapping for preferredLanguage

• Click Add New Mapping. Select a Source attribute where you have the language in ISO 639-1 alpha-2 format.
  TIP: Often you can use Entra ID's preferredLanguage as source attribute which contains the user's preferred language in Microsoft 365.
  
  
• Select preferredLanguage as Target attribute. 
•  

10.10. After you have reviewed the attribute mappings and done the needed changes, click Save and go back to Provisioning page.

11. Select provisioning scope and status

11.1. Select if you want to Sync only assigned users and groups or Sync all users and groups.

11.2. Hoxhunt recommends using Sync only assigned users and groups. This way only users who are assigned to the Hoxhunt application will be provisioned. 

11.3. If your Entra ID license won't allow you to assign groups to the Hoxhunt application, you can select Sync all users and groups and filter users using Scoping Filters. Please reach out to Hoxhunt Support at support@hoxhunt.com if you need assistance with Scoping filters.

11.4. Set a notification email address to receive notifications if provisioning is broken. It won't notify you of individual user provisioning errors.

11.5. toggle Provisioning Status to On after you are done with the configuration. 

NOTE: Initial provisioning cycle should start in 40 minutes after you have turned provisioning on. After the initial provisioning cycle, an incremental provisioning cycle will sync any changes to user data on Entra ID side to Hoxhunt every 40 minutes.

11.6. How does the provisioning work in the background?

• Subsequent provisioning cycles occur automatically every 40 minutes.
• User will only be re-provisioned to Hoxhunt if any of the mapped user attributes change in Entra ID.
• If user's data has not changed in Entra ID, user is not re-provisioned.
• In case you have lot of employees to be (re-)provisioned to Hoxhunt, all users may not be provisioned in one cycle. Entra ID will automatically split the provisioning into smaller batches.

12. Disclaimers

12.1. Provisioned data overwrites user-defined data in most cases

12.2. Each time provisioning runs, user attributes such as first name, last name, country and department are updated in the Hoxhunt system to match that of Entra ID. This means that if an end user has manually updated their settings to differ from what is attributed to them in Entra ID, those changes will be overwritten by the data synced through SCIM.

NOTE: If a user has manually added languages to their simulation language settings, provisioning of preferredLanguage attribute from Entra ID to Hoxhunt will only make sure the value defined in Entra ID is present - it will not remove additional languages added by the user.

12.3. Provisioning doesn't automatically invite or auto-start new users

12.4. Simply provisioning a new user to Hoxhunt doesn't automatically trigger an invite or auto-start for Hoxhunt training. Please use Hoxhunt Admin portal to enrol the new users or contact Hoxhunt Support to arrange a periodic activation schedule.

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

13. Test the user assignment

13.1. As a final step, you need to assign users to Hoxhunt Entra application (or create Scoping filters to assign users based on specific criteria, check further below) that you want to be provisioned. It is important to sync only actual employee accounts, and exclude non-user accounts and unwanted shared mailboxes from the provisioning scope. 

13.2. You can assign multiple users and groups to the application by going to your Hoxhunt application and selecting Users and groups under Manage.

TIP: First add only few users to the Hoxhunt application to make sure provisioning and SSO works as expected. You can test provisioning for individual users by using Provision on demand feature from Provisioning page.

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

14. Which assignment method should I use?

Option 1: Group-based assignment (RECOMMENDED)

14.1. We strongly recommend to create Entra ID group(s) for your Hoxhunt users.

14.2. You should include only employee accounts who will participate in Hoxhunt training and exclude any non-user accounts. You can use either static or dynamic Entra ID groups, but not nested groups.

14.3. Example membership rules for dynamic AD group could be to pick up only users with certain email domains, including only licensed users or users with attributes they can be recognised as employees. The best way to pick up only employee accounts depends on your AAD structure.

14.4. Group-based assignment requires Azure Active Directory Premium P1 or P2 edition. Nested group memberships and Microsoft 365 groups are not currently supported. 

• User assignment: https://docs.microsoft.com/en-us/azure/active-directory/manage-apps/assign-user-or-group-access-portal
• Dynamic membership rules: https://docs.microsoft.com/en-us/azure/active-directory/enterprise-users/groups-dynamic-membership

Option 2: Scoping filters

14.5. Scoping filters can also be used together with user assignment. With scoping filters you can filter the provisioned users based on their Entra ID attributes.

14.6. User needs to be assigned to Hoxhunt application and also pass along proper scoping filters to be in scope for provisioning. This could be done by setting a filter that allows provisioning for users with certain email domain or for example users that have an employee ID.

NOTE: If you set your provisioning scope to Sync all users and groups, you should use scoping filters to exclude at least all non-user accounts from the provisioning scope. 

14.7. Read more about scoping filters: https://docs.microsoft.com/en-us/azure/active-directory/app-provisioning/define-conditional-rules-for-provisioning-user-accounts

15. SSO and SCIM setup complete!

Once you have setup SSO and SCIM, and added all your employees who should be included in the Hoxhunt Training to Hoxhunt, you have successfully completed this step of the technical implementation!

E. Further reading and troubleshooting

Contact Hoxhunt Support if notice any issues with SSO or user provisioning. Below you can find links to articles that can help with troubleshooting.

15. Troubleshooting SSO

• I receive an AD error when trying to log in via SSO.
  • Check this KB article for common AD errors and how to fix them.
• Login process always takes me back to Hoxhunt login page.
  • Check if your SAML certificate has expired. Renew if needed.

16. Troubleshooting SCIM

If you are experiencing issues with Hoxhunt SCIM provisioning, it's a good idea to first check the provisioning logs in Entra ID for clues.

1. Go to Azure Active Directory > Enterprise applications > [Hoxhunt] > Provisioning > View provisioning logs.
2. In Status filter, tick only Failure and Warning.
3. Select a suitable time frame from Date filter. NOTE: You can go back as far as 30 days*.
4. Observe the filtered log list. Check Action column and learn which provisioning actions are causing issues.
5. Click on a log entry to see detailed information about the error under Troubleshooting & Recommendations. See Error Codes for assistance.

*The Entra portal stores reported provisioning data for 30 days if you have a premium edition and 7 days if you have a free edition. You can publish the provisioning logs to Log Analytics for retention beyond 30 days.

Most common reasons for provisioning errors

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

Due to security reasons, user's first name and last name cannot contain any bracket characters. If at all possible, avoid using bracket characters in first name and last name data in Entra ID. 

17. Further reading

Known issues for application provisioning in Azure Active Directory

Provisioning does not appear to start

No users are being provisioned

Provisioning logs say users are skipped and not provisioned even though they are assigned

Application provisioning in quarantine status

18. External SCIM resources

• General information about automatic user provisioning
  • https://docs.microsoft.com/en-us/azure/active-directory/app-provisioning/configure-automatic-user-provisioning-portal
• On-demand provisioning to test provisioning with a single user
  •  https://docs.microsoft.com/en-us/azure/active-directory/app-provisioning/provision-on-demand
• Check the status of user provisioning
  • https://docs.microsoft.com/en-us/azure/active-directory/app-provisioning/application-provisioning-when-will-provisioning-finish-specific-user
• Provisioning logs
  • https://docs.microsoft.com/en-us/azure/active-directory/reports-monitoring/concept-provisioning-logs?context=/azure/active-directory/app-provisioning/context/app-provisioning-context

Frequently asked questions

Q: Manager or City target attributes are not available for our organization in Entra ID Hoxhunt gallery application

A: If your Entra Gallery application has been added or configured before 8th of August 2023, it's required to restore the default attribute mappings before manager and city target attributes are displayed.

1. In Entra ID, navigate to your Hoxhunt enterprise application > Provisioning and click Stop provisioning.
   
   
   
   
2. In the same view, navigate to the attribute mappings by clicking Edit attribute mappings > Mappings > Provision Azure Active Directory Users.
   
   
   
   
   
3.  Make a note of all the current attribute mappings in use for your organization (both Azure Active Directory Attributes and Hoxhunt Attributes).
   
   
   
   NOTE: If your organization uses any custom expressions to parse only partial data from attributes, remember to make a note of the specific expressions as well! You can see this by clicking on the lines and verifying if the Mapping type is Expression.
   
   
4.  Navigate back to the previous view (Step 2) and select Restore default mappings and click Save.
   
   
   
   
   
   
   
5.  After saving, navigate back to the Attribute mappings by clicking Provision Azure Active Directory Users.
   
   
   
   
6.  The new attributes should now be visible for you to configure.
   
   
   
   
   
7. Re-configure the attribute mappings similarly as noted in step 3. 

If you need any assistance with this, please contact us at support@hoxhunt.com or submit a request.