Authenticate via Browser-based SSO using JWTs

Authenticate via the SingleStore JDBC Driver Using Browser-Based SSO

To authenticate your connection to a SingleStore Helios workspace 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.

To authenticate using browser-based SSO on Linux distributions, you must have the gnome-keyring-daemon and an active Login Password Keyring. If the Login Password Keyring is not configured, refer to Install a Gnome Keyring Manager for Linux Distributions. Windows and MacOS have built-in OS-specific keyrings.

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 SingleStore Helios:

• 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.

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 SingleStore Helios workspace 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 Cloud Portal for the first connection request. After a successful authentication, a JWT is generated and sent from the Cloud Portal to the driver. The driver stores the token in the OS-specific keyring.

To authenticate using browser-based SSO on Linux distributions, you must have the gnome-keyring-daemon and an active Login Password Keyring. If the Login Password Keyring is not configured, refer to Install a Gnome Keyring Manager for Linux Distributions. Windows and MacOS have built-in OS-specific keyrings.

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

By default, each member of a SingleStore Helios organization that belongs to a workspace has a corresponding JWT user created for that workspace. This JWT user has a username based on the user’s Cloud Portal email address.

You can also manually create a JWT user using the following command:

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

where:

• email@example.com is the JWT user’s username. As of SingleStore version 8.1.5, you may also create a JWT user with a username that resembles an email address or a UUID.

• 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.

A JWT user whose username conflicts with an organization user's email address is treated as an organization user. If the organization user is removed from the organization, the JWT user is also removed from the workspace. However, a JWT user that is not an organization user needs to be removed manually.

Related Topics

• Authenticate via JWT

• The SingleStore JDBC Driver

• The SingleStore ODBC Driver