Single Sign-On (SSO) with OAuth 2.0

Updated 2 weeks ago by Michael Cretzman

Harness supports Single Sign-On (SSO) with OAuth 2.0 Identity Providers, such as Azure, Google, LinkedIn, GitHub, Bitbucket, and GitLab. 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 Google, GitHub, or other provider email address.

Currently, Harness uses OAuth 2.0 for authentication only. No Identity Provider roles are used for Harness authorization. Authorization will be added soon. For information on Harness RBAC, see Managing Users and Groups (RBAC).

Intended Audience

  • Developers
  • DevOps
  • Identity Management Engineers

Before You Begin

Requirements

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 be registered with Bitbucket using JohnOAuth20@outlook.com also.

Setup Overview

Only Harness Users that are members of the Harness Administrators group may set up and enable OAuth 2.0 SSO.

Setting up Harness OAuth 2.0 SSO involves the following high-level steps:

  1. Ensure 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 holds true for users you plan to invite to Harness after you enable Harness OAuth 2.0 SSO.
  2. Select the OAuth 2.0 provider to use for SSO.
  3. Enable Harness OAuth 2.0 SSO.
  4. Test SSO by having a user log into Harness using the 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 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 rovider you plan to use for SSO.

If you accidentally get locked out of Harness, email support@harness.io, call 855-879-7727, or contact Harness at harness.io/contact.

Set Up OAuth 2.0 SSO

To set up OAuth 2.0 SSO, do the following:

  1. Log into Harness using a Harness User account that is a member of the Administrator User Group. For information on Harness RBAC, see Managing Users and Groups (RBAC).

    The email address used to log into Harness should also be registered with the OAuth 2.0 Provider you intend to use for Harness SSO.
  2. Click Continuous Security, and then click Access Management. The Access Management page appears.



    Here you can see two Users and the SSO Provider Setup section. Before you set up SSO, confirm that your users' email addresses are the same email addresses they use to log into the OAuth 2.0 Provider you intend to use for Harness SSO.
  3. Click Users. The Users page appears.



    Here we see that the user we want to log in using OAuth 2.0 SSO, johnoauth20@outlook.com, and has an Outlook.com email address.
  4. Confirm that the email address(es) used to register Harness Users is also the email address they use to log into the OAuth 2.0 provider you plan to use for SSO.

    In this case, we are going to use Bitbucket for SSO, so let's confirm that the johnoauth20@outlook.com email address is used to log into Bitbucket.


    Email address confirmed. Now you are all set to add and enable Harness OAuth 2.0 SSO.
  5. In Harness Manager, click the drop-down menu next to the Users breadcrumb and select SSO Provider Setup.



    The SSO Provider Setup page appears.



    Now we will add Bitbucket as the OAuth 2.0 SSO provider.
  6. Click Add SSO Provider, and select OAuth 2.0.


    The SSO Providers list appears.



    This dialog will change as more OAuth 2.0 providers are added.
  7. Click the OAuth 2.0 provider you want to use for SSO. For our example, we will use Bitbucket.
  8. Click SUBMIT. The OAuth 2.0 provider is displayed as an SSO option.



    The URL displays the login link you can send to a Harness User, but the recommended method is for a Harness User to login from the Harness log in page.
  9. To enable the SSO provider, click the Enabled checkbox. A confirmation dialog appears.

    The confirmation dialog reminds you that Harness Users must have registered with Harness using an email address. Their email addresses will be used with the SSO provider you enabled. Please verify that Harness Users have registered with the same email addresses they use with the SSO provider.
  10. Click CONFIRM. The SSO provider is enabled and the Current Sign In Method changes to OAuth 2.0.

OAuth 2.0 SSO is now the login method for your Harness account. Before you log out of Harness, test the OAuth 2.0 SSO using a Harness User account.

Logging in with 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 and 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 John OAuth20 is registered in Harness with the email address johnoauth20@outlook.com:

The email address johnoauth20@outlook.com is also registered with Bitbucket:

And Bitbucket is enabled as the Harness SSO Provider:

John OAuth20 logs into Harness with the email address johnoauth20@outlook.com:

When he clicks NEXT, the browser is redirected to the Bitbucket website:

John enters in his johnoauth20@outlook.com email address and clicks Continue. Next, he enters in his Bitbucket password and clicks Continue.

Bitbucket verifies the email address and password and returns the browser to Harness, where John OAuth20 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 the OAuth 2.0 SSO identity provider. You can limit which email domain names may be used to log into Harness using OAuth 2.0 SSO.

For example, you might set up Google as the OAuth 2.0 SSO provider in Harness, but you only want users that have example.io in their login email address to be able to log in via Google.

To limit domain names in Harness OAuth 2.0 SSO, do the following:

  1. Log into Harness using a Harness User account that is a member of the Administrators User Group. For information on Harness RBAC, see Managing Users and Groups (RBAC).
  2. Click Continuous Security, and then click Access Management. The Access Management page appears.

  3. In SSO Provider Setup, click the SSO provider. The SSO Provider Setup page appears.
  4. Next to the SSO provider, click the vertical ellipsis and then click Edit.

    The Single-Sign On (SSO) Provider dialog appears.
  5. Click the checkbox next to Limit email addresses to specific domains only.

  6. In Domain Name(s), enter the domains that you want to allow to log into Harness. A domain name comes after the @ symbol in the email address, such as example.com. Multiple domain names can be entered, separated by commas.
  7. Click SUBMIT. The SSO login is now limited to email addresses containing the domains you entered.

Next Steps


How did we do?