Skip to main content

Keycloak

Last updated on

What will you learn in this topic?​

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

  • How to set up a Keycloak SAML client.
  • How to configure Harness to use Keycloak SAML client as an SSO provider.
  • How to enable group-based authorization.

Before you begin​

  • A Harness account with Account Admin permissions.
  • An existing Keycloak instance with admin access to create and configure SAML clients.

You can use Keycloak as a SAML identity provider for Harness, letting Keycloak users log in to Harness with their existing credentials and optionally syncing Keycloak group memberships to Harness user groups automatically.

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.

Harness supports configuration with or without Just-In-Time (JIT) user provisioning. Without JIT, perform the following steps to add new users:

  1. In Harness, add the users you want to set up for SAML SSO by inviting them to Harness using the same email addresses that they use in your SAML provider.
  2. In Keycloak, add the users and make sure they are in scope for the client you create in the configuration steps below.

With JIT, you add users to Keycloak, and they will automatically be added to Harness upon first login.

Set up a client in Keycloak​

  1. Log in to your Keycloak account.

  2. Switch to your target Realm, then select Clients.

  3. Select Create Client, then enter the following values.

    General settings

    FieldDescription
    Client TypeSAML
    Client IDapp.harness.io
    Nameoptional
    Descriptionoptional
    Always display in UIOff

    Login settings

    FieldDescription
    Root URLhttps://app.harness.io/
    Home URLhttps://app.harness.io/ng/account/<YOUR ACCOUNT ID>/main-dashboard
    Valid post logout redirect URIshttps://app.harness.io/ng/account/<YOUR ACCOUNT ID>/main-dashboard
    Master SAML Processing URLhttps://app.harness.io/gateway/api/users/saml-login?accountId=<YOUR ACCOUNT ID>
note

If the account uses a vanity URL, then use the vanity URL in your SAML setup. For example, https://<yourvanityurl>/gateway/api/users/saml-login?accountId=<YOUR ACCOUNT ID>.

  1. Select Save.

  2. In the newly-created client's configuration, enter the following values.

    Settings -> SAML capabilities

    FieldDescription
    Name ID formatemail
    Force POST bindingOn
    Include AuthnStatementOn
    All other optionsOff

    Settings -> Signature and Encryption

    FieldDescription
    Sign documentsOn
    Sign assertionsOn
    Signature algorithmRSA_SHA256
    SAML signature key nameNONE
    Canonicalization methodEXCLUSIVE

    Keys

    FieldDescription
    Client signature requiredOff

    Advanced

    FieldDescription
    Assertion Consumer Service POST Binding URLhttps://app.harness.io/gateway/api/users/saml-login?accountId=<YOUR ACCOUNT ID>

  3. Select Save.

  4. From the left-nav menu, go to Realm Settings, then select SAML 2.0 Identity Provider Metadata. A new tab opens with XML data.

  5. Save the data to a file to use when configuring Harness.

  6. (Optional) To automatically sync group memberships in Harness based on group memberships in Keycloak, perform the following steps.

    1. Go to your newly-created Client, then select the Client Scopes tab.

    2. In the first row, select the value in the Assigned client scope field.

    3. Select Configure a new mapper, then select Group list.

    4. Configure the following settings.

    NameDescription
    Namegrouplist
    Group attribute namemember
    SAML Attribute NameFormatBasic
    Single Group AttributeOn
    Full group pathOff
    1. Select Save.

Set up Keycloak SAML SSO in Harness​

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

  2. Select + SAML Provider, then enter the following values.

    FieldDescription
    NameKeycloak
    Select an SAML ProviderOther
    Enable AuthorizationEnable if you want to automatically sync group memberships in Harness based on group memberships in Keycloak
    Group Attribute Namemember (only available if Enable Authorization is selected)
    Add Entity IdEnabled
    Entity Idapp.harness.io
    Enable JIT ProvisioningEnable if Just In Time user provisioning is desired

  3. Select Add.

  4. In Upload the Identity Provider metadata XML downloaded from your app, select Upload, then select the XML file you added when you set your Keycloak configuration steps.

  5. Select Add. The new SSO provider is displayed under Login via SAML. You might need to expand this section using the arrow on the right-hand side of the screen.

Enable and test SSO with Keycloak​

Now that Keycloak is set up in Harness as a SAML SSO provider, you can enable and test it.

  1. To enable the SSO provider, select Login via SAML.
  2. In the resulting Enable SAML Provider dialog, click TEST to verify the SAML connection you've configured.
  3. Upon a successful test, Harness will display the SAML test successful banner on top.
  4. Click CONFIRM to enable SAML SSO in Harness.

Harness Local Login​

To prevent lockouts or in the event of OAuth downtime, a user that has Account Admin assigned on All Account Level Resources or All Resources Including Child Scopes can use the Local login URL https://app.harness.io/auth/#/local-login to sign in and update the OAuth settings.

important

Harness Local Login signs in to the default account for the user. If the user is assigned to multiple accounts, the user must ensure the default account is set correctly before attempting to use Harness Local Login.

For the Harness production cluster prod-3, the local login URL is https://app3.harness.io/auth/#/local-login.

  1. Sign in using Local login.

  2. Change the settings to enable users to log in.

note

You can disable Local login using the feature flag DISABLE_LOCAL_LOGIN. 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. Under Login via SAML, select More Options (⋮), and then select Edit. The Edit SAML Provider options open.

  3. Select the Download link to download the encryption certificate for SAML assertions.

  4. Sign in to your IdP.

  5. Edit your SAML integration.

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

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

Set the default experience​

Environment administrators can set the default Harness generation landing page, FirstGen or NextGen, for their users to ensure the correct Harness Experience is provided to each user. For more information, go to Account details.

Next steps​