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.
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.
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.
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.
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.
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://.
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.
In the subsequent dialog box, click Proceed.
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.
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.
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.
Verify that you'd like to finalize the configuration by typing Configure into the field and clicking Finalize.
When it's complete, your single sign-on Status will update to Configured.
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 > Dev Center > single sign-on) and click Edit at the top-right corner of the page.
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.