IMPORTANT: No additional bug fixes or documentation updates will be released for this version. For the latest information, see the current release documentation.

« Manage users and access to Enterprise Search Set up Enterprise Search with OpenID Connect single sign-on (SSO) »

› ›

Set up Enterprise Search with SAML 2.0 single sign-on (SSO)

edit

Set up Enterprise Search with SAML 2.0 single sign-on (SSO)

edit

This feature is not available for all Elastic subscription levels. Refer to the subscriptions pages for Elastic Cloud and Elastic Stack. To change your subscription level or start a trial, see Elastic subscription.

This quickstart explains how to configure SAML authentication for Enterprise Search and Kibana on a local self-managed deployment. See the end of this document for how to apply these instructions to a deployment running on Elastic Cloud or Elastic Cloud on Kubernetes (ECK).

Since 8.0, SAML support for Enterprise Search is defined in Elasticsearch and Kibana configuration files. No additional configuration is required in the Enterprise Search configuration file.

This is only a concise reference example. See Configuring Elasticsearch for SAML authentication in the Elasticsearch documentation for a complete reference to Elasticsearch SAML configuration. For troubleshooting, see Common SAML issues.

Configure Elasticsearch for SAML authentication

edit

Configure a SAML realm within Elasticsearch for Enterprise Search in Kibana.

Add the following configuration to the Elasticsearch config/elasticsearch.yml file:

# Skip this if you are running an Elastic Cloud deployment
# Elastic Cloud has token service enabled by default and will not accept the `xpack.security.authc.token.enabled` setting
xpack.security.authc.token.enabled: true

# Update the `http://localhost:5601` references to the location of your Kibana endpoint
# See https://www.elastic.co/guide/en/enterprise-search/current/endpoints-ref.html
xpack.security.authc.realms.saml.kibana-my-saml:
  order: 3
  # Replace with your SAML identity provider's metadata URL
  idp.metadata.path: "https://YOUR_SAML_IDP/metadata"
  idp.entity_id: "urn:example:idp"
  sp.entity_id: "http://localhost:5601"
  sp.acs: "http://localhost:5601/api/security/saml/callback"
  sp.logout: "http://localhost:5601/logout"
  attributes:
    # Or replace with another SAML provider attribute you prefer to map to the username
    principal: "email"

The sp.* configuration values must point to the Kibana endpoint, and you must collect the idp.* settings from your SAML identity provider.

Configure your SAML identity provider to work with Kibana

edit

Configure your SAML identity provider to allow authentication to Kibana at http://localhost:5601. The configuration steps will vary for your specific SAML identity provider.

Configure Kibana to use the Elasticsearch SAML realm

edit

Add this configuration to the Kibana config/kibana.yml file.

xpack.security.authc.providers:
  saml:
    # Realm name matches the realm name defined in Elasticsearch config
    kibana-my-saml:
      order: 0
      realm: "kibana-my-saml"
# Enable authentication for Elasticsearch native users
  basic:
    basic1:
      order: 1

Grant SAML users access to Kibana

edit

Use the Elasticsearch role mappings API or the Kibana stack management role mappings UI to map roles to SAML realm users.

For example, to grant all SAML realm users access to all of Kibana using the Elasticsearch API:

curl --insecure -u elastic:changeme -XPOST https://localhost:9200/_security/role_mapping/mapping1 \
-H 'Content-Type: application/json' \
-d '
{
  "roles": [ "kibana_admin" ],
  "enabled": true,
  "rules": {
    "field": { "realm.name": "kibana-my-saml" }
  }
}'

Or grant only one SAML realm user access to all of Kibana:

curl --insecure -u elastic:changeme -XPOST https://localhost:9200/_security/role_mapping/mapping2 \
-H 'Content-Type: application/json' \
-d '
{
  "roles": [ "kibana_admin" ],
  "enabled": true,
  "rules": {
    "field": { "username": "saml.jackson@example.com" }
  }
}'

Grant SAML users access to Enterprise Search

edit

By default, all users have full access to App Search and Workplace Search. Enable role-based access controls in App Search or Workplace Search to control SAML user access.

Enable role-based access control in App Search and Workplace Search:

Launch Enterprise Search in Kibana.
Launch App Search or Workplace Search. Choose Users and Roles and enable role-based access.
Add a SAML role mapping for the SAML user(s) who require access. Make sure to grant owner access to at least one SAML user so that you can continue to manage users and roles.

Configure Elastic Cloud deployments

edit

Configuring SAML for Elastic Cloud deployments (ESS and ECE) is similar to configuring local self-managed deployments, with the following differences:

Replace references to http://localhost:5601 with the URL of your Kibana instance on Elastic Cloud.
Add the Elasticsearch configuration settings to the Elasticsearch settings in your Cloud deployment. Exclude the setting xpack.security.authc.token.enabled: true.
Add the Kibana configuration to the Kibana settings in your Cloud deployment.

Example: Set up SAML for an Elastic Cloud deployment using Okta

edit

