Outdated Version

You are viewing an older version of this section. View current production version.

/Security/

Configuring SAML Global Variables min read

Info

This topic does not apply to SingleStore Managed Service.

Before you can authenticate users with SAML, you must configure each aggregator node’s memsql.cnf file. The default values for three of the variables is OFF:

memsql> SHOW VARIABLES LIKE 'saml%';
+-----------------------------------+-------+
| 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 <saml:NameID> 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.

[server]
...
saml_use_NameID = ON
...

Attribute Name Configuration

If the incoming SAML assertion identifies a username with a <saml:Attribute Name=""> 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 = <my-username-identifier>
...

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 <saml:NameID> is being used for username mapping instead of <saml:Attribute Name="">:

[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:

<saml:Assertion xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xs="http://www.w3.org/2001/XMLSchema" ID="_d71a3a8e9fcc45c9e9d248ef7049393fc8f04e5f75" Version="2.0" IssueInstant="2014-07-17T01:01:48Z">
  ...
  <saml:AttributeStatement>
    <saml:Attribute Name="username" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:basic">
      <saml:AttributeValue xsi:type="xs:string">johndoe</saml:AttributeValue>
    </saml:Attribute>
  </saml:AttributeStatement>
  ...
</saml:Assertion>

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

memsql> SHOW GLOBAL VARIABLES LIKE 'saml_user_name_attribute';
+--------------------------+----------+
| 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 <saml:NameID> 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:

<saml:Subject>
   <saml:NameID Format="urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified" NameQualifier="my.service.com">johndoe</saml:NameID>
   ...
</saml:Subject>

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

memsql> SHOW GLOBAL VARIABLES LIKE 'saml_use_NameID';
+-----------------+-------+
| 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

memsql> SHOW GLOBAL VARIABLES LIKE 'saml_require_encryption';
+-------------------------+-------+
| 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

memsql> SHOW GLOBAL VARIABLES LIKE 'saml_require_signature_validation';
+-----------------------------------+-------+
| 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 DB’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 DB is started; validation occurs when a user attempts to authenticate to the database.

Examples

saml_x509_certificate = ../local/file/path/public-key.crt

memsql> SHOW GLOBAL VARIABLES LIKE 'saml_x509_certificate';
+-----------------------+-----------------------------------+
| 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 DB’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 DB is started; validation occurs when a user attempts to authenticate to the database.

Examples

saml_private_decryption_key = ../local/file/path/private-key.pem

memsql> SHOW GLOBAL VARIABLES LIKE 'saml_private_decryption_key';
+-----------------------------+------------------------------------+
| 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 <xenc:EncryptedData> element. To decrypt this data, the response may also contain an <xenc:EncryptedKey> element, which is often intended for a specific recipient. For example: <xenc:EncryptedKey Recipient="recipient@domain.com">

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

memsql> SHOW GLOBAL VARIABLES LIKE 'saml_message_recipient';
+------------------------+----------------------+
| 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:

<saml:Assertion xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xs="http://www.w3.org/2001/XMLSchema" ID="_d71a3a8e9fcc45c9e9d248ef7049393fc8f04e5f75" Version="2.0" IssueInstant="2014-07-17T01:01:48Z">
  ...
  <saml:Conditions NotBefore="2014-07-17T01:01:18Z" NotOnOrAfter="2016-01-18T06:21:48Z">
    <saml:AudienceRestriction>
      <saml:Audience>https://my.example.com/service/</saml:Audience>
      <saml:Audience>https://my.otherexample.com/service/</saml:Audience>
    </saml:AudienceRestriction>
  </saml:Conditions>
  ...
</saml:Assertion>

The assertion above is restricted to the two audiences specified in the <saml:Audience> 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/

memsql> SHOW GLOBAL VARIABLES LIKE 'saml_assertion_audience';
+-------------------------+---------------------------------+
| Variable_name           | Value                           |
+-------------------------+---------------------------------+
| saml_assertion_audience | https://my.example.com/service/ |
+-------------------------+---------------------------------+
1 row in set (0.00 sec)

Was this Article Helpful?

Need help or have suggestions? Go to SingleStore Forums

Configuring SAML Global Variables min read

Minimum Configurations

NameID Configuration

Attribute Name Configuration

Maximum Configuration and Other Options

Signing Variables

Encryption Variables

saml_user_name_attribute

Examples

saml_use_NameID

Examples

saml_require_encryption

Examples

saml_require_signature_validation

Examples

saml_x509_certificate

Examples

saml_private_decryption_key

Examples

saml_message_recipient

Examples

saml_assertion_audience

Examples

Sorry About That