Configure single sign-on (SSO) for Greenhouse Recruiting

Permissions: Basic users and above who can manage and configure SSO

Product tier: Available for Advanced and Expert subscription tiers

Greenhouse Recruiting provides your team with the ability to log in via single sign-on (SSO). With SSO enabled, your users can access your organization’s Greenhouse Recruiting account through your Identity Provider (IdP) of choice.

Enabling SSO requires your team to add the Greenhouse Recruiting application to your IdP; upload (or manually enter) IdP metadata to Greenhouse Recruiting; soft-enable and test SSO login; and finally, hard-enable SSO.

Retrieve your Assertion Consumer URL from Greenhouse Recruiting

Note: You must have the user-based permission can manage and configure SSO to complete this process. Click here for more information on updating your permissions.

Navigate to the Single sign-on page. (Configure icon > Dev Center > Single sign-on) and click Copy next to the Assertion URL field.

Screenshot of assertion url copy button

Note: Custom subdomains are not supported for new SSO configurations. Your organization must use the auto-generated SSO Assertion Consumer Service (ACS) URL provided.

To learn more about the ACS URL value, see the following article: Assertion Consumer URL and Entity Issuer Fields

Add Greenhouse Recruiting to single sign-on provider

The next step is to add the Greenhouse Recruiting application to your Identity Provider; this process will vary based on your IdP.

The following article includes links to step-by-step guides for completing this process with IdPs that offer preconfigured integrations with Greenhouse Recruiting, as well as general guidelines for integrating with other IdPs: Use single sign-on (SSO) with Greenhouse Recruiting

Add Identity Provider (IdP) metadata to Greenhouse Recruiting

Once you have added Greenhouse Recruiting to your IdP, you next will add your single sign-on metadata information to Greenhouse Recruiting. This information is provided to you by your IdP, and can be added to Greenhouse Recruiting in one of two ways:

Upload metadata XML file

If your SSO provider has issued you a metadata XML file, you can upload that file to Greenhouse Recruiting to populate configuration information automatically.

To upload a metadata file, on the single sign-on page, click the Choose File button.

Screenshot-of-choose-file-button.png

Uploading the metadata XML file will assist with auto-populating the following information:

  • Entity ID / Issuer
  • Single sign-on URL
  • Single logout URL (optional)
  • Name Identifier Format
  • IdP Certificate Fingerprint

If you're using AzureAD as your SSO provider, you'll need to select one of the following Name Identifier Formats that are accepted by AzureAD:

  • urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress
  • urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified
  • urn:oasis:names:tc:SAML:2.0:nameid-format:persistent
  • urn:oasis:names:tc:SAML:2.0:nameid-format:transient

Note: Check out the following sections for more information on specific setup cases:

Manually upload metadata details

If you do not have a metadata XML file, or prefer to enter these details manually, you can do so by typing the requested information in the fields under step 3 on the page.

Screenshot of information fields

Note: Both SHA-256 and SHA-1 are accepted for the Fingerprint, but we recommend SHA-256.

Choose name identifier format and employee login method

Select your name identifier format and Employee login method from the dropdown menus.

Screenshot of name identifier fields

Note: Organizations with an Expert subscription have the option to use Employee ID for the employee login method instead of an email address.

When you're finished, click Begin Testing.

Screenshot of begin testing button

Alternative setup: modifying Entity ID values

Some XML files populate the correct Entity ID, and some need to be modified after uploading. If you use Okta or OneLogin, leave the Entity ID / Issuer value as-is after the upload is complete.

If you use any other IdP (e.g. Google, Azure, ADFS, or something else), update the Entity ID to greenhouse.io. Please note there is no https://.

Screenshot of entity id greenhouse field

Alternative setup: manually adding your Name Identifier format

If you manually updated the SSO fields without uploading the metadata XML file, the Name Identifier format won't be automatically generated. In this case, you can use the following Name Identifier format unless otherwise directed by your identity provider: urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress .

Note: The SAML:1.1 value in the naming format above is part of the SAML 2.0 specifications (section 8.3.2) and is not an indication that the format uses an older version of SAML. Since Greenhouse Recruiting only allows the email address to be specified as the NameID, the persistent and transient NameID formats won't function when sending a request to Greenhouse Recruiting.

Complete a preliminary test of single sign-on using a soft-enabled configuration

Initially, single sign-on should be tested in a soft-enabled state. When it is soft-enabled, users can choose to log in with SSO or their old username and password.

During the initial testing stages, you'll want to still allow users to sign in with their old username and password to ensure your users can still access Greenhouse Recruiting while you address any configuration issues with the current setup.

To test your setup, click Begin Testing on the bottom of the single sign-on page. Screenshot of begin testing button

In the subsequent dialog box, click Proceed.

Screenshot of testing window

Your organization will be updated to a soft-enabled configuration. While you are in this soft-enabled state, you will see your single sign-on Status reflected as In testing.

Screenshot of testing status

If your team finds any changes need to be made to your SSO configuration, click the Edit button to make the required changes. Be sure to click Save Changes when you finish editing.

Screenshot of edit button

Finalize configuration and move to hard-enabled state

When single sign-on is hard enabled, your users will only be able to log in with their SSO credentials. After you've tested the soft-enabled configuration and are confident that it is functioning correctly, you can move it to a hard-enabled state.

Note: Any third-party vendors who might currently access your account with an email address and password will be unable to sign in to Greenhouse Recruiting unless they are added to your IdP.

If your team works with third-party vendors, we recommend connecting with those vendors and your internal IT team to ensure the vendors will have supported a log-in option before switching to the hard-enabled state.

Important note

Once your team hard-enables SSO, all user passwords will be deleted from Greenhouse Recruiting and cannot be recovered. If your team removes its SSO configuration in the future, every user must request a password reset email and create a new password to regain access to Greenhouse Recruiting.

Finalize configuration

Once your testing is complete and you have read the information above, return to the single sign-on page and click Finalize Configuration.

Screenshot of finalize configuration button

Verify that you'd like to finalize the configuration by typing Configure into the field and clicking Finalize.

Screenshot of finalize configuration pop up window

When it's complete, your single sign-on Status will update to Configured.

Screenshot of configured SSO status.

Update single sign-on configuration

If you need to edit your SSO configuration at a later time (such as to update a certificate or change your IdP) return to the single sign-on page (Configure Configure icon > Dev Center > single sign-on) and click Edit at the top-right corner of the page.

Screenshot of edit button after configuration

Make any necessary changes.

When finished, click Save.

Remove single sign-on configuration

To deactivate SSO, open a ticket with the Greenhouse Technical Support team.

Once SSO is deactivated, each user at your organization must request a password reset through email and create a new password to regain access to Greenhouse Recruiting. To learn more, click here.