Before you start the setup, consult the official docs for the SAML identity provider you are using. For this example, read the official Okta docs to add a SAML Identity Provider.

In short, you need to:

Set up your application in Okta.
Configure Enterprise Search to use the SAML application.

Set up your application in Okta:

Follow the instructions in the Okta docs to add an Okta SAML application.
Select Web and SAML 2.0.
Name your app, e.g. "Enterprise Search".
Provide the following values when prompted, replacing [KIBANA BASE URL] with the Kibana base URL for your deployment:
- Single sign-on URL: [KIBANA BASE URL]/api/security/saml/callback
- Audience Restriction / Audience URI (SP Entity ID): [KIBANA BASE URL]
Finish the setup by assigning users to the app.

Now configure Kibana to use the SAML application you created in Okta. You need to add two pieces of information from Okta to your Elasticsearch configuration in the Elastic Cloud console.

Select Edit under your deployment, and add these configuration settings to the Elasticsearch user settings:
```
xpack.security.authc.realms.saml:
  saml1:
    order: 2
    idp.metadata.path: '[METADATA PATH]'
    idp.entity_id: '[SAML ENTITY ID]'
    sp.entity_id: '[KIBANA BASE URL]' # Make sure there is no trailing "/"
    sp.acs: '[KIBANA BASE URL]/api/security/saml/callback'
    sp.logout: '[KIBANA BASE URL]/logout'
    attributes:
      # Or replace with another SAML provider attribute you prefer to map to the username
      principal: nameid
```
You will find the following information in the Okta SAML application:
- [METADATA PATH]: In Okta, underneath the View Setup Instructions button is a URI for Identity Provider metadata. Add that URI, which will look something like https://[name].okta.com/app/[appid]/sso/saml/metadata.
- [SAML ENTITY ID]: In Okta, find this under the Sign On tab for your Applications. Click View Setup Instructions, and you’ll see Identity Provider Issuer. The Identity Provider Issuer will look something like http://www.okta.com/exkeLvbBxN4x6

Add the following to your Kibana configuration in the Elastic Cloud console, under Edit user settings:

xpack.security.authc.providers:
  saml:
    saml1:
      order: 0
      realm: saml1
  basic:
    basic1:
      order: 1

Finally grant SAML users access to Kibana, using the API instructions on this page.

Save these settings, and wait for your cluster to restart. The next time you select Launch Enterprise Search, you’ll have the option to log in with Okta SSO.

If you get an error, check your Elasticsearch logs for more details.

Configuring Elastic Cloud on Kubernetes deployments

edit

Configuring SAML for Elastic Cloud on Kubernetes (ECK) deployments is similar to configuring local self-managed deployments, with the following differences:

Replace references to http://localhost:5601 with the URL of your Kibana instance on ECK.
Add the Elasticsearch and Kibana configuration settings to the appropriate sections in the ECK configuration.

This example ECK YAML file configures SAML for Elasticsearch, Enterprise Search, and Kibana all running on a local ECK instance.

apiVersion: elasticsearch.k8s.elastic.co/v1
kind: Elasticsearch
metadata:
  name: example
spec:
  version: 8.9.2
  nodeSets:
    - name: default
      count: 1
      config:
        node.store.allow_mmap: false
        # SAML configuration
        xpack.security.authc.token.enabled: true
        xpack.security.authc.realms.saml.kibana-my-saml:
          order: 3
          # Replace with your SAML identity provider's metadata URL
          idp.metadata.path: "https://YOUR_SAML_IDP/metadata"
          idp.entity_id: "urn:example:idp"
          sp.entity_id: "https://localhost:5601"
          sp.acs: "https://localhost:5601/api/security/saml/callback"
          sp.logout: "https://localhost:5601/logout"
          attributes:
            # Or replace with another SAML provider attribute you prefer to map to the username
            principal: "email"
---
apiVersion: enterprisesearch.k8s.elastic.co/v1
kind: EnterpriseSearch
metadata:
  name: example
spec:
  version: 8.9.2
  count: 1
  elasticsearchRef:
    name: example
  podTemplate:
    spec:
      containers:
      - name: enterprise-search
        env:
        - name: JAVA_OPTS
          value: -Xms1500m -Xmx1500m
        resources:
          requests:
            memory: 2Gi
          limits:
            memory: 2Gi
---
apiVersion: kibana.k8s.elastic.co/v1
kind: Kibana
metadata:
  name: example
spec:
  version: 8.9.2
  config:
    xpack.security.authc.providers:
      saml:
        # Realm name matches the realm name defined in Elasticsearch config
        kibana-my-saml:
          order: 0
          realm: "kibana-my-saml"
      basic:
        basic1:
          order: 1
  count: 1
  elasticsearchRef:
    name: example
  enterpriseSearchRef:
    name: example

Learn more about configuring SAML on ECK for Elasticsearch and Kibana.

Learn more about configuring Enterprise Search on ECK.

« Manage users and access to Enterprise Search Set up Enterprise Search with OpenID Connect single sign-on (SSO) »