# Configuring SAML Global Variables Before you can authenticate users with SAML, you must configure each SingleStore aggregator node’s **memsql.cnf** file. The default values for three of the variables is `OFF`: ```sql SHOW VARIABLES LIKE 'saml%'; ``` ```output +-----------------------------------+-------+ | Variable_name | Value | +-----------------------------------+-------+ | saml_assertion_audience | | | saml_message_recipient | | | saml_private_decryption_key | | | saml_require_encryption | OFF | | saml_require_signature_validation | OFF | | saml_use_NameID | OFF | | saml_user_name_attribute | | | saml_x509_certificate | | +-----------------------------------+-------+ 8 rows in set (0.00 sec) ``` To enable SAML authentication, the **memsql.cnf** file on each master aggregator must specify values for one or more of these variables — you cannot use the `SET GLOBAL` statement. The values are set on server startup and can only be read afterwards. If you want to modify the configuration, each aggregator node in the cluster must be restarted after any changes have been made. The settings for each configuration variable depend on the expected structure of an incoming SAML assertion, and a number of configuration combinations are possible. ## Minimum Configurations Two minimum **memsql.cnf** configurations are possible with SAML authentication, and each depends on how the incoming SAML assertion specifies the username credential. ## NameID Configuration If the incoming SAML assertion identifies a username with the `` element, you can set the `saml_use_NameID` variable to `ON`. The following configuration assumes that neither an x509 certificate, signature, audience restriction, recipient, nor any encryption exists in the assertion. New connections default to generating requests with `NameID=Persistent`. You can however specify the `nameID` format in SAML requests. For best interoperability and consistency, the `NameID` format should be set to "`Persistent`" if your IdP supports it. This ensures the `NameID` remains stable across sessions and user management events. If your configuration requires a different `NameID` format, ensure that both the Identity Provider and Service Provider (SingleStore) are configured to recognize and handle the chosen format. ``` [server] ... saml_use_NameID = ON ... ``` ## Attribute Name Configuration If the incoming SAML assertion identifies a username with a `` element, you can set the `saml_user_name_attribute` variable to its value. The following configuration assumes that neither an x509 certificate, signature, audience restriction, recipient, nor any encryption exists in the assertion. **Minimum configuration for Attribute Name element.** ``` [server] ... saml_user_name_attribute = ... ``` ## Maximum Configuration and Other Options SAML assertions are usually validated using more than just a username, so the minimum configuration options in the section above must be expanded upon. The following configuration demonstrates one possible maximum configuration, which assumes `` is being used for username mapping instead of ``: ``` [server] ... saml_assertion_audience = https://my.example.com/service/ saml_message_recipient = initech saml_private_decryption_key = ../local/file/path/private-key.pem saml_require_encryption = ON saml_require_signature_validation = ON saml_use_NameID = ON saml_x509_certificate = ../local/file/path/public-key.crt ... ``` Various other combinations are possible, depending on whether the incoming SAML assertion contains encrypted data, has restricted audiences or recipients, and if signature validation is required. ## Signing Variables If the SAML assertion is signed, at minimum the `saml_x509_certificate` variable should be set. For example: ``` [server] ... saml_use_NameID = ON saml_x509_certificate= ../local/file/path/public-key.crt ... ``` ## Encryption Variables If the SAML assertion contains encrypted data, at minimum the `saml_private_decryption_key` variable should be set. For example: ``` [server] ... saml_use_NameID = ON saml_private_decryption_key = ../local/file/path/private-key.pem ... ``` ## saml\_user\_name\_attribute Specifies the username attribute in a SAML assertion that should be used to determine if a user exists in the database. Identity providers can use arbitrary attribute names to specify a username. Some identity providers might use `username`, `user_id`, or other values. For example, consider the following snippet from a SAML assertion: ``` ... johndoe ... ``` In the assertion above, an attribute named `username` is specified with an attribute value of `johndoe`. The `saml_user_name_attribute` variable is used to map this attribute’s value so that `johndoe` will be used as the user name when authenticating to the database. ## Examples ``` saml_user_name_attribute = username ``` ```sql SHOW GLOBAL VARIABLES LIKE 'saml_user_name_attribute'; ``` ```output +--------------------------+----------+ | Variable_name | Value | +--------------------------+----------+ | saml_user_name_attribute | username | +--------------------------+----------+ 1 row in set (0.00 sec) ``` ## saml\_use\_NameID Specifies whether a username value should be extracted from the `` element in a SAML assertion. This value is used to determine if a user exists in the database during authentication. The default value is `OFF`. If set to `OFF`, this element is ignored and the `saml_user_name_attribute` variable must be set instead. If set to `ON`, the `saml_user_name_attribute` variable is ignored. Consider the following example from a SAML assertion: ``` johndoe ... ``` In the example above, the `NameID` element’s value is `johndoe`. If the `saml_use_NameID` engine variable is set to `ON`, `johndoe` will be used as the username credential during authentication. ## Examples ``` saml_use_NameID = ON ``` ```sql SHOW GLOBAL VARIABLES LIKE 'saml_use_NameID'; ``` ```output +-----------------+-------+ | Variable_name | Value | +-----------------+-------+ | saml_use_NameID | ON | +-----------------+-------+ 1 row in set (0.00 sec) ``` ## saml\_require\_encryption Specifies if authentication should fail when both the SAML response and SAML assertion are unencrypted. The default value is `OFF`. To require encryption, set this variable to `ON`. If your security requirements include encrypted SAML responses or SAML assertions, this variable ensures that authentication will fail when neither are encrypted. This variable is dependent on the presence of a valid PEM certificate, which is specified in the `saml_private_decryption_key` engine variable. In light of this dependency, three possible cases should be considered: * If required encryption is set to `ON` but no PEM certificate is specified, authentication will fail. * If a SAML assertion doesn’t contain a encrypted data and the requirement is set to `OFF`, the specified PEM certificate is ignored. * If a SAML assertion does contain encrypted data and the requirement is set to `OFF`, a PEM certificate must be present. ## Examples ``` saml_require_encryption = ON ``` ```sql SHOW GLOBAL VARIABLES LIKE 'saml_require_encryption'; ``` ```output +-------------------------+-------+ | Variable_name | Value | +-------------------------+-------+ | saml_require_encryption | ON | +-------------------------+-------+ 1 row in set (0.00 sec) ``` ## saml\_require\_signature\_validation Specifies if authentication should fail when both the SAML response and SAML assertion are unsigned. The default value is `OFF`. To require signature validation, set this variable to `ON`. If your security requirements include signed SAML responses or SAML assertions, this variable ensures that authentication will fail when neither are signed. This variable is dependent on the presence of a valid x509 certificate, which is specified in the `saml_x509_certificate` engine variable. In light of this dependency, three possible cases should be considered: * If signature validation is set to `ON` but no x509 certificate is specified, authentication will fail. * If a SAML assertion doesn’t contain a signature and validation is set to `OFF`, the specified x509 certificate is ignored. * If a SAML assertion does contain a signature and validation is set to `OFF`, an x509 certificate must be present. ## Examples ``` saml_require_signature_validation = ON ``` ```sql SHOW GLOBAL VARIABLES LIKE 'saml_require_signature_validation'; ``` ```output +-----------------------------------+-------+ | Variable_name | Value | +-----------------------------------+-------+ | saml_require_signature_validation | ON | +-----------------------------------+-------+ 1 row in set (0.00 sec) ``` ## saml\_x509\_certificate Specifies the file path for the identity provider’s public x509 signing certificate. This file path needs to be relative to SingleStore’s base directory; it cannot be an absolute path. An identity provider uses a private key to sign SAML responses. The public key is used by third parties to validate the response. The `saml_x509_certificate` variable points the database to the path of this public key and uses it to validate security tokens. No validation is performed on this file path when SingleStore is started; validation occurs when a user attempts to authenticate to the database. ## Examples ``` saml_x509_certificate = ../local/file/path/public-key.crt ``` ```sql SHOW GLOBAL VARIABLES LIKE 'saml_x509_certificate'; ``` ```output +-----------------------+-----------------------------------+ | Variable_name | Value | +-----------------------+-----------------------------------+ | saml_x509_certificate | ../local/file/path/public-key.crt | +-----------------------+-----------------------------------+ 1 row in set (0.00 sec) ``` ## saml\_private\_decryption\_key Specifies the file path for the private key that is used to decrypt an encrypted assertion. The file path needs to be relative to SingleStore’s base directory; it cannot be an absolute path. An identity provider can encrypt assertions within a SAML response by using a previously supplied public key. The private key can be used to decrypt an encrypted assertion. The `saml_private_decryption_key` points the database to the path of this public key and uses it to decrypt the assertions. No validation is performed on this file path when SingleStore is started; validation occurs when a user attempts to authenticate to the database. ## Examples ``` saml_private_decryption_key = ../local/file/path/private-key.pem ``` ```sql SHOW GLOBAL VARIABLES LIKE 'saml_private_decryption_key'; ``` ```output +-----------------------------+------------------------------------+ | Variable_name | Value | +-----------------------------+------------------------------------+ | saml_private_decryption_key | ../local/file/path/private-key.pem | +-----------------------------+------------------------------------+ 1 row in set (0.00 sec) ``` ## saml\_message\_recipient Specifies the intended recipient for a wrapped encryption key. A SAML response may contain encrypted data in the `` element. To decrypt this data, the response may also contain an `` element, which is often intended for a specific recipient. For example: `` The `saml_message_recipient` variable is used to validate that the intended recipient of a message is the same. If a SAML response’s encryption key does not have a recipient attribute, validation will be skipped. ## Examples ``` saml_message_recipient = recipient@domain.com ``` ```sql SHOW GLOBAL VARIABLES LIKE 'saml_message_recipient'; ``` ```output +------------------------+----------------------+ | Variable_name | Value | +------------------------+----------------------+ | saml_message_recipient | recipient@domain.com | +------------------------+----------------------+ 1 row in set (0.00 sec) ``` ## saml\_assertion\_audience Specifies a single audience restriction for the SAML assertion. SAML assertions can be restricted to specific audiences. For example, consider the following snippet from a SAML assertion: ``` ... https://my.example.com/service/ https://my.otherexample.com/service/ ... ``` The assertion above is restricted to the two audiences specified in the `` elements. If the server receives a SAML response that has an Audience Restriction, it validates that the `saml_assertion_audience` variable matches at least one of the audiences in the restriction. ## Examples ``` saml_assertion_audience = https://my.example.com/service/ ``` ```sql SHOW GLOBAL VARIABLES LIKE 'saml_assertion_audience'; ``` ```output +-------------------------+---------------------------------+ | Variable_name | Value | +-------------------------+---------------------------------+ | saml_assertion_audience | https://my.example.com/service/ | +-------------------------+---------------------------------+ 1 row in set (0.00 sec) ``` *** Modified at: October 9, 2025 Source: [/db/v9.1/security/authentication/saml-authentication/configuring-saml-global-variables/](https://docs.singlestore.com/db/v9.1/security/authentication/saml-authentication/configuring-saml-global-variables/) (An index of the documentation is available at /llms.txt)