Set up single sign-on (SSO) using Active Directory Federation Services (AD FS)

If you have a HubSpot Enterprise account, you can set up single sign-on using Active Directory Federation Services (AD FS). 

To use AD FS to log in to your HubSpot account, you must meet the following requirements:

• All users in your Active Directory instance must have an email address attribute.
• You are using a HubSpot Enterprise account.
• You have a server running Windows Server 2008, 2012, or 2019. 

Please note: this setup process should be done by an IT administrator with experience creating applications in your identity provider account. Learn more about setting up SSO with HubSpot. 

Before you begin

Before you begin, take note of the following two values from your HubSpot account to set up SSO using Microsoft AD FS:

• Log in to your HubSpot account. 
• In your HubSpot account, click the settings settings icon in the top navigation bar.
• On the left sidebar, click Account Defaults. 
• Click the Security tab.
• Click Set up Single Sign-on.
• In the Set up Single sign-on slide-in panel, click Microsoft AD FS.
• Take note of both the Audience URI (Service Provider Entity ID) and Sign on URL, ACS, Recipient, or Redirect values as you will need to add them to Microsoft AD FS in the setup process. 

1.Add a Relying Party Trust (RPT)

Open your Active Directory Federation Services (AD FS) manager:

• In your AD FS manager, open the Relying Party Trusts (RPT) folder. 
• In the right sidebar menu, select Add Relying Party Trust.... 
• In the Add Relying Party Trust Wizard dialog box, click Start to add a new RPT. 
• On the Select Data Source screen, select Enter data about the relying party manually. 
• Click Next >.
• In the Display name field, enter a name for your trust - this is for internal purposes, so make sure you name it something that you can easily recognize. 
• Click Next >. 
• On the Configure Certificate screen, leave the default settings as they are, then click Next >.
• Select the Enable Support for the SAML 2.0 WebSSO protocol checkbox. In the Relying party SAML 2.0 SSO service URL field, enter the Sign on URL, ACS, Recipient or Redirect URL from your HubSpot account.

• Click Next >. 
• In the Relying party trust identifier field:
  • Enter the Audience URI (Service Provider Entity ID) value from your HubSpot account. 
  • Enter https://api.hubspot.com, then click Add. 
• Click Next >. 
• In the Choose an access control policy window, select Permit everyone, then click Next >. 
• Review your settings, then click Next >. 
• Click Close. 

2. Create claims rules 

Before setting up your claims rule, make sure that your users' email addresses match their HubSpot user email addresses. You can use other identifiers, such as the User Principal Name (UPN), if your UPNs are in the form of an email address. In order for single sign-on with AD FS to work, the nameID needs to be in the form of an email address in order to match with a HubSpot user. 

• In the Claims Rule window, click Add Rule. 
• Click the Claim rule template dropdown menu and select Send LDAP Attributes as Claims. 
• Click Next >. 
• On the Configure Claim Rule screen:
  • In the Claim rule name field, enter a rule name. 
  • Click the Attribute store dropdown menu and select Active Directory. 
  • In the Mapping of LDAP attributes table, map the following:
    • In the LDAP Attribute column, click the dropdown menu and select Email Addresses. 
    • In the Outgoing ClaimType column, click the dropdown menu and select Email Address. 
• Click Finish. 

Next, set up the Transform an Incoming Claim rule: 

• Click Add Rule. 
• Click the Claim rule template dropdown menu and select Transform an Incoming Claim. 
• Click Next >. 
• On the Configure Claim Rule screen:
  • Enter a claim rule name. 
  • Click the Incoming claim type dropdown menu and select E-Mail Address. 
  • Click the Outgoing claim type dropdown menu and select Name ID. 
  • Click the Outgoing name ID format dropdown menu and select Email. 
  • Click Finish to add the new rule. 
• Click OK to add both new rules. 

3. Adjust the trust settings

In the Replying Party Trusts folder, select Properties from the Actions sidebar menu. Click the Advanced tab and make sure SHA-256 is specified as the secure hash algorithm. Though both SHA-256 and SHA-1 are supported, SHA-256 is recommended. 

4. Locate your PEM format x509 certificate

To access your PEM format x509 certificate:

• Navigate to the AD FS management window. In the left sidebar menu, navigate to Services > Certificates. 
• Locate the Token signing certificate. Right-click the certificate and select View Certificate. 
• In the dialog box, click the Details tab. 
• Click Copy to File. 
• In the Certificate Export Window that opens, click Next. 
• Select Base-64 encoded X.509 (.CER), then click Next. 
• Give your file export a name, then click Next. 
• Click Finish to complete the export. 

• Locate the file you just exported and open it using a text editor, such as Notepad. 
• Copy the contents of the file.

5. Complete your set up in HubSpot

• Log in to your HubSpot account. 
• In your HubSpot account, click the settings settings icon in the top navigation bar.
• On the left sidebar, click Account Defaults. 
• Click the Security tab.
• Click Set up Single Sign-on.
• In the Set up Single sign-on slide-in panel, click Microsoft AD FS.
• Paste the contents of the file into the X.509 Certificate field. 
• Return to your AD FS manager. 

• In the left sidebar menu, select the Endpoints folder. 
• Search for SSO service endpoint and the entity URL. The SSO service URL usually ends in “adfs/services/ls” and the entity URL ends in “adfs/services/trust”.
• Return to HubSpot. In the Identity provider Identifier or Issuer field, enter the entity URL.
• In the Identity Provider Single Sign-On URL field, enter the SSO service URL. 
• Click Verify. 

Please note: if you receive an error when configuring single sign-on in HubSpot, check your event viewer logs on your device for the error message. If you are not able to troubleshoot the error message, contact HubSpot Support.