Configuring Azure AD SSO and SCIM

Introduction

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

 

Before you start

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

  • You have an Azure AD tenant

  • You have a user account in Azure AD 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 Azure subscription includes support for assignment groups.
  • You know which users or groups you need to assign to Hoxhunt Azure AD 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 Azure AD 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 Azure AD 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 Azure AD 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 Azure Gallery

1.1. Log in to your Azure AD 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 Azure AD 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).

SSO_-_Retrieve_ACS_Url__Entity_ID_.png

3.3. Go back to Azure AD and open the new Hoxhunt Azure AD 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.

basic_saml.png

 

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

 

sso_claims_2.PNG

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.

clear_namespace.PNG

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:

SSO_claims.png

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.

 

sss_mail_as_source.PNG

 

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.

sso_cert_url.png

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.

SSO_-_Enter_SSO_URL.png

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

SSO_-_Enter_certificate.png

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 as follows:

  1. by clicking Test SSO integration button in Single Sign-On page in the Admin Portal.
  2. 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.

SCIM_-_Retrieve_token.png

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.

SCIM_-_warning.png

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.

SCIM_-_Copy_token.png

 

9. Set Provisioning mode and credentials

9.1. Log in to your Azure AD 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.

 

provisioning_1.PNG

 

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.

provisioning_2.PNG

10.2. Edit the source and target attributes as needed.

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

provisioning_attributes_2.png

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. 

Suggested source attribute Technical target attribute User field in Hoxhunt Description
department urn:ietf:params:scim:schemas:extension:enterprise:2.0:User:department Department

User's department in Hoxhunt. Default source attribute in AD is department.

country addresses[type eq "work"].country Country

User's country in Hoxhunt. Default source attribute in AD is country.

physicalDeliveryOfficeName urn:ietf:params:scim:schemas:extension:enterprise:2.0:User:division Site

User's site in Hoxhunt. Default source attribute in AD is physicalDeliveryOfficeName

preferredLanguage preferredLanguage

UI language

Quest languages

User's language for Hoxhunt UI and training emails (English is always included by default).

This attribute is not visible on the list by default. Please see below how to add a new mapping.

city addresses[type eq "work"].locality

City

Users city in Hoxhunt.

Default source attribute in AD is city 

If you cannot find this, see Q&A at the end of this article

manager urn:ietf:params:scim:schemas:extension:enterprise:2.0:User:manager

Manager

Users manager in Hoxhunt

Default source attribute in AD is manager

 

If you cannot find this, see Q&A at the end of this article

 

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 Azure AD's preferredLanguage as source attribute which contains the user's preferred language in Microsoft 365.

  • Select preferredLanguage as Target attribute
  •  

language_attribute.png

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 Azure AD 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.

provisioning_scope.PNG

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 Azure AD 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 Azure AD.
  • If user's data has not changed in Azure AD, 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. Azure AD 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 Azure AD. This means that if an end user has manually updated their settings to differ from what is attributed to them in Azure AD, 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 Azure AD to Hoxhunt will only make sure the value defined in Azure AD 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 Azure 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 Azure AD 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 Azure AD 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. 

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 Azure AD 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.
  • Login process always takes me back to Hoxhunt login page.

 

16. Troubleshooting SCIM

If you are experiencing issues with Hoxhunt SCIM provisioning, it's a good idea to first check the provisioning logs in Azure AD 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 Azure 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 Azure AD. 

 

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

 

Frequently asked questions

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

A: If your Azure AD 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 Azure AD, 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.

Was this article helpful?

2 out of 2 found this helpful

Have more questions? Submit a request