--- title: Configure SAML signing and encryption description: Configure Elasticsearch to sign outgoing SAML messages and decrypt incoming encrypted assertions, including certificate generation for PEM, PKCS#12, and JKS formats. url: https://docs-v3-preview.elastic.dev/elastic/docs-content/pull/7484/deploy-manage/users-roles/cluster-or-deployment-auth/saml-signing-encryption products: - Elasticsearch applies_to: - Elastic Stack: Generally available --- # Configure SAML signing and encryption This page is a detailed reference for SAML signing and encryption configuration. For the complete SAML SSO configuration, refer to [SAML authentication](https://docs-v3-preview.elastic.dev/elastic/docs-content/pull/7484/deploy-manage/users-roles/cluster-or-deployment-auth/saml). The Elastic Stack supports generating signed SAML authentication and logout messages, verifying signed messages from the IdP, and processing encrypted content. You can configure Elasticsearch for signing, encryption or both, using a single key or individual keys. The Elastic Stack uses X.509 certificates with RSA private keys for SAML cryptography. These keys can be generated using any standard SSL tool, including the `elasticsearch-certutil` tool. Your IdP might require that the Elastic Stack have a cryptographic key for signing SAML messages, and that you provide the corresponding signing certificate in your Service Provider configuration — either in the Elastic Stack SAML metadata file, or manually in the IdP administration interface. While most IdPs do not expect authentication requests to be signed, signatures are often required for logout requests. Your IdP validates these signatures against the signing certificate that is configured for the Elastic Stack Service Provider. Encryption certificates are rarely needed, but the Elastic Stack supports them for cases where IdPs or local policies mandate their use. ## Generate certificates and keys Elasticsearch supports certificates and keys in either PEM, PKCS#12 or JKS format. Some Identity Providers are more restrictive in the formats they support, and require you to provide the certificates as a file in a particular format. You should consult the documentation for your IdP to determine what formats they support. ### Example: Using `openssl` ```sh openssl req -new -x509 -days 3650 -nodes -sha256 -out saml-sign.crt -keyout saml-sign.key ``` ### Example: Using `elasticsearch-certutil` - Self-managed Elastic deployments: Generally available Using the [`elasticsearch-certutil` tool](https://docs-v3-preview.elastic.dev/elastic/elasticsearch/tree/main/reference/elasticsearch/command-line-tools/certutil), you can generate a signing certificate with the following command. Because PEM format is the most commonly supported format, the example generates a certificate in that format. ```sh bin/elasticsearch-certutil cert --self-signed --pem --days 1100 --name saml-sign --out saml-sign.zip ``` This command does the following: - generate a certificate and key pair (the `cert` subcommand) - create the files in PEM format (`--pem` option) - generate a certificate that is valid for 3 years (`--days 1100`) - name the certificate `saml-sign` (`--name` option) - save the certificate and key in the `saml-sign.zip` file (`--out` option) The generated zip archive contains three files: - `saml-sign.crt`, the public certificate to be used for signing - `saml-sign.key`, the private key for the certificate - `ca.crt`, a CA certificate that is not needed, and can be ignored. Encryption certificates can be generated with the same process. ## Sign outgoing SAML messages By default, Elasticsearch signs *all* outgoing SAML messages if a signing certificate and key has been configured. When configuring a file path in an Elasticsearch setting, keep in mind: - In self-managed clusters, file path settings are resolved relative to the Elasticsearch config directory. Elasticsearch monitors this file for changes and reloads the configuration whenever it is updated. - If you're using Elastic Cloud Hosted or Elastic Cloud Enterprise, upload the file before referencing it in the configuration. For Elastic Cloud Hosted, upload it [as a custom bundle](https://docs-v3-preview.elastic.dev/elastic/docs-content/pull/7484/deploy-manage/deploy/elastic-cloud/upload-custom-plugins-bundles). For Elastic Cloud Enterprise, follow the equivalent [ECE procedure](https://docs-v3-preview.elastic.dev/elastic/docs-content/pull/7484/deploy-manage/deploy/cloud-enterprise/add-custom-bundles-plugins). - If you're using Elastic Cloud on Kubernetes, install the file as a [custom configuration file](/elastic/docs-content/pull/7484/deploy-manage/deploy/cloud-on-k8s/custom-configuration-files-plugins#use-a-volume-and-volume-mount-together-with-a-configmap-or-secret). If you want to use **PEM formatted** keys and certificates for signing, then you should configure the following settings on the SAML realm: The path to the PEM formatted certificate file. for example, `saml/saml-sign.crt` Only the single leaf certificate is required for the `signing.certificate` setting, even when using an internal or non-public Certificate Authority (CA). If additional certificates are included, Elasticsearch attempts to validate the resulting chain, and the chain must be valid and complete. The path to the PEM formatted key file. for example, `saml/saml-sign.key` The passphrase for the key, if the file is encrypted. This is a secure setting that must be uploaded to your [Elasticsearch keystore](https://docs-v3-preview.elastic.dev/elastic/docs-content/pull/7484/deploy-manage/security/secure-settings). If you want to use **PKCS#12 formatted** files or a **Java Keystore** for signing, then you should configure the following settings on the SAML realm: The path to the PKCS#12 or JKS keystore. for example, `saml/saml-sign.p12` The alias of the key within the keystore. for example, `signing-key` The passphrase for the keystore, if the file is encrypted. This is a secure setting that must be uploaded to your [Elasticsearch keystore](https://docs-v3-preview.elastic.dev/elastic/docs-content/pull/7484/deploy-manage/security/secure-settings). ### Sign only certain message types If you want to sign some, but not all outgoing SAML messages, then configure `signing.saml_messages` with a comma separated list of message types to sign. Supported values are `AuthnRequest`, `LogoutRequest` and `LogoutResponse` and the default value is `*`. For example: ```yaml xpack: security: authc: realms: saml-realm-name: order: 2 ... signing.saml_messages: AuthnRequest ... ``` ## Configure Elasticsearch for encrypted messages Elasticsearch supports a single key for message decryption. If a key is configured, then Elasticsearch attempts to use it to decrypt `EncryptedAssertion` and `EncryptedAttribute` elements in Authentication responses, and `EncryptedID` elements in Logout requests. Elasticsearch rejects any SAML message that contains an `EncryptedAssertion` that cannot be decrypted. If an `Assertion` contains both encrypted and plain-text attributes, then failure to decrypt the encrypted attributes does not cause an automatic rejection. Rather, Elasticsearch processes the available plain-text attributes (and any `EncryptedAttributes` that could be decrypted). When configuring a file path in an Elasticsearch setting, keep in mind: - In self-managed clusters, file path settings are resolved relative to the Elasticsearch config directory. Elasticsearch monitors this file for changes and reloads the configuration whenever it is updated. - If you're using Elastic Cloud Hosted or Elastic Cloud Enterprise, upload the file before referencing it in the configuration. For Elastic Cloud Hosted, upload it [as a custom bundle](https://docs-v3-preview.elastic.dev/elastic/docs-content/pull/7484/deploy-manage/deploy/elastic-cloud/upload-custom-plugins-bundles). For Elastic Cloud Enterprise, follow the equivalent [ECE procedure](https://docs-v3-preview.elastic.dev/elastic/docs-content/pull/7484/deploy-manage/deploy/cloud-enterprise/add-custom-bundles-plugins). - If you're using Elastic Cloud on Kubernetes, install the file as a [custom configuration file](/elastic/docs-content/pull/7484/deploy-manage/deploy/cloud-on-k8s/custom-configuration-files-plugins#use-a-volume-and-volume-mount-together-with-a-configmap-or-secret). If you want to use **PEM formatted** keys and certificates for SAML encryption, then you should configure the following settings on the SAML realm: The path to the PEM formatted certificate file. for example, `saml/saml-crypt.crt` Only the single leaf certificate is required for the `encryption.certificate` setting, even when using an internal or non-public Certificate Authority (CA). If additional certificates are included, Elasticsearch will attempt to validate the resulting chain, and the chain must be valid and complete. The path to the PEM formatted key file. for example, `saml/saml-crypt.key` The passphrase for the key, if the file is encrypted. This is a secure setting that must be uploaded to your [Elasticsearch keystore](https://docs-v3-preview.elastic.dev/elastic/docs-content/pull/7484/deploy-manage/security/secure-settings). If you want to use **PKCS#12 formatted** files or a **Java Keystore** for SAML encryption, then you should configure the following settings on the SAML realm: The path to the PKCS#12 or JKS keystore. for example, `saml/saml-crypt.p12` The alias of the key within the keystore. for example, `encryption-key` The passphrase for the keystore, if the file is encrypted. This is a secure setting that must be uploaded to your [Elasticsearch keystore](https://docs-v3-preview.elastic.dev/elastic/docs-content/pull/7484/deploy-manage/security/secure-settings).