Single Sign-On (SSO) with OAuth
Harness supports Single Sign-On (SSO) with OAuth 2.0 identity providers, such as GitHub, Bitbucket, GitLab, LinkedIn, Google, and Azure. This integration allows you to use an OAuth 2.0 provider to authenticate your Harness Users.
Once OAuth 2.0 SSO is enabled, Harness Users can simply log into Harness using their GitHub, Google, or other provider's email address.
In this topic:
- Before You Begin
- Setup Overview
- Set Up OAuth 2.0 SSO
- Log In With An OAuth 2.0 Provider
- Limit OAuth 2.0 SSO Domain Names
- Next Steps
Before You Begin
- See Authentication Overview.
- See Access Management (RBAC) Overview.
- For information on OAuth 2.0 see OAuth 2 Simplified from Aaron Parecki.
To set up OAuth 2.0 successfully, the following requirements should be met:
- Each Harness User should be registered with Harness using their email address. Users are registered once they have logged into Harness. Harness Users are required to register the first time they log into Harness.
- A Harness User's email address should also be used to authenticate with the OAuth 2.0 provider you plan to enable in Harness for SSO.
For example, if a Harness User is registered with Harness using the email address JohnOAuth20@outlook.com, and OAuth SSO is enabled in Harness using Bitbucket as the provider, then the user must also be registered with Bitbucket using JohnOAuth20@outlook.com.
GitHub Primary Email Required For Harness Login
GitHub supports primary and secondary email addresses:
If you use GitHub for Harness OAuth 2.0 SSO with Harness, the primary email must be used for the Harness account and login.
Setting up Harness OAuth 2.0 SSO involves the following high-level steps:
- Ensure that the email addresses of registered Harness Users are also registered with the OAuth 2.0 provider you will use for Harness OAuth 2.0 SSO. This applies to all users you plan to invite to Harness after you enable Harness OAuth 2.0 SSO.
- Enable Harness OAuth 2.0 SSO, and select the OAuth 2.0 providers to use for SSO.
- Test SSO by having a user log into Harness using each enabled OAuth 2.0 provider.
How Do I Prevent Lockouts?
The following steps can help you prevents lockouts when setting up SSO in Harness:
- When you enable OAuth 2.0 SSO, using a Harness User account that is a member of the Administrator Group, remain logged in until you have tested SSO using a separate User account. If there is any error, you can disable OAuth 2.0 SSO.
- Ensure that one or more Harness Users in the Administrators Group are registered with Harness using the same email address they use to log into the OAuth 2.0 provider you plan to use for SSO. Repeat this test for each enabled OAuth 2.0 provider.
Harness Local Login
To prevent lockouts or in the event of OAuth downtime, a User in the Harness Administrators Group can use Local Login to log in and update the OAuth settings.
- Click Harness Local Login.
- Change the settings to enable users to log in.
Set Up OAuth 2.0 SSO
To set up OAuth 2.0 SSO, do the following:
- Log into Harness using a Harness User account that is a member of the Administrator User Group with Create/Edit, Delete permissions for Authentication Settings. For information on Harness RBAC, see Access Management (RBAC) Overview.
The email address used to log into Harness should also be registered with the OAuth 2.0 providers you intend to enable for Harness SSO.
- Click Home, and then click Access Control under ACCOUNT SETUP. The Access Control page appears.
- In the Users tab, we can see the list of all the Active Users and their Email.
- Before you set up SSO, confirm that your users' email addresses registered with Harness are the same email addresses they use to log into the OAuth 2.0 provider you're enabling for Harness SSO.
- Click Authentication under ACCOUNT SETUP. The Authentication: Configuration page appears.
- If it's not already enabled, enable Use Public OAuth Providers.
- Enable each public OAuth 2.0 provider you want to use for SSO.
Log In With An OAuth 2.0 Provider
The first time a user logs into Harness using OAuth 2.0 SSO, they will be redirected to the OAuth 2.0 provider. The user will enter the same email address they used for Harness, along with the OAuth 2.0 provider-specific password. Next, they are redirected back to Harness and automatically logged in.
For all future logins, if the user is already logged into their OAuth 2.0 provider in the same browser as Harness, they will simply enter their email address in Harness and log in automatically.
Let's look at an example:
The Harness user ExampleUser is registered in Harness with the email address exampleharnessUser@gmail.com:
The email address exampleharnessUser@gmail.com is also registered with Google:
And Google is enabled as the Harness SSO provider.
ExampleUser logs into Harness with the email address exampleharnessUser@gmail.com:
When the user clicks Google, the browser is redirected to the Google website:
The user enters his exampleharnessUser@gmail.com email address and clicks Next. Then, he enters his Google password and clicks Next.
Google verifies the email address and password and returns the browser to Harness, where Example User is logged in automatically.
Harness OAuth 2.0 login successful!
Limit OAuth 2.0 SSO Domain Names
By default, any member invited to Harness by a Harness Administrator can log in using an OAuth 2.0 SSO identity provider that's enabled on Harness. However, you can limit which email domain names can be used to log into Harness.
For example, you might set up Google as a Harness OAuth 2.0 SSO provider, but you want only users who have example.io in their (login) email address to be able to log in via Google.