Authenticate via Browser-based SSO using JWTs


SingleStoreDB Cloud supports browser-based single sign-on (SSO) with Google Chrome, Mozilla Firefox, and Microsoft Edge. To use browser-based SSO on macOS, you will need to set your default browser to either Chrome or Firefox.

SingleStoreDB supports authentication via browser-based SSO using JWTs only for the SingleStore JDBC driver and SingleStore ODBC driver.

The SingleStore authentication helper utility, singlestore-auth-helper, enables browser-based passwordless login using the SingleStore and MySQL clients. Install the singlestore-auth-helper utility using Go. Perform the following steps:

  1. Download Go installer version 1.18.2 or later.

  2. Run the following command, which is tested with Go v1.18.2:

    go install


The singlestore-auth-helper is not required for browser-based SSO authentication with the SingleStore JDBC driver.

The browser-based SSO authentication workflow opens the default browser to the SingleStoreDB Cloud login page. After authentication, a JWT is created for the user, which can then be used to access a SingleStoreDB Cloud cluster.

Use JWTs with the SingleStore and MySQL Clients

To use a JWT with the SingleStore client to connect to your SingleStoredDB Cloud cluster, replace the password with the JWT:

singlestore -u $EMAIL_ADDRESS -h $CLUSTER_HOSTNAME -P $CLUSTER_PORT --password=$JWT --ssl=TRUE --enable-cleartext-plugin

Similarly, to use a JWT with the MySQL client to connect to your SingleStoredDB Cloud cluster, replace the password with the JWT.

mysql -u $EMAIL_ADDRESS -h $CLUSTER_HOSTNAME -P $CLUSTER_PORT --password=`singlestore-auth-helper` --ssl=TRUE

Authenticate via the SingleStore JDBC Driver Using Browser-Based SSO


To authenticate your connection to the SingleStore cluster via SingleStore JDBC driver using JWTs, the SingleStore user must connect via SSL and use JWT for authentication. See Create a JWT User for more information.

To authenticate your connection to a SingleStoreDB Cloud cluster with browser-based single sign-on (SSO), add the following parameter to the connection string:


Using the credentialType=BROWSER_SSO parameter in the connection string tells the driver to use the BrowserCredentialPlugin class for authentication. This plugin queries the OS-native keyring (keystore) for the username and token to use. If this parameter is not specified, the connection uses password-based authentication.


The keyring must have only one username-token pair for a specific user.

If there is no token in the keyring, or the existing token has expired, the driver launches the default browser to initiate the authentication workflow. After a successful authentication, the driver stores the new/updated token in the keyring.

The driver receives the following information from the JWT generated by SingleStoreDB Cloud:

  • expiration: Timestamp for when the token expires (in RFC3339 format).

  • token: Base64-encoded JWT token, which is used as the password.

  • username: Username for the database. By default, it is the user’s authentication email address.

  • email: Email address used in the next invocation of the authentication helper.


Do not specify a user or password in the connection string.

You must set the connect_timeout engine variable to a value that’s long enough to allow a user to successfully complete the browser-based login. For example, a value of 300 specifies that the user has 300 seconds to complete the login process. You can set connect_timeout value via the SET GLOBAL command. For example:

SET GLOBAL connect_timeout = 300;

Authenticate via the SingleStore ODBC Driver Using Browser-Based SSO

To authenticate your connection to the SingleStoreDB cluster via ODBC using browser-based SSO, add the BROWSER_SSO=1 parameter to the connection string.

When the BROWSER_SSO parameter is enabled, the driver launches the default browser to the SingleStore portal for the first connection request. After a successful authentication, a JWT is generated and sent from the portal to the driver. The driver stores the token in the OS-specific keyring.


You may need to install the gnome-keyring-daemon on Linux OS. The OS-specific keyring is inbuilt in Windows and MacOS.

For subsequent logins, the access token is read from the OS-specific keyring. If the token in the keyring expires (or removed/lost), a new login is required.

To skip the interaction with the keyring and login via the browser on each connection attempt, enable the IGNORE_KEYRING_SSO connection parameter.

Create a JWT User


Creating JWT users is only supported in SingleStoreDB Cloud clusters running SingleStoreDB v7.8.5 and later.

By default, each member of a SingleStoreDB Cloud organization that belongs to a cluster has a corresponding JWT user created for that cluster. This JWT user is based on the user’s portal email address as the username.

As a consequence, do not manually create a JWT user with a username that resembles an email address unless email syncing is disabled.

To create a JWT user, run the following SQL command.



  • is the JWT user’s email address which serves as the username; anything but a UUID may be used

  • IDENTIFIED WITH authentication_jwt sets the user’s authentication method to use a JWT

  • REQUIRE SSL (mandatory) enforces the use of SSL for the JWT connection