This guide tells you how to configure Single Sign-On (SAML) and automatic user provisioning (SCIM) in your Azure AD for 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.
- Add Hoxhunt application from Azure Gallery
- Configure Single Sign-On (SSO)
- Configure automatic user provisioning (SCIM)
- Assign users to Hoxhunt application
- Further readings and troubleshooting
- An Azure AD tenant
- A user account in Azure AD with permissions to configure provisioning (for example, Application Administrator, Cloud Application administrator, Application Owner, or Global Administrator).
Add Hoxhunt application from Azure Gallery
Hoxhunt Azure AD enterprise application can be used for both Single Sign-On (SSO) and automatic user provisioning (SCIM). Hoxhunt application is preconfigured but you still need to do some changes that are described later in this article.
1. To add Hoxhunt enterprise application to your Azure AD, go to: Enterprise applications > All applications > New application.
2. Search for "hoxhunt". Select Hoxhunt application and click Create.
Now you are ready move forward configuring SSO and automatic user provisioning.
Configure Single Sign On
To start configuring SSO, go to your Hoxhunt Azure AD application (Add Hoxhunt application from Azure Gallery) and to Single sign-on page under Manage. Select SAML as single sign-on method.
1. Basic SAML configuration
1.1. Click Edit on Basic SAML Configuration
1.2. Add SAML consumer URL provided by Hoxhunt to Identifier and to Reply URL as in the picture. Add https://app.hoxhunt.com/ to Sign On URL. Click Save.
2. User Attributes and Claims
2.1. Click Edit on User Attributes and Claims.
2.2. Delete Claims for http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress and http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name by clicking the three dots and Delete
2.3. Click over http://schemas.xmlsoap.org/ws/2005/05/identity/claims/givenname
2.4. Clear everything from Namespace. Click Save.
2.5. Click over http://schemas.xmlsoap.org/ws/2005/05/identity/claims/surname
2.6. Clear everything from Namespace. Click Save.
2.7. Attributes and Claims should look like this after you have done editing:
OPTIONAL: If you are using Mail attribute instead of userPrincipalName as your main attribute for Hoxhunt users, you can change it by clicking on Unique User Identifier (Name ID). Change Source Attribute to user.mail.
3. Certificate and Login URL
You are almost done with configuring SSO!
Download SAML Signing Certificate by clicking Download button next to Certificate (Base 64). Send the certificate file to Hoxhunt Support or your Onboarding contact person together with Login URL found under Set up Hoxhunt.
TIP! You can either zip the file or remove ".cer" file type extension from the end the file name before sending to make sure it gets correctly delivered.
4. Assign a test user and test SSO
After the Login URL and certificate has been configured by Hoxhunt, assign your user account to the application (see Assign users to Hoxhunt application) and test SSO by logging in to Hoxhunt via https://game.hoxhunt.com via Incognito/InPrivate browser window.
How to renew SSO certificate
You should renew the SSO certificate before it expires to avoid any downtime in the SSO service. Please follow the instructions from Microsoft: https://docs.microsoft.com/en-us/azure/active-directory/manage-apps/manage-certificates-for-federated-single-sign-on#renew-a-certificate-that-will-soon-expire
When finished, please send the certificate to firstname.lastname@example.org and ask for SSO certificate renewal.
Configure automatic user provisioning (SCIM)
To start configuring automatic user provisioning go to your Hoxhunt Azure AD application (Add Hoxhunt application from Azure Gallery) and navigate to Manage > Provisioning. Then select Get started.
1. Set Provisioning mode and credentials
1.1. Change Provisioning Mode to Automatic.
1.2 Add Tenant URL (https://app.hoxhunt.com/services/scim)
and Secret Token provided by Hoxhunt.
1.3 Click Test Connection. Contact Hoxhunt Support if the connection test is not successful.
1.4 click Save.
2. Define attribute mappings
Review the user attributes that will be synced to Hoxhunt and change them if needed.
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.
2.1. Expand Mappings and click Provision Azure Active Directory Users.
2.2 Default attribute mappings are shown in the picture below.
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.
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:
- 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.
- NOTE: You can use either userPrincipalName or mail as source attribute depending on which works as the address where user can receive emails outside your organization.
- Not([IsSoftDeleted]) mapped to active:
- Do not change this mapping! This is related user's deactivation when user falls 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:
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.
You can delete any unused mappings if you don't need this data in Hoxhunt.
- User's department in Hoxhunt. Default source attribute in AD is department.
- addresses[type eq "work"].country:
- User's country in Hoxhunt. Default source attribute in AD is country.
- User's site in Hoxhunt. Default source attribute in AD is physicalDeliveryOfficeName.
- 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.
Add a new 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.
2.3. After you have reviewed the attribute mappings and done the needed changes, click Save and go back to Provisioning page.
3. Select provisioning scope and status
Select if you want to Sync only assigned users and groups or Sync all users and groups.
Preferred way is to Sync only assigned users and groups. This way only users who are assigned to the Hoxhunt application will be provisioned.
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. Discuss first with Hoxhunt Support if you are selecting this option.
Optionally, you can set a notification email address to receive notification is provisioning is broken. It won't notify of individual user provisioning errors.
You can toggle Provisioning Status to On after you have done the configuration.
Provisioned data overrides user-defined data
Each time provisioning runs, any user attribute such as country, department or preferredLanguage is 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.
Provisioning doesn't automatically invite or auto-start new users
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.
Assign users to Hoxhunt application
Next you need to assign users to Hoxhunt application or create Scoping filters to select users that you want to be provisioned. It is important to sync only employee accounts and exclude all non-user accounts and not wanted shared mailboxes from the provisioning scope.
You can assign users to the application by going to your Hoxhunt application and selecting Users and groups under Manage.
Add only few users to the Hoxhunt application first to test that provisioning and SSO works. Initial provisioning cycle should start in 40 minutes after you have turned provisioning on. After the initial provisioning cycle has completed, an incremental provisioning cycle will sync all users updates to Hoxhunt every 40 minutes.
You can also test provisioning using Provision on demand feature from Provisioning page to provision single user.
Ask Hoxhunt Support to confirm that test users have been synced correctly before assigning all users to the application.
To test SSO, add your user account to Hoxhunt application and test login via https://game.hoxhunt.com.
Group based assignment
Preferred way is to create Azure AD group for Hoxhunt users. You should include only employee accounts who are participating in the training and exclude non-user accounts. You can use either static or dynamic Azure AD group. 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 get only employee accounts depends on your AAD structure.
Scoping filters can also be used together with user assignment. User needs to be then assigned to application and also pass scoping filters to be in scope for provisioning.
Group-based assignment requires Azure Active Directory Premium P1 or P2 edition. Nested group memberships and Microsoft 365 groups are not currently supported.
Dynamic membership rules: https://docs.microsoft.com/en-us/azure/active-directory/enterprise-users/groups-dynamic-membership
With scoping filters you can filter the provisioned users based on Azure AD attributes. 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. If you set 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://docs.microsoft.com/en-us/azure/active-directory/app-provisioning/define-conditional-rules-for-provisioning-user-accounts
Further readings and troubleshooting
Contact Hoxhunt Support if notice any issues with SCIM provisioning. Below you can find links to articles that can help with troubleshooting.
- General information about automatic user provisioning.
- On-demand provisioning to test provisioning with a single user.
- Check the status of user provisioning.
- Provisioning logs.