Skip to main content

Advanced SAML configuration

Last updated on

Once SAML SSO is in place, additional configuration may be required to meet security requirements. For example, an identity provider (IdP) outage can lock users out of Harness, unencrypted SAML assertions may not adhere to your organization's compliance policies, and teams with different workflows may need to land on different parts of the product after login.

This page covers advanced SAML configuration options in Harness, including local login fallback, encrypted SAML assertions, and setting the default UI experience for your users.

note

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:

Before you begin​

Before you begin, ensure you have:

  • A Harness account with Account Admin permissions to modify authentication settings.
  • An active SAML SSO provider already configured in Harness (such as Okta, Microsoft Entra ID).

Harness Local Login​

To prevent lockouts or in the event of OAuth downtime, you can use the local login URL https://app.harness.io/auth/#/local-login to sign in to your default account and update the OAuth settings.

You can use the local login URL only if you have the admin role assigned on All Account Level Resources or All Resources Including Child Scopes.

Local login authenticates against a Harness-native username and password, not your SSO identity provider. Your IdP is never contacted for this sign-in, which is why local login continues to work during an OAuth or SAML outage.

If you belong to multiple accounts, confirm the default account is set before attempting to use Harness Local Login.

For example, for the Harness production cluster prod-3, the local login URL is https://app3.harness.io/auth/#/local-login. Once you login, you can change the settings to enable users to log in.

Disable local login​

To disable Local login, use the DISABLE_LOCAL_LOGIN feature flag. Contact Harness Support to enable the feature flag.

Use encrypted SAML​

To use encrypted SAML with Harness, you download the encryption certificate from the Harness UI and upload it to your identity provider (IdP) settings to support the encrypted SAML flow.

To download your encryption certificate and upload it to your IdP settings, do the following:

  1. In your Harness account, go to Account Settings, and then select Authentication.

  2. Assuming you have a SAML provider set up, select your provider. Under Enable Authorization, click the Download button.

This downloads the Harness encryption certificate required for SAML assertions. 3. Sign in to your IdP (identity providers, such as Okta, Microsoft Entra ID). 4. To edit your SAML integration in the IdP:

  1. Enable assertion encryption.
  2. Select your encryption algorithm.
  3. Upload the encrypted certificate file you downloaded from the Harness UI in step 2 above.

When you sign in to Harness via SAML, the operation is completed using encrypted assertions.

Rotate your IdP signing certificate​

Harness reads your IdP's signing certificate from the metadata XML file you upload when you set up your SAML provider. When your IdP rotates its signing certificate, re-upload the current metadata XML to Harness to pick up the new certificate.

To avoid a login gap during rotation, Harness supports uploading metadata that lists more than one signing certificate: it validates a SAML response against any signing certificate present in the metadata. If your IdP's metadata carries both the current and next certificate during an overlap window, you can upload that metadata to Harness ahead of the cutover so logins keep working through the rotation.

Set the default experience​

When you log in through SAML, Harness redirects you to a default landing page. If your organization has teams that work in different modules (for example, developers in CI and operations in CD), account administrators or environment administrators (that is, users who have all the permissions required to work with environments) can set the default landing experience so each user lands on the relevant part of the product after login.

The following diagram shows the permissions required for environment administrator access.

To set the default landing page, follow the steps below:

  1. In your Harness account, go to Account Settings and select Account Details.
  2. Under Default Experience, select the experience you want users to see when they log in (First generation or next generation).
  3. Click Save. For more information on account-level settings, go to Account details.
Last updated on