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.

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.

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.

openssl req -new -x509 -days 3650 -nodes -sha256 -out saml-sign.crt -keyout saml-sign.key
		

Using the elasticsearch-certutil tool, 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.

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.

By default, Elasticsearch signs all outgoing SAML messages if a signing certificate and key has been configured.

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:

xpack:
  security:
    authc:
      realms:
        saml-realm-name:
          order: 2
          ...
          signing.saml_messages: AuthnRequest
          ...
		

1. This configuration ensures that only SAML authentication requests will be sent signed to the Identity Provider.

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