Authenticate via Browser-based SSO using JWTs

Note

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 github.com/memsql/singlestore-auth-helper@latest

Note

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

Note

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:

credentialType=BROWSER_SSO

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.

Note

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.

Note

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.

Note

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

Notice

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.

CREATE USER 'email@example.com'@'%' IDENTIFIED WITH authentication_jwt REQUIRE SSL;

where:

  • email@example.com 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