> For the complete documentation index, see [llms.txt](https://developer.harness.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developer.harness.io/harness-platform/3.0/harness-platform-resources/authentication/authentication-overview.md).

# Overview

Authentication in Harness controls who can access your account and how. The first layer of Harness access control includes:

* **Authentication:** Checks who you are.
* **Authorization:** Checks what you can do.
* **Auditing:** Logs what you do.

If you are in an Administrator group, you can use Authentication Settings to restrict access to an organization's Harness account. The options you choose apply to all account users.

This page covers ***authentication***. For information about ***authorization***, go to [RBAC in Harness](/harness-platform/3.0/harness-platform-resources/platform-access-control/rbac-in-harness.md).

***

### What you will learn in this topic <a href="#what-you-will-learn-in-this-topic" id="what-you-will-learn-in-this-topic"></a>

By the end of this topic, you will be able to understand:

* How to [configure authentication](#configure-authentication) methods for your Harness account, including [Harness login, OAuth](#enable-public-oauth-providers), Security Assertion Markup Language (SAML), and Lightweight Directory Access Protocol (LDAP).
* How to [enforce password policies](#enforce-password-policies), including [password strength requirements](#enforce-password-strength), [expiration intervals](#enforce-password-expiration), and [lockout rules](#enforce-lockout-after-failed-logins) after failed login attempts.
* How to set up [session timeouts](#set-inactive-session-timeout) (inactive) and [absolute session timeout](#set-absolute-session-timeout) to automatically log you out after inactivity or after an absolute time limit.
* How to restrict account access by [whitelisting specific email domains](#restrict-email-domains) and [enabling two-factor authentication](#enforce-two-factor-authentication) account-wide.
* [Audit logs for authentication events](#audit-logs-for-authentication), including how to identify and troubleshoot failed login attempts across all supported auth methods.

***

### Before you begin <a href="#before-you-begin" id="before-you-begin"></a>

* **Basic Harness navigation:** [Sign up or sign in to your Harness account](/harness-ai/new-to-harness-platform/get-started.md#step-1-access-your-harness-account).
* **Harness account hierarchy:** Authentication settings are configured at the account level and apply to all users. Understand the [account](/service-reliability-management/new-to-srm/get-started/key-concepts.md#account)/[organization/project](/service-reliability-management/new-to-srm/get-started/key-concepts.md#organizations-and-projects) hierarchy before proceeding.
* **Admin-level permissions:** Permission to create, edit, and delete Authentication Settings. Contact your administrator to get the required permissions.
* **RBAC concepts:** A general [understanding](https://www.harness.io/blog/user-role-management) of role-based access control, since authentication is one of the three aspects of Harness access control, and how [RBAC works in Harness](/service-reliability-management/new-to-srm/get-started/key-concepts.md#how-rbac-works-in-harness).
* **SSO familiarity:** Basic knowledge of what SAML, LDAP, and OAuth are, so you can choose the right method for your organization.

***

### Configure authentication <a href="#configure-authentication" id="configure-authentication"></a>

To configure authentication, follow the steps below:

1. In **Home**, select **Account Settings**, and then select **Authentication**.

   The **Authentication** page opens.
2. Select one of the following authentication methods to follow its configuration:
   * [Login via a Harness Account or Public OAuth Providers](#enable-public-oauth-providers): Authenticate using a Harness username/password or a connected OAuth provider such as GitHub, GitLab, Azure, and so on.
   * [Login via SAML](#enable-multiple-identity-providers): Authenticate through your organization's identity provider using SAML-based single sign-on.
   * [Login via LDAP](/harness-platform/3.0/harness-platform-resources/authentication/single-sign-on-sso-with-ldap.md#add-ldap-sso-provider): Authenticate using your organization's LDAP directory service with your corporate username and password.

***

### Enable public OAuth providers <a href="#enable-public-oauth-providers" id="enable-public-oauth-providers"></a>

You can use Harness logins with different single sign-on mechanisms by enabling the **Use Public OAuth Providers** under **Login via a Harness Account or Public OAuth Providers** and selecting individual OAuth partners (such as Azure, Bitbucket, GitLab, Github, and so on).

For more information, go to [Single Sign-On with OAuth](/harness-platform/3.0/harness-platform-resources/authentication/single-sign-on-sso-with-oauth.md).

#### Enforce password policies <a href="#enforce-password-policies" id="enforce-password-policies"></a>

Under **Password Policies**, configure the following requirements:

* **Enforce password strength:** Set minimum length and character requirements.
* **Periodically expire passwords:** Define how often passwords must be refreshed.
* **Enforce Two Factor Authentication:** Require 2FA as part of password policy enforcement.

#### Enforce password strength <a href="#enforce-password-strength" id="enforce-password-strength"></a>

1. Select **Enforce password strength** to open the dialog.
2. Specify and enforce any of the following options:
   * **Minimum password length:** Set the minimum number of characters required.
   * **Include at least one uppercase letter:** Require at least one capital letter.
   * **Include at least one lowercase letter:** Require at least one lowercase letter.
   * **Include at least one digit:** Require at least one number.
   * **Include at least one special character:** Require one or more of the following: `! @ # $ % ^ & * ( ) - _ = + \ | [ ] { } ; : / ? . >`

#### Enforce password expiration <a href="#enforce-password-expiration" id="enforce-password-expiration"></a>

Select **Periodically expire passwords** to set an interval at which you must refresh your Harness passwords. In the same dialog, you can also set an advance notification interval.

#### Enforce lockout after failed logins <a href="#enforce-lockout-after-failed-logins" id="enforce-lockout-after-failed-logins"></a>

Select **Enforce lockout policy** to open the dialog. Use the dialog to configure the lockout trigger (how many failed logins), lockout time (in days), and notifications to locked-out users and Harness user groups.

A summary appears on the main Authentication page:

#### Enforce two factor authentication <a href="#enforce-two-factor-authentication" id="enforce-two-factor-authentication"></a>

Select **Enforce Two Factor Authentication** to enforce 2FA for all users in Harness. This option governs all logins - whether through SSO providers or Harness username/password combinations. For more information, go to [Two-factor authentication](/harness-platform/3.0/harness-platform-resources/authentication/two-factor-authentication.md).

***

### Enable multiple identity providers <a href="#enable-multiple-identity-providers" id="enable-multiple-identity-providers"></a>

Harness supports multiple identity providers (IdPs) for user authentication using SAML. You can configure a variety of SAML providers and enable or disable them for user authentication.

{% hint style="info" %}
Currently, this feature is behind the feature flag `PL_ENABLE_MULTIPLE_IDP_SUPPORT`. Contact [Harness Support](mailto:support@harness.io) to enable it.
{% endhint %}

Before configuring your SAML provider in Harness, you must first set up the integration on the provider side and download the **Identity Provider metadata XML** file. You will upload this file into Harness in step 3c below.

Follow the setup guide for your provider:

* [SAML SSO with Okta](/harness-platform/3.0/harness-platform-resources/authentication/single-sign-on-saml/okta.md)
* [SAML SSO with Microsoft Entra ID](https://github.com/iKettles/harness-gitbook/tree/main/docs/platform/authentication/single-sign-on-saml/ms-entra-id/README.md)
* [SAML SSO with OneLogin](https://github.com/iKettles/harness-gitbook/tree/main/docs/platform/authentication/single-sign-on-saml/saml-sso-with-onelogin/README.md)
* [SAML SSO with Keycloak](/harness-platform/3.0/harness-platform-resources/authentication/single-sign-on-saml/keycloak.md)

To configure multiple SAML providers in Harness, follow the steps below:

1. In Harness UI, select **Account Settings**, and then select **Authentication**.
2. If you are configuring SAML for the first time and no SAML providers are configured, your screen appears as shown below. Select **+SAML Provider** and jump to step 3b. If SAML provider is configured but not enabled, jump to step 3.
3. Select **Login via SAML** and add the SAML providers you need.

   a. If SAML providers are configured but not enabled for the account, enable the one you want. If you want to create a new one, select **Add SAML Provider**.

   The SAML Provider settings appear.

   b. In the **Name** field, enter a name for the SAML provider. Names can only contain alphanumeric characters, `_`, `-`, `.`, and spaces. Select a SAML provider from the list. Select **Add**.

   c. Copy the SAML Endpoint URL. Upload the **Identity Provider metadata XML** file you downloaded from your SAML provider. Deselect **Enable Authorization** for now. You can enable this after completing the provider setup. Select **Add**.

   Harness supports the following SAML providers. Based on the SAML provider you select, refer to one of the following:

   * [SAML SSO with Okta](/harness-ai/use-harness-platform/authentication/single-sign-on-saml/okta.md)
   * [SAML SSO with Microsoft Entra ID](https://github.com/harness/harness-developer-hub/tree/main/docs/platform/authentication/single-sign-on-saml/ms-entra-id/README.md)
   * [SAML SSO with OneLogin](https://github.com/harness/harness-developer-hub/tree/main/docs/platform/authentication/single-sign-on-saml/saml-sso-with-onelogin/README.md)
   * [SAML SSO with Keycloak](/harness-ai/use-harness-platform/authentication/single-sign-on-saml/keycloak.md)

The SAML provider is now listed under **Login via SAML**.

Before enabling SAML, disable any configured public OAuth providers. For more information, go to [Single Sign-On with SAML](https://github.com/iKettles/harness-gitbook/tree/main/docs/platform/authentication/single-sign-on-saml/overview/README.md).

#### Enable login via SAML <a href="#enable-login-via-saml" id="enable-login-via-saml"></a>

[Enable one or more SAML providers](#enable-multiple-identity-providers) and follow the steps to enable SAML login for your account .

1. Login to your Harness account and select **Login via SAML**.
2. Choose your organization's SAML provider. When you click **Single sign-on**, you will be redirected to your selected provider's login page to complete authentication.

***

### Set up vanity URL <a href="#set-up-vanity-url" id="set-up-vanity-url"></a>

You can access `app.harness.io` using your own unique subdomain URL.

The subdomain URL is in the following format, with `{company}` being the name of your account:

`https://{company}.harness.io`

Contact [Harness Support](mailto:support@harness.io) to set up your account's subdomain URL. The subdomain URL cannot be changed later. Harness automatically detects your Account ID from the subdomain URL and redirects you to the account's login mechanism.

***

### Restrict email domains <a href="#restrict-email-domains" id="restrict-email-domains"></a>

Select **Only allow users with the following email domains:** to allow (whitelist) only certain domains as usable in login credentials. In the dialog, enter your chosen domains into the **Domains** multi-select field.

Click **Save**. The success message **Domain restrictions have been updated successfully** appears at the top of the page, indicating that certain domains were added to the allowlist.

The allowlist filters logins to Harness via both SSO providers and username/passwords. To modify your domain selections, select the Edit icon.

***

### Allow public access to resources <a href="#allow-public-access-to-resources" id="allow-public-access-to-resources"></a>

You can use this feature to grant unauthenticated access to view Harness resources without requiring login. Once enabled, you can allow public access to your pipelines. For more information, go to [Allow public access to executions](/harness-platform/3.0/harness-platform-resources/pipelines/executions-and-logs/allow-public-access-to-executions.md).

{% hint style="info" %}

* Currently, this feature is behind the feature flag `PL_ALLOW_TO_SET_PUBLIC_ACCESS`. Contact [Harness Support](mailto:support@harness.io) to enable the feature.
  {% endhint %}

### Set inactive session timeout <a href="#set-inactive-session-timeout" id="set-inactive-session-timeout"></a>

Harness logs you out after a period of inactivity.

To configure your account's session inactivity timeout, follow the steps below:

1. In your Harness account, select **Account Settings** and select **Authentication**.
2. In **Session Inactivity Timeout (in minutes)**, enter the time in minutes to set the session inactivity timeout.

   The default session inactivity timeout value is 1440 minutes (1 day).

   You can set this to a minimum of 30 minutes and a maximum of 4320 minutes (3 days). The field automatically converts the minutes you enter to higher units of time and displays the result under the field. For example, if you enter 1440, the UI shows **1 day** below the field.
3. Click **Save**.

***

### Set absolute session timeout <a href="#set-absolute-session-timeout" id="set-absolute-session-timeout"></a>

When you set the **Absolute Session Timeout (in minutes)**, Harness logs you out after the configured timeout, regardless of any activity.

To configure your account's absolute session timeout, follow the steps below:

1. In your Harness account, select **Account Settings** and select **Authentication**.
2. In **Absolute Session Timeout (in minutes)**, enter the time in minutes to set the absolute session timeout.

   The default absolute session timeout is 0, which means it is not set.

   You can set this to a maximum of 4320 minutes (3 days). The field automatically converts the minutes you enter to higher units of time and displays the result under the field. For example, if you enter 1440, the UI shows **1 day** below the field.
3. Click **Save**.

{% hint style="info" %}
When both the session inactivity timeout and the absolute session timeout are set, whichever condition is met first takes precedence.
{% endhint %}

***

### Audit logs for authentication <a href="#audit-logs-for-authentication" id="audit-logs-for-authentication"></a>

Harness audit trails record login attempts across all supported authentication methods. These audit events help administrators monitor authentication activity and investigate both successful and failed login attempts. Audit logs are generated for the following methods:

* [LDAP](#ldap-authentication)
* [SAML](#saml-authentication)
* [Two-Factor Authentication (2FA)](#two-factor-authentication-2fa)
* [Password-based authentication](#usernamepassword-authentication)

Each audit entry shows **how the login was attempted**, whether it was successful or failed, and the reason for failure, if applicable. Audit logs are only created for users who exist in your Harness account and are associated with a valid email address. No audit log is generated for login attempts by users who do not exist in the account.

While successful login events are common, pay closer attention to unsuccessful attempts. You may encounter the following failure reasons in the audit trail or in the JSON output when audit streaming is enabled for your account.

#### LDAP authentication <a href="#ldap-authentication" id="ldap-authentication"></a>

Unsuccessful login attempts can occur for the following reasons:

* **Domain not whitelisted:** Your email domain is not permitted for the account.
* **LDAP not configured for the account:** LDAP authentication is not set up.
* **Invalid credentials:** The username or password provided is incorrect.
* **Unable to fetch LDAP configuration:** Harness could not retrieve LDAP settings due to an internal error.
* **LDAP not configured:** LDAP authentication is not configured for this account.
* **LDAP authentication error:** An unexpected error occurred during the LDAP authentication process.

**Example JSON:**

```json
{
  "module": "CORE",
  "resource": {
    "type": "USER",
    "identifier": "demouser@harness.io",
    "labels": {
      "resourceName": "Demo Test",
      "userId": "68xLsmP7RzOJ_F3M_LBBHw"
    }
  },
  "action": "UNSUCCESSFUL_LOGIN",
  "auditEventData": {
    "type": "UnsuccessfulLoginEventData",
    "loginType": "LDAP",
    "failureReason": "Invalid LDAP credentials"
  }
}
```

#### SAML authentication <a href="#saml-authentication" id="saml-authentication"></a>

Unsuccessful login attempts can occur for the following reasons:

* **Domain not in allowlist:** Your email domain is not included in the account's allowed domain list.
* **Replay attack:** A previously used SAML login request was detected and blocked for security reasons.

**Example JSON:**

```json
{
  "module": "CORE",
  "resource": {
    "type": "USER",
    "identifier": "demouser@harness.io",
    "labels": {
      "resourceName": "Demo Test",
      "userId": "jWF23r4XQjyRTLVsAS_mVw"
    }
  },
  "action": "UNSUCCESSFUL_LOGIN",
  "auditEventData": {
    "type": "UnsuccessfulLoginEventData",
    "loginType": "SAML",
    "failureReason": "Domain not whitelisted"
  }
}
```

#### Two-Factor Authentication (2FA) <a href="#two-factor-authentication-2fa" id="two-factor-authentication-2fa"></a>

Unsuccessful login attempts can occur for the following reasons:

* **Invalid two-factor configuration:** Two-factor authentication is not properly set up for your account.
* **Invalid TOTP token:** The one-time password provided is incorrect or has expired.
* **Two-factor authentication failed:** The security code could not be verified.

**Example JSON:**

```json
{
  "module": "CORE",
  "resource": {
    "type": "USER",
    "identifier": "demouser@harness.io",
    "labels": {
      "resourceName": "Demo Test",
      "userId": "jWF23r4XQjyRTLVsAS_mVw"
    }
  },
  "action": "UNSUCCESSFUL_LOGIN",
  "auditEventData": {
    "type": "UnsuccessfulLoginEventData",
    "loginType": "TWOFA",
    "failureReason": "Invalid TOTP token"
  }
}
```

#### Username/password authentication <a href="#usernamepassword-authentication" id="usernamepassword-authentication"></a>

Failed login attempts using username/password occur when:

* Your credentials are incorrect.
* Your account is temporarily locked or deactivated, or your access has been revoked.

{% hint style="info" %}
The JSON response for username/password failures follows a different schema than the audit event entries above. This is an API error response.
{% endhint %}

**Example JSON:**

```json
{
  "metaData": null,
  "resource": null,
  "responseMessages": [
    {
      "code": "INVALID_CREDENTIAL",
      "level": "ERROR",
      "message": "Invalid credentials: INVALID_CREDENTIAL"
    }
  ]
}
```

***

### Next steps <a href="#next-steps" id="next-steps"></a>

* [RBAC in Harness](/harness-platform/3.0/harness-platform-resources/platform-access-control/rbac-in-harness.md) - learn how authorization and permissions work with authentication.
* [Single Sign-On with SAML](https://github.com/iKettles/harness-gitbook/tree/main/docs/platform/authentication/single-sign-on-saml/overview/README.md) - configure SAML-based SSO for your organization.
* [Two-factor authentication](/harness-platform/3.0/harness-platform-resources/authentication/two-factor-authentication.md) - set up and enforce 2FA for your account.