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:
Download Go installer version 1.18.2 or later.
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 usedIDENTIFIED WITH authentication_jwt
sets the user’s authentication method to use a JWTREQUIRE SSL
(mandatory) enforces the use of SSL for the JWT connection