Authenticate via JWT

About JWT Users

For the purposes of this document, a "JWT user" is a user that can authenticate with a JWT when connecting to a SingleStore Helios workspace. Refer to Create a JWT User for more information.

For authenticating to SingleStore Helios with a JWT:

• When using browser-based SSO in conjunction with the singlestore-auth-helper or SingleStore driver, the JWT user is identified by the user’s Cloud Portal email address, where the sub field of the JWT will contain the user’s email address as the username. Any user configured with a corresponding JWT user in the database can use this method to authenticate. The default expiration time for these tokens is sixteen (16) hours. Workspaces accept these JWTs that are signed by the Cloud Portal.

• When using the Cloud Portal SQL Editor against a running workspace, a JWT user is identified by a UUID. Only Cloud Portal users that are members of the organization which owns the workspace may access the database using this method. Workspaces accept these JWTs that are signed by the Cloud Portal.

• Customers can create and sign JWTs. For a customer-created JWT to be accepted by SingleStore Helios, the workspace must be configured to accept the public key corresponding to the private key used to sign the JWT.

• Workspaces are configured to accept JWTs using JSON Web Key Sets (JWKS). With JWKS, JWTs are matched to JSON Web Keys (JWKs) to validate the JWT. The JWK and JWT together specify the database username to use.

Validate JWTs with JWKS

You can use JSON Web Key Sets (JWKS) to validate the signature of a signed JWT. JWKS are a set of keys which contain public keys that can be used to authenticate any JWT. JWKS is a standard to download a batch of JWKs from a URL.

JWTs are matched with JSON Web Keys (JWKs) for validation as follows:

• If the JWT has a kid (Key ID) field, the JWKs with matching kid fields are validated.

• If the JWT has a kid field that doesn’t match any JWK, the authentication request is rejected.

• If the JWT has an iss (Issuer) field (instead of a kid field) that matches the kid in one or more JWKs, the JWKs with matching kid fields are validated.

• If the JWT does not have a kid field and the iss field does not match the kid field in any JWK, then validation is attempted with all the JWKs with a matching alg (Algorithm) field. If the alg field is not specified, the kty (Key Type) field is used instead.

The JWTs signature is validated as follows:

• The JWT’s signature is validated against matching JWKs. If the JWT’s signature matches more than one JWK, validation is attempted against all matching JWKs. If the signature cannot be validated, the authentication request is rejected.

• If the matching JWK includes an aud (Audience) field which does not match the aud field in the JWT, then the authentication request is rejected. The aud field can be a string or an array of strings. If any aud string of the JWT matches any aud string of the JWK, it is considered a match.

  Note: If the jwks_require_audience variable is set (non-empty), the value of this variable must be present in the aud field in the JWT. If the aud field is an array, the value of this variable must be one of the items in the array.

• If the matching JWK does not define an audience (aud), audience checking is skipped. Note that aud is not a standard field in JWK.

The database username is identified as follows:

• When the jwks_username_field variable is set (non-empty), the value of this variable specifies the name of the JWT field that determines the database username. If this variable is set, all the other rules for identifying the database username are overridden/ignored.

• If the matching JWK has a usernameFrom field, the value of this JWK field is used to identify the name of the field in the JWT that determines the database username.

• If the JWK does not have a usernameFrom field, but the JWT has a username field, then the username field determines the database username.

• If the JWK does not have a usernameFrom field and the JWT does not have a username field, then the sub field in the JWT determines the database username.

Configure JWKS

To authenticate using JWKS, build a JWKS configuration file that contains your public keys and serve it from your Web server via static URL.

SingleStore Helios supports the following public key signature algorithms: RS256, RS384, RS512, ES256, ES384, and ES512.

Perform the following tasks to configure JWKS.

1. Configure the certificate authority used to validate the TLS transfer of the JWKS using SSL.

   This step should be performed only if you are using self-signed certificates. If you are not using self-signed certificates then start with step 2.

   1. Upload a public key certificate corresponding to your TLS encryption certificate authority that secures the HTTP SSL transfers.

      Use the following command to obtain the certificate (assuming that your JWKS endpoint is http://some-domain/some/path):

      Shell

      Copy

      openssl s_client --connect some-domain.com:443 --servername some-domain.com --showcerts < /dev/null | sed -ne '/-BEGIN CERTIFICATE-/,/-END CERTIFICATE-/p' > certificate-filename.pem

      1. On the Cloud Portal, select the workspace on which to enable TLS/SSL connection.

      2. Under Security, select the Upload Certificate button to upload your security certificate. Once the certificate is uploaded, it is available to all the nodes in the workspace. This lets you secure outbound connections via TLS/SSL.

   2. Specify the certificate file.

      SQL

      Copy

      SET GLOBAL jwks_ssl_ca_certificate='certificate-filename.pem'

2. Configure the JWKS endpoint.

   SQL

   Copy

   SET GLOBAL jwks_endpoint='https://example.com/.well-known/jwks.json'

   Updating the endpoint configuration triggers a JWKS update and validation. The SET GLOBAL command returns an error if:

   • The GET request fails.

   • There are no valid keys in the updated JWKS.

   A warning is generated if any JWKS is rejected, even if the JWKS has valid keys. Information on rejected keys is available in the audit log.

To disable JWKS updates, set the endpoint to an empty string.

SET GLOBAL jwks_endpoint=''

Optionally, you can set a refresh interval to update the JWKS configuration automatically (specify the value in seconds).

SET GLOBAL jwks_update_interval = 3600

If this value is not set, or set to 0, the JWKS configuration updates only when the SET GLOBAL jwks_endpoint command is run. To manually refresh the JWKS configuration, run the SET GLOBAL jwks_endpoint command with its existing value.

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.

Notes on JWT Authentication

The Cloud Portal creates and deletes users in the workspace to ensure that every user in the organization has corresponding JWT users.

SingleStore Helios creates two JWT users for each user in the organization:

1. User based on a UUID: The SQL Editor and other Cloud Portal functions use a UUID to identify a user.

2. User based on an email address: Browser-based SSO uses the email address to identify a user for access to SingleStore Helios workspaces.

SingleStore Helios will automatically delete any users it created when they are no longer members of the organization. However, if JWT users are manually created then they are not managed by the SingleStore Helios automatic sync process and will not be removed if they are no longer members of the organization.