Securing OpenSearch with OIDC Integration

OpenSearch includes a robust security plugin that provides encryption, authentication and authorization. This article guides you how to connect OpenSearch with an OIDC provider like Keycloak. By the end, you'll have a secure authentication system that centralizes user management.

We have been building an full stack observability platform, as a truly open source and efficient alternative to the ELK stack, using OpenSearch at the core. Having and SSO integrated with the system will make it more cohesive and easier for teams to use and manage.

Why SSO?

Integrating OpenSearch with OIDC brings several key benefits:

• Single Sign-On (SSO): Let your team access OpenSearch along with other tools with one set of credentials
• Precise permissions: Map user roles directly to OpenSearch access levels. Moreover you can control what kind of data users can access. This allows large teams to work on the same cluster without worrying about data leaks More on this on a later article.
• Centralized control: Manage all users in one place instead of maintaining separate accounts

Prerequisites: What you'll need

Before we start, ensure you have:

• OpenSearch cluster running (with security plugin enabled)
• Administrative access to your OIDC provider (Keycloak, Okta, Auth0, etc.). This article will use Keycloak as an example. The steps are similar for other providers.
• HTTPS configured for OpenSearch and Dashboards
• Network connectivity between OpenSearch and your identity provider
• Basic familiarity with OpenSearch configuration files

Step-by-Step Guide to OIDC Integration

Step 1: Configure Your OIDC Provider

1.1 Create a new client named opensearch

With the following configuration:

• Redirect URI: https://opensearch.apps.yourcompany.com/
• Home URL: https://opensearch.apps.yourcompany.com/
• Valid Redirect URIs: https://opensearch.apps.yourcompany.com/* Note these these are the URLs for your OpenSearch Dashboards instance.

1.2 Create custome scope opensearch_roles

• Once the scope is created you need to create a role mapper
• Goto "Mappers", Click on "Add mapper", select "From predefined mapper", Seach for "client roles" and select it
• Now click on edit put the following valuess:
  • Client ID: opensearch
  • Multivalued: true
  • Token claim name: roles
  • Claim JSON Type: String
  • Add to ID token: true
  • Add to access token: true
  • Add to token introspection: true

1.3 Add the scope to the client

• Go to opensearch client, "Client Scopes" tab, and add the opensearch_roles scope to the client.
• Make it a default scope so that it is always included in the tokens issued for this client.
• Remove the existing roles scope if it exists, as it will conflict with our custom scope. role

1.4 Create client secret

• Go to the opensearch client, "Credentials" tab, and create a new client secret.
• Note down the client secret, as you will need it to configure OpenSearch.

Step 2: Configure OpenSearch Security and Dashboards

2.1 Edit OpenSearch security config

<opensearch-install-dir>/config/opensearch-security/config.yaml file would be:

_meta:
  type: "config"
  config_version: 2

config:
  dynamic:
    http:
      anonymous_auth_enabled: false
    authc:
      basic_internal_auth_domain:
        description: "Authenticate via HTTP Basic against internal users database"
        http_enabled: true
        transport_enabled: true
        order: 4
        http_authenticator:
          type: basic
          challenge: true
        authentication_backend:
          type: intern
      clientcert_auth_domain:
        description: "Authenticate via SSL client certificates"
        http_enabled: false
        transport_enabled: false
        order: 2
        http_authenticator:
          type: clientcert
          config:
            username_attribute: cn
          challenge: false
        authentication_backend:
          type: noop
      openid_auth_domain:
        description: "Authenticate via OpenID Connect"
        http_enabled: true
        transport_enabled: true
        order: 3
        http_authenticator:
          type: openid
          challenge: false
          config:
            subject_key: preferred_username
            roles_key: roles
            openid_connect_url: https://keycloak.apps.yourcompany.com/realms/yourcompany/.well-known/openid-configuration
        authentication_backend:
          type: noop
    authz: {}

Note: The openid_connect_url should point to your OIDC provider's discovery document. In Keycloak this found in realm settings under "OpenID Endpoint Configuration".

Once changed are made apply the changes by running your security admin tool. If you are using the OpenSearch operator in k8s, you don't need to do this as the operator will take care of it. (Which we strongly recommanded)

2.2 Update the OpenSearch Dashboards configuration

opensearch.ssl.verificationMode: none
opensearch_security.auth.type: openid
opensearch_security.openid.base_redirect_url: https://opensearch.apps.yourcompany.com/
opensearch_security.openid.client_id: opensearch
opensearch_security.openid.client_secret: sjwVyYqeaEXVaaZlssBIwNeNDdgGsoqy
opensearch_security.openid.connect_url: https://keycloak.apps.yourcompany.com/realms/yourcompany/.well-known/openid-configuration
opensearch_security.openid.scope: basic email opensearch_roles
server.name: opensearch-dashboards

Note:

• Update the opensearch_security.openid.client_secret with the secret you created in Keycloak.
• Pay attention to the opensearch_security.openid.scope which includes the custom scope we created earlier (opensearch_roles).
• Once configs are updated, restart the OpenSearch Dashboards service to apply the changes.

Step 3: Grant permission via Keycloak

Once the previous steps are done, you no longer can access OpenSearch dashboards with the default admin user. You need to map the role admin to a user in Keycloak. For that:

1. Go to Keycloak, opensearch client, "Roles" tab.
2. Create a new role called admin
3. Go to the "Users" tab, select a user you want to grant admin access. Search for the role you just created (admin) and assign it to the user.

Step 4: Test the integration

Once these configurations are applied, you can test the integrations as follows:

1. Open your OpenSearch Dashboards URL (e.g., https://opensearch.apps.yourcompany.com/).
2. You should be redirected to your OIDC provider's login page (Keycloak in this case)
3. Login with your Keycloak credentials.
4. After successful authentication, you should be redirected back to OpenSearch Dashboards with admin access.

Next steps

You now have a working OIDC integration with OpenSearch. You can create more roles in Opensearch security in Opensearch dashboard and map them to users in Keycloak, similar to how we did for the admin role.

Basic Troubleshooting Tips

If you encounter issues:

• Redirect errors: Double-check callback URLs in OIDC client config
• Permission issues: Verify role mappings in OpenSearch. Make sure you the role you are mapping is mapped to the role in Opensearch security. (This can be done in OpenSearch Dashboards under Security → Role → Mapped users)
• Connection problems: Ensure networks can communicate
• Logs are your friend: Check OpenSearch and OIDC provider logs
• Certificate issues: Confirm all endpoints use trusted certificates

Conclusion

Integrating OpenSearch with OIDC enhances security and simplifies user management. This setup demonstrates how open source solutions can provide enterprise-grade security without enterprise-grade price tags. Good luck you your journey!

Cheers!