Single Sign-On (SSO) with Keycloak for OpenSearch

This guide describes how to log in to OpenSearch Dashboards using Keycloak (OIDC) in a kubeops-managed Kubernetes environment.

Unlike some other integrations, you do not have to create the Keycloak realm, client, roles or mapper by hand — the opensearch-dashboards package provisions them automatically during install/update. Username/password login remains available as a fallback.

Prerequisites

• A running Kubernetes cluster with kubectl configured
• Keycloak is installed and running (the keycloak package), exposed via Ingress and reachable over HTTPS
• A valid DNS record and a trusted TLS certificate (e.g. Let’s Encrypt) for the ingress hostname
• The OpenSearch hostname is set to that public host and is identical for the opensearch-os and opensearch-dashboards packages

Step 1: Configure the packages

Set the shared hostname and (optionally) the adminPassword for both OpenSearch packages in your enterprise-values.yaml:

apiVersion: kubeops/kubeopsctl/enterprise/beta/v1

deleteNs: false
localRegistry: false

packages:
  - name: opensearch-os
    enabled: true
    values:
      standard:
        namespace: logging
        hostname: <your_DNS_name>          # must match opensearch-dashboards and Keycloak host
        adminPassword: "<admin-password>"  # optional, default Password@@123456
  - name: opensearch-dashboards
    enabled: true
    values:
      standard:
        namespace: logging
        nodePort: 30050
        hostname: <your_DNS_name>          # must match opensearch-os
        adminPassword: "<admin-password>"  # must match opensearch-os

Apply the configuration:

kubeopsctl apply -f enterprise-values.yaml

Step 2: What the package provisions automatically

During install/update the package configures Keycloak and OpenSearch for you:

• Realm: kubeops-dashboards
• Client: opensearch-dashboards (OpenID Connect, confidential, standard flow)
• User: kubeops (default password password)
• Realm roles: all_access, opensearch_dashboards_user
• Protocol mapper: exposes the realm roles as a roles claim so OpenSearch can map them
• OpenSearch backend security config: an openid authentication domain (Keycloak) plus a basic domain (username/password fallback), and a role mapping from the Keycloak realm roles to OpenSearch roles

The Keycloak admin credentials used for this are read from the keycloak-kubeops secret.

Step 3: Grant a user access

To let a Keycloak user log in to OpenSearch, assign them one of the realm roles in the kubeops-dashboards realm:

• all_access — full access (maps to the OpenSearch all_access role)
• opensearch_dashboards_user — dashboards access (maps to the kibana_user role)

You can use the pre-created kubeops user, or assign the role to your own Keycloak users.

Step 4: Log in

Open the OpenSearch Dashboards URL:

https://<your_DNS_name>/opensearch/

• SSO: choose Log in with single sign-on → authenticate in Keycloak.
• Fallback: use username admin and the adminPassword value (default Password@@123456).

Notes / Troubleshooting

• hostname mismatch: the opensearch-os and opensearch-dashboards hostnames must be identical and must be the public Keycloak host, otherwise the OpenSearch backend cannot validate the token.

• 401 Unauthorized on SSO login: the OpenSearch backend could not validate the Keycloak token. Check that hostname is set and reachable from the OpenSearch pods, and that Keycloak’s TLS certificate is trusted (e.g. Let’s Encrypt). Verify the backend security config contains the openid domain:

  curl -k -u admin:<adminPassword> \
    https://opensearch-cluster-master:9200/_plugins/_security/api/securityconfig
  

• *.local hostname: SSO is intentionally skipped; only username/password login is available.

• Changing the admin password: see Changing the OpenSearch password.