This guide tells you how to configure Single Sign-On (SAML) in your Active Directory Federation Services (AD FS) 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/.
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.
Before you start
Before you start configuring AD FS SSO for Hoxhunt, make sure you meet the following requirements:
you have access to AD FS 2.0 Console or later
you have Admin access to Hoxhunt
you know which users or groups you need to assign to Hoxhunt SSO.
1. Obtain HTTP Endpoint and certificate
Obtain your Saml 2.0 HTTP endpoint URL and X.509 certificate from your IdP metadata as follows:
1.1. Locate your AD FS Federation Metadata file URL on the AD FS server through the AD FS Management in AD FS > Service > Endpoints and go to section Metadata. It should look like this:
1.2. Open the FederationMetadata.xml file.
Endpoint URL is found at SingleSignOnService Location (e.g. https://sts.yourdomain.com/adfs/ls/).
Certificate is found under KeyDescriptor use="signing" at X509Certificate.
See below for guidance.
2. Configure SSO in Hoxhunt Admin Portal
2.1. Go to Single Sign-On in Hoxhunt Admin Portal.
2.2. Paste your Endpoint URL to the SAML 2.0 endpoint (HTTP) field.
2.3. Reformat your X.509 certificate e.g. with free online tool like https://www.samltool.com/format_x509cert.php
2.4. Paste your X.509 certificate (including -----BEGIN CERTIFICATE----- and -----END CERTIFICATE----- to the Public certificate field.
3. Configure SSO in AD FS Console
3.1. While still in Hoxhunt Admin Portal, copy the ACS Url (Entity ID).
3.2. Switch to the AD FS 2.0 Console, under Actions, select Add Relying Party Trust....
3.3. This will take you to the Add Relying Party Trust Wizard.
3.4. In the Select Data Source section, select Enter data about the relying party manually.
3.5. In the Specify Display Name section, enter Hoxhunt Login to Display name field.
3.6. In the Choose Profile section, choose AD FS 2.0 profile or AD FS profile.
3.7. In the Configure Certificate section, do not specify a token encryption certificate
3.8. In the Configure URL section, check the option Enable support for the SAML 2.0 Web SSO protocol. Enter the ACS Url you obtained from Hoxhunt Admin Portal to Relying party SAML 2.0 SSO service URL field.
3.9. In the Configure Identifiers section, add the same ACS Url you used in previous step to the Relying party trust identifier field and click Add.
If displayed, please skip Configure Multi-factor Authentication Now? section.
3.10. In the Choose Issuance Authorization Rules section, select Permit all users to access this relying party.
3.11. No changes are needed in the Ready to Add Trust section.
3.12. In the Finish section, check the option Open the Edit Claim Rules dialog for this relying party trust when the wizard closes.
3.13. Next you'll be taken to the Edit Claim Rules for Hoxhunt Login panel. From the Issuance Transform Rules tab, click Add Rule...
3.14. From the Choose Rule Type section, select Send LDAP Attributes as Claims from the Claim rule template drop-down menu, and then click Next.
3.15. From the Configure Claim Rule section, under Claim rule name, type Email LDAP query. Under Attribute store, select Active Directory.
Under mapping of LDAP attributes to outgoing claim types, map LDAP Attribute E-Mail Addresses to Outgoing Claim Type E-Mail Address.
Click Finish or OK to save the Claim Rule.
3.16. Additionally, Add following extra data mappings. Below are the Outgoing claim types.
(Note: Specific LDAP attributes may vary depending on your LDAP configuration.)
user.firstname <-- mandatory
user.lastname <-- mandatory
3.17. Add another rule from the Edit Claim Rules for Hoxhunt Login panel.
In Choose Rule Type section, select Transform an Incoming Claim from the Claim rule template drop-down menu.
3.18. From the Configure Claim Rule section, type the following Claim rule name:
Transform email address as NameID
Set the rule values:
- For Incoming claim type, select E-Mail Address.
- For Outgoing claim type, select Name ID.
- For Outgoing name ID format, select Email.
- Select Pass through all claim values.
3.19. At this point, you should be back at the Edit Claim Rules for Hoxhunt Login window.
Click Apply, then OK.
4. Test SSO integration
After completing step 3 above, test SSO by logging in to Hoxhunt via https://game.hoxhunt.com with a Incognito/InPrivate browser window.