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/.
• Setting up SSO is optional but recommended. 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.
• Automatic user provisioning (SCIM) 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. Note: 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. 

Getting Started

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

• You have Admin access to Hoxhunt (https://admin.hoxhunt.com/). If you don't have access, please reach out to your Onboarding Manager, Customer Success Manager or Hoxhunt Support.
• For the SSO & SCIM configuration 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)

Configuring Single Sign On (SSO)

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

• Log in to your Entra ID portal and then go to Enterprise applications > All applications > New application.
• 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).

2. Assign a test user

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

• Open the new Hoxhunt Entra ID application you created in the previous step.
• Assign yourself to the application by selecting Users and groups under Manage.

3. Basic SAML configuration

• Switch to Hoxhunt Admin Portal , and navigate to Settings > Single Sign-On > Identity providers.
• Click Add Provider button to start configuring a new provider.

• In the opening view, give your SSO provider a name, for example Entra.
• Copy the value in ACS Url (Entity ID) field above the provider name.
• If you want to use this provider as default for new email domains added to Hoxhunt in the future, enable Use provider as default for new email domains.
• Switch back to Entra ID and open the new Hoxhunt Entra ID application you created earlier.
• Navigate to Manage > Single sign-on.
• Select SAML as your single sign-on method.
• Next to Basic SAML Configuration, click Edit.
• Add the ACS Url (Entity ID) you retrieved from Hoxhunt Admin Portal to Identifier (Entity ID) and Reply URL fields as shown below.
• Add https://game.hoxhunt.com/ to Sign on URL field.
• Click Save to close the dialog.

4. User Attributes and Claims

• Still under Manage > Single sign-on, click Edit next to Attributes and Claims.
• 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  

• IMPORTANT! 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.
• For this, click the row for Unique User Identifier (Name ID), change the Source attribute to user.mail and Save to close the dialog.

• User Attributes & Claims view should now look like this:

5. Certificate and Login URL

• Still under Manage > Single sign-on, download your SAML signing certificate by clicking Download next to Certificate (Base 64).
• Copy the Login URL to clipboard.

• Switch back to Single Sign-On in Hoxhunt Admin Portal.
• Paste the Login URL to the SAML 2.0 endpoint (HTTP) field.
• Open the .cer file you downloaded in a text editor.

• 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

   

• Click Save.
• Navigate back to Hoxhunt Admin Portal > Settings > Single Sign-On > Domain settings.
• Set the newly created Entra identity provider to be used for your current domains.

6. Test SSO integration

• After completing the above steps, test the SSO configuration by logging in to Hoxhunt via https://game.hoxhunt.com with a Incognito/InPrivate browser window.
• If you receive any AADSTS errors, please refer to this KB article for assistance.

7. Assign users to the Hoxhunt application for SSO

• As a final step, you need to assign users to Hoxhunt Entra application.
• You can assign multiple users and groups to the application by going to your Hoxhunt enterprise application and selecting Users and groups under Manage.

Configure automatic user provisioning (SCIM)

1. Retrieve your SCIM token from Hoxhunt Admin Portal

• Go to Automated user provisioning in Hoxhunt Admin Portal.

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

• 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.
• Copy the SCIM authentication token from the Hoxhunt Admin Portal.

2. Set Provisioning mode and credentials

