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 Platinum features »

› ›

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 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).

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.

SAML for Enterprise Search is a platinum feature.

Configure Elasticsearch for SAML authentication

edit

In Elasticsearch, configure one SAML realm for Kibana and another for Enterprise Search by adding this configuration to the Elasticsearch config/elasticsearch.yml file.

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: "http://localhost:5601"
  sp.acs: "http://localhost:5601/api/security/v1/saml"
  sp.logout: "http://localhost:5601/logout"
  attributes:
    # Or replace with another SAML provider attribute you prefer to map to the username
    principal: "email"

xpack.security.authc.realms.saml.ent-search-my-saml:
  order: 2
  # 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:3002"
  sp.acs: "http://localhost:3002/users/saml_login"
  sp.logout: "http://localhost:3002/logout"
  attributes:
    # Or replace with another SAML provider attribute you prefer to map to the username
    principal: "email"

Keep in mind the sp.* configurations must point to the Kibana and Enterprise Search endpoints, and you must collect the idp.* settings from your SAML identity provider.

You must configure a separate realm for Enterprise Search in order to log in to Enterprise Search through its standalone UI. When accessing Enterprise Search through Kibana exclusively, you do not need to configure a second realm for Enterprise Search because Kibana is authenticating your users.

Configure your SAML identity provider to work with Enterprise Search and Kibana

edit

Configure your SAML identity provider to allow authentication to Enterprise Search at http://localhost:3002 and to Kibana at http://localhost:5601. The configuration steps will vary for your specific SAML identity provider. For an example identity provider configuration, see Setting up SAML for Enterprise Search: Okta edition.

Configure Enterprise Search to use the Elasticsearch SAML realm

edit

Add this configuration to the Enterprise Search config/enterprise-search.yml file.

ent_search.auth:
  ent-search-my-saml:             # match the realm name in elasticsearch.yml
    source: elasticsearch-saml    # always elasticseach-saml
    description: "My SAML"
    icon: "https://www.elastic.co/favicon.ico"
    order: 3
# Optionally also enable authentication for Elasticsearch native users
  ent-search-native:
    source: elasticsearch-native   # always elasticsearch-native
    description: "Elasticsearch"
    icon: "https://www.elastic.co/favicon.ico"
    order: 4

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 http://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 http://localhost:9200/_security/role_mapping/mapping2 \
-H 'Content-Type: application/json' \
-d '
{
  "roles": [ "kibana_admin" ],
  "enabled": true,
  "rules": {
    "field": { "username": "[email protected]" }
  }
}'

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 from Kibana or log in to the Enterprise Search standalone UI with any SAML user.
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.

Configuring 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:3002 with the URL of your Enterprise Search instance on Elastic Cloud.
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 Enterprise Search configuration settings to the Enterprise Search settings in your Cloud deployment. Note that Cloud always adds a native realm configuration to Enterprise Search. It’s not necessary to add native realm configuration to your Enterprise Search deployment settings.
Add the Kibana configuration to the Kibana settings in your Cloud deployment.

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:3002 with the URL of your Enterprise Search instance on ECK.
Replace references to http://localhost:5601 with the URL of your Kibana instance on ECK.
Add the Elasticsearch, Enterprise Search, and Kibana configuration settings to the appropriate sections in the ECK configuration.
Before version 8.0, ECK only allows configuring a single authentication source in the Enterprise Search config. For example, you can specify either SAML auth or Elasticsearch native auth, but not both. ECK supports multiple authentication sources in Kibana; your SAML users and Elasticsearch native users can log in to Enterprise Search through the Kibana UI.
Configuring SAML on Enterprise Search on ECK requires ECK to have an Enterprise license.

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: 7.14.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/v1/saml"
          sp.logout: "https://localhost:5601/logout"
          attributes:
            # Or replace with another SAML provider attribute you prefer to map to the username
            principal: "email"
        xpack.security.authc.realms.saml.ent-search-my-saml:
          order: 2
          # 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:3002"
          sp.acs: "https://localhost:3002/users/saml_login"
          sp.logout: "https://localhost:3002/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: 7.14.2
  count: 1
  elasticsearchRef:
    name: example
  config:
    # Only one authentication source is allowed for the Enterprise Search standalone UI when running in ECK.
    # Beginning in version 8.0, ECK supports multiple auth providers in the Enterprise Search config.
    # Auth source is always elasticsearch-saml
    ent_search.auth.source: elasticsearch-saml
    # Auth name matches the realm name defined in Elasticsearch config
    ent_search.auth.name: ent-search-my-saml
  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: 7.14.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 Platinum features »