- Elasticsearch Guide: other versions:
- Elasticsearch introduction
- Getting started with Elasticsearch
- Set up Elasticsearch
- Installing Elasticsearch
- Configuring Elasticsearch
- Important Elasticsearch configuration
- Important System Configuration
- Bootstrap Checks
- Heap size check
- File descriptor check
- Memory lock check
- Maximum number of threads check
- Max file size check
- Maximum size virtual memory check
- Maximum map count check
- Client JVM check
- Use serial collector check
- System call filter check
- OnError and OnOutOfMemoryError checks
- Early-access check
- G1GC check
- All permission check
- Discovery configuration check
- Starting Elasticsearch
- Stopping Elasticsearch
- Adding nodes to your cluster
- Set up X-Pack
- Configuring X-Pack Java Clients
- Bootstrap Checks for X-Pack
- Upgrade Elasticsearch
- API conventions
- Document APIs
- Search APIs
- Aggregations
- Metrics Aggregations
- Avg Aggregation
- Weighted Avg Aggregation
- Cardinality Aggregation
- Extended Stats Aggregation
- Geo Bounds Aggregation
- Geo Centroid Aggregation
- Max Aggregation
- Min Aggregation
- Percentiles Aggregation
- Percentile Ranks Aggregation
- Scripted Metric Aggregation
- Stats Aggregation
- Sum Aggregation
- Top Hits Aggregation
- Value Count Aggregation
- Median Absolute Deviation Aggregation
- Bucket Aggregations
- Adjacency Matrix Aggregation
- Auto-interval Date Histogram Aggregation
- Children Aggregation
- Composite Aggregation
- Date Histogram Aggregation
- Date Range Aggregation
- Diversified Sampler Aggregation
- Filter Aggregation
- Filters Aggregation
- Geo Distance Aggregation
- GeoHash grid Aggregation
- GeoTile Grid Aggregation
- Global Aggregation
- Histogram Aggregation
- IP Range Aggregation
- Missing Aggregation
- Nested Aggregation
- Parent Aggregation
- Range Aggregation
- Reverse nested Aggregation
- Sampler Aggregation
- Significant Terms Aggregation
- Significant Text Aggregation
- Terms Aggregation
- Pipeline Aggregations
- Avg Bucket Aggregation
- Derivative Aggregation
- Max Bucket Aggregation
- Min Bucket Aggregation
- Sum Bucket Aggregation
- Stats Bucket Aggregation
- Extended Stats Bucket Aggregation
- Percentiles Bucket Aggregation
- Moving Average Aggregation
- Moving Function Aggregation
- Cumulative Sum Aggregation
- Bucket Script Aggregation
- Bucket Selector Aggregation
- Bucket Sort Aggregation
- Serial Differencing Aggregation
- Matrix Aggregations
- Caching heavy aggregations
- Returning only aggregation results
- Aggregation Metadata
- Returning the type of the aggregation
- Metrics Aggregations
- Indices APIs
- Create Index
- Delete Index
- Get Index
- Indices Exists
- Open / Close Index API
- Shrink Index
- Split Index
- Rollover Index
- Put Mapping
- Get Mapping
- Get Field Mapping
- Types Exists
- Index Aliases
- Update Indices Settings
- Get Settings
- Analyze
- Index Templates
- Indices Stats
- Indices Segments
- Indices Recovery
- Indices Shard Stores
- Clear Cache
- Flush
- Refresh
- Force Merge
- cat APIs
- Cluster APIs
- Query DSL
- Scripting
- Mapping
- Analysis
- Anatomy of an analyzer
- Testing analyzers
- Analyzers
- Normalizers
- Tokenizers
- Standard Tokenizer
- Letter Tokenizer
- Lowercase Tokenizer
- Whitespace Tokenizer
- UAX URL Email Tokenizer
- Classic Tokenizer
- Thai Tokenizer
- NGram Tokenizer
- Edge NGram Tokenizer
- Keyword Tokenizer
- Pattern Tokenizer
- Char Group Tokenizer
- Simple Pattern Tokenizer
- Simple Pattern Split Tokenizer
- Path Hierarchy Tokenizer
- Path Hierarchy Tokenizer Examples
- Token Filters
- ASCII Folding Token Filter
- Flatten Graph Token Filter
- Length Token Filter
- Lowercase Token Filter
- Uppercase Token Filter
- NGram Token Filter
- Edge NGram Token Filter
- Porter Stem Token Filter
- Shingle Token Filter
- Stop Token Filter
- Word Delimiter Token Filter
- Word Delimiter Graph Token Filter
- Multiplexer Token Filter
- Conditional Token Filter
- Predicate Token Filter Script
- Stemmer Token Filter
- Stemmer Override Token Filter
- Keyword Marker Token Filter
- Keyword Repeat Token Filter
- KStem Token Filter
- Snowball Token Filter
- Phonetic Token Filter
- Synonym Token Filter
- Parsing synonym files
- Synonym Graph Token Filter
- Compound Word Token Filters
- Reverse Token Filter
- Elision Token Filter
- Truncate Token Filter
- Unique Token Filter
- Pattern Capture Token Filter
- Pattern Replace Token Filter
- Trim Token Filter
- Limit Token Count Token Filter
- Hunspell Token Filter
- Common Grams Token Filter
- Normalization Token Filter
- CJK Width Token Filter
- CJK Bigram Token Filter
- Delimited Payload Token Filter
- Keep Words Token Filter
- Keep Types Token Filter
- Exclude mode settings example
- Classic Token Filter
- Apostrophe Token Filter
- Decimal Digit Token Filter
- Fingerprint Token Filter
- MinHash Token Filter
- Remove Duplicates Token Filter
- Character Filters
- Modules
- Index modules
- Ingest node
- Pipeline Definition
- Ingest APIs
- Accessing Data in Pipelines
- Conditional Execution in Pipelines
- Handling Failures in Pipelines
- Processors
- Append Processor
- Bytes Processor
- Convert Processor
- Date Processor
- Date Index Name Processor
- Dissect Processor
- Dot Expander Processor
- Drop Processor
- Fail Processor
- Foreach Processor
- GeoIP Processor
- Grok Processor
- Gsub Processor
- HTML Strip Processor
- Join Processor
- JSON Processor
- KV Processor
- Lowercase Processor
- Pipeline Processor
- Remove Processor
- Rename Processor
- Script Processor
- Set Processor
- Set Security User Processor
- Split Processor
- Sort Processor
- Trim Processor
- Uppercase Processor
- URL Decode Processor
- User Agent processor
- Managing the index lifecycle
- Getting started with index lifecycle management
- Policy phases and actions
- Set up index lifecycle management policy
- Using policies to manage index rollover
- Update policy
- Index lifecycle error handling
- Restoring snapshots of managed indices
- Start and stop index lifecycle management
- Using ILM with existing indices
- SQL access
- Overview
- Getting Started with SQL
- Conventions and Terminology
- Security
- SQL REST API
- SQL Translate API
- SQL CLI
- SQL JDBC
- SQL ODBC
- SQL Client Applications
- SQL Language
- Functions and Operators
- Comparison Operators
- Logical Operators
- Math Operators
- Cast Operators
- LIKE and RLIKE Operators
- Aggregate Functions
- Grouping Functions
- Date/Time and Interval Functions and Operators
- Full-Text Search Functions
- Mathematical Functions
- String Functions
- Type Conversion Functions
- Geo Functions
- Conditional Functions And Expressions
- System Functions
- Reserved keywords
- SQL Limitations
- Monitor a cluster
- Frozen indices
- Set up a cluster for high availability
- Roll up or transform your data
- X-Pack APIs
- Info API
- Cross-cluster replication APIs
- Explore API
- Freeze index
- Index lifecycle management API
- Licensing APIs
- Machine learning APIs
- Add events to calendar
- Add jobs to calendar
- Close jobs
- Create jobs
- Create calendar
- Create datafeeds
- Create filter
- Delete calendar
- Delete datafeeds
- Delete events from calendar
- Delete filter
- Delete forecast
- Delete jobs
- Delete jobs from calendar
- Delete model snapshots
- Delete expired data
- Find file structure
- Flush jobs
- Forecast jobs
- Get calendars
- Get buckets
- Get overall buckets
- Get categories
- Get datafeeds
- Get datafeed statistics
- Get influencers
- Get jobs
- Get job statistics
- Get machine learning info
- Get model snapshots
- Get scheduled events
- Get filters
- Get records
- Open jobs
- Post data to jobs
- Preview datafeeds
- Revert model snapshots
- Set upgrade mode
- Start datafeeds
- Stop datafeeds
- Update datafeeds
- Update filter
- Update jobs
- Update model snapshots
- Migration APIs
- Rollup APIs
- Security APIs
- Authenticate
- Change passwords
- Clear cache
- Clear roles cache
- Create API keys
- Create or update application privileges
- Create or update role mappings
- Create or update roles
- Create or update users
- Delete application privileges
- Delete role mappings
- Delete roles
- Delete users
- Disable users
- Enable users
- Get API key information
- Get application privileges
- Get role mappings
- Get roles
- Get token
- Get users
- Has privileges
- Invalidate API key
- Invalidate token
- OpenID Connect Prepare Authentication API
- OpenID Connect Authenticate API
- OpenID Connect Logout API
- SSL certificate
- Transform APIs
- Unfreeze index
- Watcher APIs
- Definitions
- Secure a cluster
- Overview
- Configuring security
- Encrypting communications in Elasticsearch
- Encrypting communications in an Elasticsearch Docker Container
- Enabling cipher suites for stronger encryption
- Separating node-to-node and client traffic
- Configuring an Active Directory realm
- Configuring a file realm
- Configuring an LDAP realm
- Configuring a native realm
- Configuring a PKI realm
- Configuring a SAML realm
- Configuring a Kerberos realm
- Security files
- FIPS 140-2
- How security works
- User authentication
- Built-in users
- Internal users
- Token-based authentication services
- Realms
- Realm chains
- Active Directory user authentication
- File-based user authentication
- LDAP user authentication
- Native user authentication
- OpenID Connect authentication
- PKI user authentication
- SAML authentication
- Kerberos authentication
- Integrating with other authentication systems
- Enabling anonymous access
- Controlling the user cache
- Configuring SAML single-sign-on on the Elastic Stack
- Configuring single sign-on to the Elastic Stack using OpenID Connect
- User authorization
- Auditing security events
- Encrypting communications
- Restricting connections with IP filtering
- Cross cluster search, clients, and integrations
- Tutorial: Getting started with security
- Tutorial: Encrypting communications
- Troubleshooting
- Some settings are not returned via the nodes settings API
- Authorization exceptions
- Users command fails due to extra arguments
- Users are frequently locked out of Active Directory
- Certificate verification fails for curl on Mac
- SSLHandshakeException causes connections to fail
- Common SSL/TLS exceptions
- Common Kerberos exceptions
- Common SAML issues
- Internal Server Error in Kibana
- Setup-passwords command fails due to connection failure
- Failures due to relocation of the configuration files
- Limitations
- Alerting on cluster and index events
- Command line tools
- How To
- Testing
- Glossary of terms
- Release highlights
- Breaking changes
- Release notes
- Elasticsearch version 7.2.1
- Elasticsearch version 7.2.0
- Elasticsearch version 7.1.1
- Elasticsearch version 7.1.0
- Elasticsearch version 7.0.0
- Elasticsearch version 7.0.0-rc2
- Elasticsearch version 7.0.0-rc1
- Elasticsearch version 7.0.0-beta1
- Elasticsearch version 7.0.0-alpha2
- Elasticsearch version 7.0.0-alpha1
Common SAML issues
editCommon SAML issues
editSome of the common SAML problems are shown below with tips on how to resolve these issues.
-
Symptoms:
Authentication in Kibana fails and the following error is printed in the Elasticsearch logs:
Cannot find any matching realm for [SamlPrepareAuthenticationRequest{realmName=null, assertionConsumerServiceURL=https://my.kibana.url/api/security/v1/saml}]
Resolution:
Elasticsearch, Kibana and your Identity Provider need all have the same view on what the Assertion Consumer Service URL of the SAML Service Provider is.
-
Elasticsearch discovers this via the
sp.acs
setting in your Elasticsearch SAML realm configuration -
Kibana constructs this value using the
server.host
andserver.port
inkibana.yml
. For instance:server.host: kibanaserver.org server.port: 3456
These settings would mean that Kibana would construct the Assertion Consumer Service URL as
https://kibanaserver.org:3456/api/security/v1/saml
. However, if for example, Kibana is behind a reverse proxy and you have configured the followingxpack.security.public.*
settings:xpack.security.public: protocol: https hostname: kibana.proxy.com port: 8080
These settings would instruct Kibana to construct the Assertion Consumer Service URL as
https://kibana.proxy.com:8080/api/security/v1/saml
-
The SAML Identity Provider is either explicitly configured by the IdP
administrator or consumes the SAML metadata that are generated by Elasticsearch and as
such contain the same value for the
as the one
that is configured in the the
sp.acs
setting in the Elasticsearch SAML realm configuration.
The error encountered here indicates that the Assertion Consumer Service URL that Kibana has constructed via one of the aforementioned ways (
https://my.kibana.url/api/security/v1/saml
) is not the one that Elasticsearch is configured with. Note that these two URLs are compared as case-sensitive strings and not as canonicalized URLs.Often, this can be resolved by changing the
sp.acs
URL inelasticearch.yml
to match the value that Kibana has constructed. Note however, that the SAML IdP configuration needs to also be adjusted to reflect this change.Alternatively, if you think Kibana is using the wrong value for the Assertion Consumer Service URL, you will need to change the configuration in
kibana.yml
by adjusting either theserver.host
andserver.port
to change the URL Kibana listens to or thexpack.security.public.*
settings to make Kibana aware about its correct public URL. -
Elasticsearch discovers this via the
-
Symptoms:
Authentication in Kibana fails and the following error is printed in the Elasticsearch logs:
Authentication to realm saml1 failed - Provided SAML response is not valid for realm saml/saml1 (Caused by ElasticsearchSecurityException[Conditions [https://some-url-here...] do not match required audience [https://my.kibana.url]])
Resolution:
We received a SAML response that is addressed to another SAML Service Provider. This usually means that the configured SAML Service Provider Entity ID in
elasticsearch.yml
(sp.entity_id
) does not match what has been configured as the SAML Service Provider Entity ID in the SAML Identity Provider documentation.To resolve this issue, ensure that both the saml realm in Elasticsearch and the IdP are configured with the same string for the SAML Entity ID of the Service Provider.
These strings are compared as case-sensitive strings and not as canonicalized URLs even when the values are URL-like. Be mindful of trailing slashes, port numbers, etc.
-
Symptoms:
Authentication in Kibana fails and the following error is printed in the Elasticsearch logs:
Cannot find metadata for entity [your:entity.id] in [metadata.xml]
Resolution:
We could not find the metadata for the SAML Entity ID
your:entity.id
in the configured metadata file (metadata.xml
).-
Ensure that the
metadata.xml
file you are using is indeed the one provided by your SAML Identity Provider. -
Ensure that the
metadata.xml
file contains one <EntityDescriptor> element as follows:<EntityDescriptor ID="0597c9aa-e69b-46e7-a1c6-636c7b8a8070" entityID="https://saml.example.com/f174199a-a96e-4201-88f1-0d57a610c522/" ...
where the value of theentityID
attribute is the same as the value of theidp.entity_id
that you have set in your SAML realm configuration inelasticsearch.yml
. - Note that these are also compared as case-sensitive strings and not as canonicalized URLs even when the values are URL-like.
-
Ensure that the
-
Symptoms:
Authentication in Kibana fails and the following error is printed in the Elasticsearch logs:
unable to authenticate user [<unauthenticated-saml-user>] for action [cluster:admin/xpack/security/saml/authenticate]
Resolution:
This error indicates that Elasticsearch failed to process the incoming SAML authentication message. Since the message can’t be processed, Elasticsearch is not aware of who the to-be authenticated user is and the
<unauthenticated-saml-user>
placeholder is used instead. To diagnose the actual problem, you must check the Elasticsearch logs for further details. -
Symptoms:
Authentication in Kibana fails and the following error is printed in the Elasticsearch logs:
Authentication to realm my-saml-realm failed - Provided SAML response is not valid for realm saml/my-saml-realm (Caused by ElasticsearchSecurityException[SAML Response is not a 'success' response: The SAML IdP did not grant the request. It indicated that the Elastic Stack side sent something invalid (urn:oasis:names:tc:SAML:2.0:status:Requester). Specific status code which might indicate what the issue is: [urn:oasis:names:tc:SAML:2.0:status:InvalidNameIDPolicy]] )
Resolution:
This means that the SAML Identity Provider failed to authenticate the user and sent a SAML Response to the Service Provider (Elastic Stack) indicating this failure. The message will convey whether the SAML Identity Provider thinks that the problem is with the Service Provider (Elastic Stack) or with the Identity Provider itself and the specific status code that follows is extremely useful as it usually indicates the underlying issue. The list of specific error codes is defined in the SAML 2.0 Core specification - Section 3.2.2.2 and the most commonly encountered ones are:
-
urn:oasis:names:tc:SAML:2.0:status:AuthnFailed
: The SAML Identity Provider failed to authenticate the user. There is not much to troubleshoot on the Elastic Stack side for this status, the logs of the SAML Identity Provider will hopefully offer much more information. -
urn:oasis:names:tc:SAML:2.0:status:InvalidNameIDPolicy
: The SAML Identity Provider cannot support releasing a NameID with the requested format. When creating SAML Authentication Requests, Elasticsearch sets the NameIDPolicy element of the Authentication request with the appropriate value. This is controlled by thenameid_format
configuration parameter inelasticsearch.yml
, which if not set defaults tourn:oasis:names:tc:SAML:2.0:nameid-format:transient
. This instructs the Identity Provider to return a NameID with that specific format in the SAML Response. If the SAML Identity Provider cannot grant that request, for example because it is configured to release a NameID format withurn:oasis:names:tc:SAML:2.0:nameid-format:persistent
format instead, it returns this error indicating an invalid NameID policy. This issue can be resolved by adjustingnameid_format
to match the format the SAML Identity Provider can return or by setting it tourn:oasis:names:tc:SAML:2.0:nameid-format:unspecified
so that the Identity Provider is allowed to return any format it wants.
-
-
Symptoms:
Authentication in Kibana fails and the following error is printed in the Elasticsearch logs:
The XML Signature of this SAML message cannot be validated. Please verify that the saml realm uses the correct SAMLmetadata file/URL for this Identity Provider
Resolution:
This means that Elasticsearch failed to validate the digital signature of the SAML message that the Identity Provider sent. Elasticsearch uses the public key of the Identity Provider that is included in the SAML metadata, in order to validate the signature that the IdP has created using its corresponding private key. Failure to do so, can have a number of causes:
- As the error message indicates, the most common cause is that the wrong metadata file is used and as such the public key it contains doesn’t correspond to the private key the Identity Provider uses.
- The configuration of the Identity Provider has changed or the key has been rotated and the metadata file that Elasticsearch is using has not been updated.
- The SAML Response has been altered in transit and the signature cannot be validated even though the correct key is used.
The private keys and public keys and self-signed X.509 certificates that are used in SAML for digital signatures as described above have no relation to the keys and certificates that are used for TLS either on the transport or the http layer. A failure such as the one described above has nothing to do with your
xpack.ssl
related configuration. -
Symptoms:
Users are unable to login with a local username and password in Kibana because SAML is enabled.
Resolution:
If you want your users to be able to use local credentials to authenticate to Kibana in addition to using the SAML realm for Single Sign-On, you must enable the
basic
authProvider
in Kibana. The process is documented in the SAML Guide
Logging:
Very detailed trace logging can be enabled specifically for the SAML realm by setting the following transient setting:
PUT /_cluster/settings { "transient": { "logger.org.elasticsearch.xpack.security.authc.saml": "trace" } }
Alternatively, you can add the following lines to the end of the
log4j2.properties
configuration file in the ES_PATH_CONF
:
logger.saml.name = org.elasticsearch.xpack.security.authc.saml logger.saml.level = TRACE