SAML Authentication


SingleStore supports the SAML 2.0 protocol for third-party user authentication. When a user attempts to authenticate to a SingleStore database, SingleStore can validate a SAML security token’s assertions about that user and optionally grant them access to the database.

Before you can authenticate a user with SAML 2.0, two conditions must be met:

  1. The user must already exist in the SingleStore database and be configured to allow SAML 2.0 authentication instead of the default authentication method.

  2. Each SingleStore aggregator node’s memsql.cnf file must be configured for SAML 2.0 authentication. The configuration process is described in the Configuring SAML Global Variables topic.

This section explains how to enable, configure, and troubleshoot this feature.


Ensure that your system meets the following prerequisites:

  • MySQL Client version 5.5.27 or newer: This version of the MySQL client is required because it includes the Cleartext Client-Side Authentication Plugin. This plugin is necessary because MySQL clients normally hash user credentials before they are sent to the server. However, the internal SAML authentication module operates at the server level, not the client level, and it requires the clear text form of user credentials. Therefore, all user accounts that require SAML authentication must have their credentials passed to the server in clear text.

When passing any credentials in clear text, you should always use some form of transport layer security (TLS). Otherwise, an attacker can see the user’s credentials by inspecting unencrypted network traffic.

  • MemSQL version 5.8.0 or newer: This version of SingleStore is required because it’s the first version that provides the option to authenticate with SAML 2.0 security tokens.

  • SAML 2.0 Requirements:

  • Base64-encoded security tokens: When a user is authenticated using SAML 2.0, the security token sent to the database must be Base64 encoded. If a token is not Base64 encoded, the database will return an error.

  • Decoded security token cannot be greater than 250KB in size: A fully decoded Base64 security token must not exceed 250KB. The Base64-encoded security token itself may exceed 250KB, but ensure that its decoded size does not exceed 250KB.

Terms and Concepts

This section uses a limited set of security terms and concepts with the following definitions:

SAML Assertion: A package of information issued by an identity provider that contains zero or more statements about a subject.

Identity Provider: An authority that issues and validates statements about a subject.

Public Signing Key: The public portion of a public/private key pair that is used by third parties to validate a signed security token issued by an identity provider.

Private Encryption Key: The private portion of a public/private key pair that is used to decrypt a SAML assertion.

Security Token: For this document, a security token is equivalent to a SAML Response, and both terms are used interchangeably.

In this section

Last modified: June 22, 2022

Was this article helpful?