# Authenticate via Browser-based SSO using JWTs

> **📝 Note**: SingleStore Helios 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.SingleStore Helios 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](https://github.com/memsql/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](https://go.dev/doc/install) Go installer version 1.18.2 or later.

2. Run the following command, which is tested with Go v1.18.2:
   ```shell
   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 SingleStore Helios login page. After authentication, a JWT is created for the user, which can then be used to access a SingleStore Helios workspace.

## Use JWTs with the SingleStore and MySQL Clients

To use a JWT with the SingleStore client to connect to your SingleStore Helios workspace, replace the password with `singlestore-auth-helper`:

```shell
singlestore -u '*' -h $WORKSPACE_HOSTNAME -P $WORKSPACE_PORT --password=`singlestore-auth-helper` --ssl=TRUE --enable-cleartext-plugin
```

Similarly, to use a JWT with the MySQL client to connect to your SingleStore Helios workspace:

```shell
mysql -u '*' -h $WORKSPACE_HOSTNAME -P $WORKSPACE_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 Helios workspace via SingleStore JDBC driver using JWTs, the SingleStore user must connect via SSL and use JWT for authentication. See [Create a JWT User](https://docs.singlestore.com/#section-idm323307115459026.md) for more information.

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](https://wiki.gnome.org/Projects/GnomeKeyring/RunningDaemon) and an active Login Password Keyring. If the Login Password Keyring is not configured, refer to [Install a Gnome Keyring Manager for Linux Distributions](https://docs.singlestore.com/#section-idm4585460943528033557225814158.md). Windows and MacOS have built-in OS-specific keyrings.

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

* `expiration`: Timestamp for when the token expires (in [RFC3339](https://datatracker.ietf.org/doc/html/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 UUID.
* `userID`: User ID represented as a UUID, used by 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:

```sql
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](https://wiki.gnome.org/Projects/GnomeKeyring/RunningDaemon) and an active Login Password Keyring. If the Login Password Keyring is not configured, refer to [Install a Gnome Keyring Manager for Linux Distributions](https://docs.singlestore.com/#section-idm4585460943528033557225814158.md). 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.

## Install a Gnome Keyring Manager for Linux Distributions

You can store and manage tokens in the Login Password Keyring on Linux distributions using a [Gnome Keyring](https://wiki.archlinux.org/title/GNOME/Keyring) manager, for example, Seahorse. Perform the following steps to install the `seahorse` package:

1. Run the following command on the terminal to install the seahorse package.

   **Debian**
   ```shell
   sudo apt-get install seahorse
   ```
   **Red Hat**
   ```shell
   sudo yum install seahorse
   ```

2. Once the installation is complete, open **Seahorse**.

3. Configure a Password Keyring. Select **+** (Add a new key or item) **> Password Keyring**.

4. Enter a name and password for the new keyring.

5. Set the new keyring as the default.

## Create a JWT User

> **📝 Note**: Creating JWT users is only supported in SingleStore Helios workspaces running SingleStore v7.8.3 and later.

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:

```sql
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.
* The maximum length of a JWT user’s username is 320 characters.
* `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](https://docs.singlestore.com/cloud/security/database-access/authenticate-via-jwt.md)
* [The SingleStore JDBC Driver](https://docs.singlestore.com/cloud/developer-resources/connect-with-application-development-tools/connect-with-java-jdbc/the-singlestore-jdbc-driver.md)
* [The SingleStore ODBC Driver](https://docs.singlestore.com/cloud/developer-resources/connect-with-application-development-tools/connect-with-odbc/the-singlestore-odbc-driver.md)

***

Modified at: November 27, 2025

Source: [/cloud/security/database-access/authenticate-via-browser-based-sso-using-jwts/](https://docs.singlestore.com/cloud/security/database-access/authenticate-via-browser-based-sso-using-jwts/)

(An index of the documentation is available at /llms.txt)