SAML Authentication
editSAML Authentication
editThe Elastic Stack supports SAML single sign-on (SSO) into Kibana, using Elasticsearch as a backend service.
Elastic Stack SSO requires a valid Enterprise license or Enterprise trial license. See the license documentation for more details about managing licenses.
Make sure you read the complete Configuring SAML single sign-on on the Elastic Stack guide before setting up SAML SSO for Kibana and Elasticsearch deployments managed by ECK.
Add a SAML realm to X-Pack security settings
editTo enable SAML SSO for the Elastic Stack, you have to configure the SAML realm in Elasticsearch and enable the usage of the SAML realm and authentication provider in Kibana.
Elasticsearch
editTo add the SAML realm to Elasticsearch, use the spec
section of the manifest. The SAML realm configuration contains an idp.metadata.path
field that should be set to the path where your IdP’s SAML metadata file is located in the Elasticsearch pods.
The sp.*
SAML settings must point to Kibana endpoints that are accessible from the web browser used to open Kibana.
Check Elastic Stack SAML documentation for more information on idp.*
and sp.*
settings.
Make sure not to disable Elasticsearch’s file realm set by ECK, as ECK relies on the file realm for its operation. Set the order
setting of the SAML realm to a greater value than the order
value set for the file and native realms, which is by default -100 and -99 respectively. We recommend setting the priority of SAML realms to be lower than other realms, as shown in the next example.
apiVersion: elasticsearch.k8s.elastic.co/v1 kind: Elasticsearch metadata: name: elasticsearch-sample spec: version: 8.15.3 nodeSets: - name: default count: 1 config: xpack.security.authc.realms: saml: saml1: attributes.principal: nameid idp.entity_id: https://sso.example.com/ idp.metadata.path: /usr/share/elasticsearch/config/saml/idp-saml-metadata.xml order: 2 sp.acs: https://kibana.example.com/api/security/v1/saml sp.entity_id: https://kibana.example.com sp.logout: https://kibana.example.com/logout
The idp.metadata.path
setting should point to your Identity Provider’s metadata file. The metadata file path can either be a path within the Elasticsearch container (full path or relative to Elasticsearch’s config directory), or an HTTPS URL.
If a path is provided, you need to make the metadata file available in the Elasticsearch container by creating a Kubernetes secret, containing the metadata file, and mounting it to the Elasticsearch container.
After saving your Identity Provider’s metadata file, create the secret. For example:
kubectl create secret generic idp-saml-metadata --from-file=idp-saml-metadata.xml
Next, create a volume from the secret and mount it for the Elasticsearch containers. For example:
apiVersion: elasticsearch.k8s.elastic.co/v1 kind: Elasticsearch metadata: name: elasticsearch-sample spec: version: 8.15.3 nodeSets: - name: default count: 1 config: ... podTemplate: spec: containers: - name: elasticsearch volumeMounts: - name: idp-saml-metadata mountPath: /usr/share/elasticsearch/config/saml volumes: - name: idp-saml-metadata secret: secretName: idp-saml-metadata
To configure Elasticsearch for signing messages and/or for encrypted messages, keys and certificates should be mounted from a Kubernetes secret similar to how the SAML metadata file is mounted in the previous example. Passphrases, if needed, should be added to Elasticsearch’s keystore using ECK’s Secure Settings feature. For more information, check the Secure Settings documentation and the Encryption and signing section in the Stack SAML guide.
Kibana
editTo enable SAML authentication in Kibana, you have to add SAML as an authentication provider and specify the SAML realm that you used in your Elasticsearch configuration.
You can configure multiple authentication providers in Kibana and let users choose the provider they want to use. For more information, check the Kibana authentication documentation.
For example:
apiVersion: kibana.k8s.elastic.co/v1 kind: Kibana metadata: name: kibana-sample spec: version: 8.15.3 count: 1 elasticsearchRef: name: elasticsearch-sample config: xpack.security.authc.providers: saml.saml1: order: 0 realm: "saml1"
Your SAML users cannot login to Kibana until they are assigned roles. For more information, refer to the Configuring role mapping section in the Stack SAML guide.
Generating Service Provider metadata
editThe Elastic Stack supports generating service provider metadata, that can be imported to the identity provider, and configure many of the integration options between the identity provider and the service provider, automatically. For more information, check the Generating SP metadata section in the Stack SAML guide.
To generate the Service Provider metadata using the elasticsearch-saml-metadata command, you will have to run the command using kubectl
, and then copy the generated metadata file to your local machine. For example:
# Create metadata kubectl exec -it elasticsearch-sample-es-default-0 -- sh -c "/usr/share/elasticsearch/bin/elasticsearch-saml-metadata --realm saml1" # Copy metadata file kubectl cp elasticsearch-sample-es-default-0:/usr/share/elasticsearch/saml-elasticsearch-metadata.xml saml-elasticsearch-metadata.xml