Configure Single Sign-On (SSO) in 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 complete the following steps: 

  1. Add the Greenhouse Recruiting application to your IdP.
  2. Upload (or manually enter) IdP metadata to Greenhouse Recruiting. 
  3. Soft-enable and test SSO login. 
  4. 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 Configure.png icon > Dev Center > Single Sign-On) and click Copy next to the Assertion URL field.

Screenshot-of-copy-URL-button.png

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

Note: See 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-step-3-fields.png

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-and-employee-method.png

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.png

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://.

mceclip1.png

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.png

In the subsequent dialog box, click Proceed

Screenshot-of-begin-testing-window.png

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-in-testing-stage.png

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.png

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.png

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

Screenshot-of-finalize-window.png

When it's complete, your Single Sign-On Status will update to Configured.

Screenshot-of-configured-status.png

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.png Dev Center Single Sign-On) and click Edit at the top-right corner of the page. 

Screenshot-of-edit-button-after-configuration.png

Make any necessary changes. Click Save at the bottom of the page when finished.