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

Last updated: January 29, 2024

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

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, clickAccount Defaults.
Click theSecurity tab.
ClickSet up Single Sign-on.
In theSet up Single sign-onslide-in panel, clickMicrosoft AD FS.
Take note of both theAudience URI (Service Provider Entity ID)andSign 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 yourAD FSmanager, open theRelying Party Trusts (RPT)folder.
In the right sidebar menu, selectAdd Relying Party Trust....
In theAdd Relying Party Trust Wizarddialog box, clickStartto add a new RPT.
On theSelect Data Sourcescreen, selectEnter data about the relying party manually.
ClickNext >.
In theDisplay namefield, enter a name for your trust - this is for internal purposes, so make sure you name it something that you can easily recognize.
ClickNext >.
On theConfigure Certificatescreen, leave the default settings as they are, then clickNext >.
Select theEnable Support for the SAML 2.0 WebSSO protocolcheckbox. In theRelying party SAML 2.0 SSO service URL field, enter theSign on URL, ACS, Recipient or Redirect URL from your HubSpot account.

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

ClickNext >.
In theRelying party trust identifierfield:
- Enter theAudience URI (Service Provider Entity ID) value from your HubSpot account.
- Enter https://api.hubspot.com, thenclickAdd.
ClickNext >.
In theChoose an access control policywindow, selectPermit everyone, then clickNext >.
Review your settings, then clickNext >.
ClickClose.

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 Rulewindow, clickAdd Rule.
Click the Claim rule templatedropdown menu and select Send LDAP Attributes as Claims.
ClickNext >.
On theConfigure Claim Rulescreen:
- In the Claim rule namefield, enter a rule name.
- Click theAttribute storedropdown menu and selectActive Directory.
- In the Mapping of LDAP attributestable, map the following:
  - In the LDAP Attributecolumn, click thedropdown menuand selectEmail Addresses.
  - In the Outgoing ClaimTypecolumn, click thedropdown menuand selectEmail Address.
ClickFinish.

Next, set up the Transform an Incoming Claim rule:

ClickAdd Rule.
Click theClaim rule template dropdown menuand selectTransform an Incoming Claim.
ClickNext >.
On theConfigure Claim Rulescreen:
- Enter a claim rule name.
- Click theIncoming claim typedropdown menu and selectE-Mail Address.
- Click theOutgoing claim typedropdown menu and selectName ID.
- Click theOutgoing name ID formatdropdown menu and selectEmail.
- ClickFinishto add the new rule.
ClickOKto add both new rules.

3. Adjust the trust settings

In the Replying Party Trusts folder, select Properties from theActionssidebar menu. Click theAdvancedtab and make sureSHA-256is 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 totheAD FSmanagement window. In the left sidebar menu, navigate to Services>Certificates.
Locate theToken signingcertificate. Right-click the certificate and selectView Certificate.
In the dialog box, click theDetailstab.
ClickCopy to File.
In theCertificate Export Windowthat opens, clickNext.
SelectBase-64 encoded X.509 (.CER), then clickNext.
Give your file export a name, then clickNext.
ClickFinishto 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, clickAccount Defaults.
Click theSecurity tab.
ClickSet up Single Sign-on.
In theSet up Single sign-onslide-in panel, clickMicrosoft AD FS.
Paste the contents of the file into the X.509 Certificatefield.
Return to your AD FS manager.

In the left sidebar menu, select theEndpointsfolder.
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 theIdentity provider Identifier or Issuerfield, enter the entity URL.
In theIdentity Provider Single Sign-On URLfield, enter the SSO service URL.
ClickVerify.

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.