• Log in to your Entra ID portal and then go to Enterprise applications. Locate Hoxhunt and click to open it.
• Navigate to Manage > Provisioning, and then select New configuration.
• Add the Tenant URL (https://app.hoxhunt.com/services/scim).
• Add the SCIM authentication token you retrieved from Hoxhunt Admin portal earlier.
• Click Test Connection. If the connection test is not successful, regenerate a new SCIM token and try again.
• Click Create on the bottom of the page.

3. 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 practice 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.

• Go to Attribute mappings and click Provision Microsoft Entra ID Users.

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

  IMPORTANT! These default mappings need to be changed, see steps 10.4 and 10.5.

• Microsoft Entra ID Attribute column shows the source attributes that will be provisioned to Hoxhunt. 
• Hoxhunt Attribute column shows the target attribute in Hoxhunt where the data from Microsoft Entra ID Attribute will be synced. Target attributes are explained below.

4. User attributes

4.1 Mandatory Hoxhunt User Attributes

• The following attributes are mandatory:
  • userName and emails[type eq "work"].value:
    • 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. This is especially important for customers who use non-identical values for userPrincipalName and mail.
  • 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.

4.2 Optional Hoxhunt User Attributes

• You can find a list of available user attributes from the Hoxhunt SCIM Attributes article. 
• Make sure you have selected SCIM as the data source for all user attributes you plan to provision to Hoxhunt.

4.2.1 Enabling New Optional Attributes

• Some of the optional attributes are not available as target attributes by default in the Hoxhunt application. 
• Title, customAttribute1-10, phoneNumbers and employmentStart need to be added to the attribute list before they can be used. 
• To edit the attribute list, you need to go to https://portal.azure.com/?Microsoft_AAD_Connect_Provisioning_forceSchemaEditorEnabled=true and then navigate back to the Hoxhunt enterprise application's attribute mappings.

• Scroll down and click "Show advanced options" and select "Edit attribute list for Hoxhunt".

  

• Add the target new attribute to the list and Save.

• Target attributes for Title, customAttribute1-10, phoneNumbers and employmentStart 
  • title
  • urn:ietf:params:scim:schemas:extension:hoxhunt:2.0:User:customAttribute1
  • phoneNumbers[type eq "work"].value
  • urn:ietf:params:scim:schemas:extension:hoxhunt:2.0:User:employmentStart

• Go back to attribute mappings and add the mapping by clicking "Add new mapping"

  IMPORTANT: Make sure you have selected SCIM as the data source for all user attributes you plan to provision to Hoxhunt.

• After you have reviewed the attribute mappings and done the changes, click Save and go back to Provisioning page.
• Link to Microsoft article about customizing the attribute mappings: Tutorial - Customize user provisioning attribute-mappings for SaaS applications in Microsoft Entra ID

5. Select provisioning scope and status

• Select if you want to Sync only assigned users and groups or Sync all users and groups.
• Hoxhunt recommends using Sync only assigned users and groups. This way only users who are assigned to the Hoxhunt application will be provisioned. 
• 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.
• Set a notification email address to receive notifications if provisioning is broken. It won't notify you of individual user provisioning errors.

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

   

• 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.
  • SCIM - Disclaimer: Provisioning doesn't automatically start adaptive phishing training for new users who would be eligible for it. 
    • Simply provisioning a new user to Hoxhunt doesn't automatically trigger Hoxhunt adaptive phishing training to start. Please use Hoxhunt Admin portal to automatically enroll the new users to adaptive phishing training periodically.

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

6.1 Test the user assignment

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

6.2 Which assignment method should I use?

Option 1: Group-based assignment (RECOMMENDED)

• We strongly recommend to create Entra ID group(s) for your Hoxhunt users.
• 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.
• 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 recognized as employees. The best way to pick up only employee accounts depends on your AAD structure.
• Group-based assignment requires Microsoft Entra ID Premium P1 or P2 edition. Nested group memberships and Microsoft 365 groups are not currently supported. 
  • User assignment: https://learn.microsoft.com/en-us/entra/identity/enterprise-apps/assign-user-or-group-access-portal
  • Dynamic membership rules: https://learn.microsoft.com/en-us/entra/identity/users/groups-dynamic-membership

Option 2: Scoping filters

• 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.
• 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. 
• Read more about scoping filters: https://learn.microsoft.com/en-us/entra/identity/app-provisioning/define-conditional-rules-for-provisioning-user-accounts

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!

Troubleshooting & Further Reading