Configure OpenSearch SSO with Keycloak

ClusterNest Managed OpenSearch can delegate Dashboards login to Keycloak over OIDC or SAML. A cluster takes several auth sources side by side, with at most one SAML source and one OIDC source offered on Dashboards. A new cluster already has the ClusterNest sign-in, which is the one OIDC login Dashboards offers, so remove it before offering an OIDC source of your own (the auth_sources list in the Terraform tab replaces it). SAML sources sit next to it.

You’ll need your cluster’s OpenSearch Dashboards hostname before registering the client. Set dashboards_custom_hostname so you know it upfront, or create the cluster first without an auth source and note the generated opensearch_dashboards_url output before adding it.

OIDC

OIDC

Keycloak’s ID token doesn’t include realm/client roles by default - roles_key only works once a matching mapper is attached to the client.

Console

1. In the Keycloak admin console, go to your realm’s Clients > Create client.
   • Client type: OpenID Connect, Client ID: e.g. opensearch-dashboards
   • Client authentication: On (confidential client), Standard flow: enabled
   • Valid redirect URIs: https://<dashboards-hostname>/auth/openid/login
2. On the Credentials tab, note the Client secret.
3. To get a claim for roles_key, go to the client’s Client scopes tab, open its dedicated scope, and add a Group Membership mapper with token claim name groups.

connect_url is https://<keycloak-host>/realms/<realm>/.well-known/openid-configuration.

In the ClusterNest console, open the cluster’s create/edit form and add an OIDC source under Authentication. Choose a Name (it becomes the text of the Dashboards button, “Login with” followed by this name), tick Offer on OpenSearch Dashboards, then fill in:

• Connect URL: https://auth.example.com/realms/myrealm/.well-known/openid-configuration
• Client ID / Client Secret: from the client’s Credentials tab
• Roles Key: groups (or whatever your mapper’s claim name is; leave blank if you skipped step 3)

Terraform

Keycloak’s official provider (keycloak/keycloak) manages both the client and the role-mapping claim in the same config as the ClusterNest cluster:

terraform {
  required_providers {
    keycloak = {
      source  = "keycloak/keycloak"
      version = "~> 5.0"
    }
    clusternest = {
      source  = "tf.clusternest.com/clusternest/clusternest"
      version = ">= 1.11.1"
    }
  }
}

provider "keycloak" {
  url       = "https://auth.example.com"
  client_id = "admin-cli"
}

provider "clusternest" {
  email    = "[email protected]"
  password = var.clusternest_app_password
}

locals {
  dashboards_hostname = "opensearch-dashboards.example.com"
}

data "keycloak_realm" "myrealm" {
  realm = "myrealm"
}

resource "keycloak_openid_client" "opensearch" {
  realm_id  = data.keycloak_realm.myrealm.id
  client_id = "opensearch-dashboards"
  name      = "OpenSearch Dashboards"
  enabled   = true

  access_type           = "CONFIDENTIAL"
  standard_flow_enabled = true
  valid_redirect_uris   = ["https://${local.dashboards_hostname}/auth/openid/login"]
}

resource "keycloak_openid_group_membership_protocol_mapper" "groups" {
  realm_id   = data.keycloak_realm.myrealm.id
  client_id  = keycloak_openid_client.opensearch.id
  name       = "groups"
  claim_name = "groups"
}

resource "clusternest_opensearch" "sso" {
  name            = "logs"
  tier            = "standard"
  organization_id = 123
  auth_sources = [
    {
      name             = "keycloak"
      type             = "oidc"
      connect_url      = "https://auth.example.com/realms/myrealm/.well-known/openid-configuration"
      client_id        = keycloak_openid_client.opensearch.client_id
      client_secret    = keycloak_openid_client.opensearch.client_secret
      roles_key        = "groups"
      dashboards_login = true
    },
  ]

  dashboards_custom_hostname = local.dashboards_hostname
}

client_secret is left unset on the client so Keycloak generates one, exposed as a sensitive computed attribute. Drop the keycloak_openid_group_membership_protocol_mapper resource and roles_key if you don’t need role mapping.

SAML

SAML

roles_key defaults to an ADFS-style claim URI Keycloak never emits - it only works once a matching Role List mapper is attached to the client (Client scopes > dedicated scope > Add mapper in the console).

Console

1. In the Keycloak admin console, go to your realm’s Clients > Create client.
   • Client type: SAML, Client ID: the value you’ll use as sp_entity_id below
   • Valid redirect URIs / Master SAML Processing URL: https://<dashboards-hostname>/_opendistro/_security/saml/acs
   • Name ID format: email (or whatever your subject_key mapping expects)
2. To map roles into the assertion, go to the client’s Client scopes, edit the dedicated scope, and add a Role list mapper - note the SAML attribute name it’s configured to emit.

idp_metadata_url is Keycloak’s realm SAML descriptor endpoint - it needs no authentication. idp_entity_id is the realm issuer URL, https://<keycloak-host>/realms/<realm>.

In the ClusterNest console, open the cluster’s create/edit form and add a SAML source under Authentication. Choose a Name (it becomes the text of the Dashboards button, “Login with” followed by this name), then fill in:

• IDP Metadata URL: https://auth.example.com/realms/myrealm/protocol/saml/descriptor
• IDP Entity ID: https://auth.example.com/realms/myrealm
• SP Entity ID: opensearch-dashboards
• Roles Key: Role (or whatever your mapper’s attribute name is)

Terraform

terraform {
  required_providers {
    keycloak = {
      source  = "keycloak/keycloak"
      version = "~> 5.0"
    }
    clusternest = {
      source  = "tf.clusternest.com/clusternest/clusternest"
      version = ">= 1.11.1"
    }
  }
}

provider "keycloak" {
  url       = "https://auth.example.com"
  client_id = "admin-cli"
}

provider "clusternest" {
  email    = "[email protected]"
  password = var.clusternest_app_password
}

locals {
  dashboards_hostname = "opensearch-dashboards.example.com"
}

data "keycloak_realm" "myrealm" {
  realm = "myrealm"
}

resource "keycloak_saml_client" "opensearch" {
  realm_id  = data.keycloak_realm.myrealm.id
  client_id = "opensearch-dashboards"
  name      = "OpenSearch Dashboards"

  valid_redirect_uris = ["https://${local.dashboards_hostname}/_opendistro/_security/saml/acs"]
  name_id_format       = "email"
}

resource "clusternest_opensearch" "sso" {
  name            = "logs"
  tier            = "standard"
  organization_id = 123
  auth_sources = [
    {
      name             = "keycloak"
      type             = "saml"
      idp_metadata_url = "https://auth.example.com/realms/myrealm/protocol/saml/descriptor"
      idp_entity_id    = "https://auth.example.com/realms/myrealm"
      sp_entity_id     = keycloak_saml_client.opensearch.client_id
    },
  ]

  dashboards_custom_hostname = local.dashboards_hostname
}

For roles_key, add a Role List mapper resource to the client and set roles_key to the SAML attribute name it’s configured to emit.

See the Terraform resource reference for the full field list.