Overview
Harness supports Single Sign-On (SSO) with SAML by integrating with your SAML SSO provider to enable you to log your users into Harness as part of your SSO infrastructure. This section explains how to set up SAML authentication.
If you use Harness Self-Managed Enterprise Edition , your instance must be accessed via an HTTPS load balancer. SAML authentication will fail over HTTP.
What will you learn in this topic?
By the end of this topic, you will be able to understand:
- How Harness supports SAML-based single sign-on and how to enable it as the default authentication method.
- XML SAML file format requirements used with Harness.
- How to use the System for Cross-domain Identity Management (SCIM) protocol with Harness to keep user group memberships continuously up to date.
- Key integration components required to integrate SAML SSO.
Before you begin
- A Harness account with admin permissions: You need permission to manage Authentication Settings. Go to Authentication overview for details.
- A SAML identity provider (IdP): Such as Okta, Microsoft Entra ID, OneLogin, or Keycloak, with admin access to configure a new application integration.
- Matching user accounts: Users must exist in both Harness and the SAML provider with the same email address before SSO can be enabled.
- At least two user accounts for testing: One Harness Administrator account to configure SSO and one regular user account to test the login flow.
Supported formats
The XML SAML file used with Harness must use UTF-8.
UTF-8 BOM is not supported. Some text editors like Notepad++ save in UTF-8 BOM by default.
When integrating users through any SAML provider, users added to an external SAML provider are not automatically synchronized with Harness user groups. Synchronization occurs upon the first login by the user belonging to a specific provider's user group into Harness. Only at this point will the newly added user, having logged in through SAML, inherit all permissions and access rights associated with the Harness group linked to the SAML-provider's user group.
Use System for Cross-domain Identity Management (SCIM) protocol
To ensure continuous and real-time synchronization of user group bindings and access controls, Harness recommends that you utilize the System for Cross-domain Identity Management (SCIM) protocol. SCIM enables real-time syncing of user additions with Harness user groups, ensuring that user permissions and access rights are consistently applied and maintained.
For implementation details on provisioning users with SCIM, go to Okta SCIM , Microsoft Entra SCIM , or OneLogin SCIM based on your SAML provider.
SCIM API integration settings
If you provision users and groups via SCIM API, use the following settings for your SAML integration.
- SCIM connector base URL:
https://app.harness.io/gateway/ng/api/scim/account/[YOUR_ACCOUNT_ID]. enter the appropriate URL for your cluster:
The base URL format will follow the following base format:
https://app.harness.io/gateway/ng/api/scim/account/[YOUR_ACCOUNT_ID], (e.g https://app.harness.io/gateway/ng/api/scim/account/9999aaaa9999AA)
However, this will need to be modified depending on which cluster your account exists within. You can verify this by going to your Account Settings -> Account Details, in the Harness Cluster Field.
| Cluster | URL Format |
|---|---|
| Prod1 | https://app.harness.io/gateway/ng/api/scim/account/[YOUR_ACCOUNT_ID] |
| Prod2 | https://app.harness.io/gateway/gratis/ng/api/scim/account/[YOUR_ACCOUNT_ID] |
| Prod3 | https://app3.harness.io/gateway/ng/api/scim/account/[YOUR_ACCOUNT_ID] |
| Prod0/Prod4 | https://accounts.harness.io/gateway/ng/api/scim/account/[YOUR_ACCOUNT_ID] |
| EU clusters | https://accounts.eu.harness.io/ng/api/scim/account/[YOUR_ACCOUNT_ID] |
Please note that if customers select the incorrect cluster, the changes will not show up within their environment, even if there is a successful response from Harness.
If you environment is On-Prem (SMP) the URL will use your custom domain name and omits gateway.
For example, if your On-Prem domain name is harness.mycompany.com, then your SCIM base URL would become https://harness.mycompany.com/ng/api/scim/account/[YOUR_ACCOUNT_ID].
- Unique identifier:
userName - Authentication Mode: HTTP Header
- Authorization:
<YOUR_SERVICE_ACCOUNT_TOKEN>
You must also do the following:
- Enable provisioning to Harness.
- Assign your user groups.
- Push your groups to Harness.
SAML SSO with Harness
To set up SAML SSO with Harness, you add a SAML SSO provider to your Harness account and enable it as the default authentication method.
The following elements are required to successfully connect Harness to your SAML provider:
- Harness User email addresses: Users are invited to Harness using their email addresses. Once they log into Harness, their email addresses are registered with Harness as Harness Users. To use SAML SSO, Harness Users must use the same email addresses to register in Harness and the SAML provider.
Ensure that you have at least two corresponding user accounts when setting up and testing SAML SSO in Harness. This allows you to set up the account with a Harness Administrator account and test it with a Harness user account.
- SAML provider user email addresses: To use the SAML provider to verify Harness Users, the email addresses used in the SAML provider must match the email addresses for the registered Harness Users you want to verify.
- Harness SAML Endpoint URL: This URL is where the SAML provider will post the SAML authentication response to your Harness account. This URL is provided by Harness in the Single Sign-On (SSO) Provider dialog. You enter this URL in your SAML SSO provider app to integrate it with Harness.
- SAML metadata file: This file is provided by your SAML provider app. You upload this file into the Harness Single Sign-On (SSO) Provider dialog to integrate the app with Harness.