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:
- Add the Greenhouse Recruiting application to your IdP.
- Upload (or manually enter) IdP metadata to Greenhouse Recruiting.
- Soft-enable and test SSO login.
- Hard-enable SSO.
In this article, we will cover:
Prepare Greenhouse Recruiting to Integrate with Sign-On Provider
To begin the process of enabling a new SSO configuration, have a user with the Developer Permission Can manage and configure SSO click the Configure icon in the upper right-hand corner and navigate to Dev Center in the left-hand panel.
On the subsequent page, click Single Sign-On.
From the Single Sign-On page, click Begin Configuration.
Greenhouse Recruiting will auto-populate the Assertion Consumer URL field. Click the Copy button next to the SSO Assertion Consumer URL field and save the information to provide to your SSO provider.
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, please see the following Help Center 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 Help Center 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 your metadata XML file, or
- Manually enter metadata details
If your SSO provider has issued you a metadata XML file, you can upload that file in 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
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://.
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 pictured below.
Note: Both SHA-256 and SHA-1 are accepted for the Fingerprint, but we recommend SHA-256.
Greenhouse Recruiting uses Email Address as the default employee login method. Organizations with an Expert subscription have the option to use Employee ID for the employee login method instead. To learn more about using Employee ID to log in, click here.
When finished, confirm you have entered the correct details in all fields, then move on to the next section.
Test Single Sign-On Configuration in Soft-Enabled State
After you have entered the the metadata XML information and confirmed it is correct, click the Begin Testing button at the bottom right of the page.
Note: Once you begin testing your SSO configuration, users will have the option to log into Greenhouse Recruiting either using your SSO Identity Provider (IdP) or using a Greenhouse Recruiting password. Users will no longer be able to sign into Greenhouse Recruiting via the Sign in with Google button. Users who do not have a Greenhouse Recruiting password may set one by clicking the Forgot Password button on the Greenhouse Recruiting login page. Once you have confirmed all users can log in via SSO, you can require all users to log in using SSO moving forward by finalizing your SSO configuration.
In the subsequent dialog box, click Proceed.
Once you click Begin Testing, your Greenhouse Recruiting account will be in a soft-enabled SSO state. Use this testing state to ensure all users can log in via SSO, and that no service interruptions occur. We recommend keeping your account in a soft-enabled state only as long as is necessary to test SSO functionality. While you are in this soft-enabled state, you will see your Single Sign-On Status reflected as In testing.
Note: Once SSO is hard-enabled, users can only sign into your Greenhouse Recruiting account using Single Sign-On. Any third-party vendors who might currently access your account with an email address and password will be unable to sign in unless they are added to your IdP, as email/password login is not supported for any users once your SSO configuration is hard-enabled. If your team works with third-party vendors, prior to hard-enabling your SSO configuration, we recommend connecting with those vendors and your internal IT team to ensure the vendors will have supported a log-in option.
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
Once your team has confirmed users can log in via SSO without issue, return to the Single Sign-On page and click Finalize Configuration to move to a hard-enabled state.
Note: Once your team hard-enables SSO, all user passwords will be deleted from Greenhouse Recruiting and cannot be recovered. Should your team remove 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.
Your Single Sign-On Status will update to Configured.
Your Single Sign-On configuration is complete.
Update Single Sign-On Configuration
Should your team need to edit your SSO configuration later, 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.
Make any necessary changes. Click Save at the bottom of the page when finished.