Authenticate via JWT
A JSON Web Token (JWT) is an open, industry standard (RFC 7519) that defines a compact and self-contained method for securely transmitting information between parties as a JSON object, which can be verified and trusted as it is digitally signed.
JWTs are useful for both authorization (the most common scenario for using a JWTs) and information exchange (where information can be securely transmitted between parties). SingleStoreDB supports using JWTs for authentication. Refer to JWT.io for more information.
Use JWTs with the SingleStore and MySQL Clients
To use a JWT with the SingleStore client, 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, replace the password with the JWT.
mysql -u $EMAIL_ADDRESS -h $CLUSTER_HOSTNAME -P $CLUSTER_PORT --password=$JWT --ssl=TRUE
Note
SingleStoreDB also supports JWT-based authentication with the SingleStore JDBC driver, the SingleStore ODBC driver, and client libraries that support cleartext (provided cleartext is enabled).
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 SingleStoreDB cluster.
For authenticating to SingleStoreDB with a JWT:
Clusters are configured to accept JWTs using JSON Web Key Sets (JWKS) or with the static
jwt-config
file. 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. With the staticjwt-config
file, JWTs are matched to keys based on thealg
in the JWT. Both JWKS andjwt-config
can be used at the same time. When they’re used together, JWTs are matched against JWKS first and will only be matched against thejwt-config
file if there is no match to any JWK.
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 matchingkid
fields are validated.If the JWT has a
kid
field that doesn’t match any JWK orjwt_config
key, the authentication request is rejected. See Validate JWTs with thejwt-config
for more information.If the JWT has an
iss
(Issuer) field (instead of akid
field) that matches thekid
in one or more JWKs, the JWKs with matchingkid
fields are validated.If the JWT does not have a
kid
field and theiss
field does not match thekid
field in any JWK, then validation is attempted with all the JWKs with a matchingalg
(Algorithm) field. If thealg
field is not specified, thekty
(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 theaud
field in the JWT, then the authentication request is rejected. Theaud
field can be a string or an array of strings. If anyaud
string of the JWT matches anyaud
string of the JWK, it is considered a match.If the matching JWK does not define an audience (
aud
), audience checking is skipped. Note thataud
is not a standard field in JWK.
The database username is identified as follows:
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 ausername
field, then theusername
field determines the database username.If the JWK does not have a
usernameFrom
field and the JWT does not have ausername
field, then thesub
field in the JWT determines the database username.
Note
The database username in the JWT, once determined, must exactly match the database username used in the connection attempt. Otherwise, authentication is rejected.
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.
SingleStoreDB supports the following public key signature algorithms: RS256, RS384, RS512, ES256, ES384, and ES512.
Perform the following tasks to configure JWKS.
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.
Install a public key certificate corresponding to your TLS encryption certificate authority that secures the HTTP SSL transfers.
Run the following command to specify the certificate file:
SET GLOBAL jwks_ssl_ca_certificate='/path/to/certificate-filename.pem'
Configure the JWKS endpoint.
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.
JWKS Update Status
To check the status of the most recent JWKS update, use the SHOW STATUS EXTENDED
command. It provides the following information:
JWKS_update_status
: Specifies the status of the update. The status can be one of the following:SUCCESS
,FAILED
, orDISABLED
. TheFAILED
status is followed by the reason behind the failure, in parenthesis.JWKS_update_time
: Specifies the timestamp of JWKS update.SHOW STATUS EXTENDED LIKE 'JWKS_update%'; **** +--------------------+-----------------------------------------------------------------------+ | Variable_name | Value | +--------------------+-----------------------------------------------------------------------+ | JWKS_update_status | FAILED (Failed to connect to localhost port 8082: Connection refused) | | JWKS_update_time | Mon May 2 14:03:08 2022 EST | +--------------------+-----------------------------------------------------------------------+
Validate JWTs with the jwt-config
The jwt-config
file supports only one key per algorithm: RS256, RS384, RS512, HS256, HS384, HS512, ES256, ES384, ES512.
The username_claim
field specifies the field in the JWT that is used to obtain the database username. The database username must match the username in the connection string.
The name of this static configuration file is passed to the engine at startup using the jwt_auth_config_file
variable. Alternatively, it can be set with using the following command:
SET GLOBAL jwt_auth_config_file='filename.json'
The static JWT configuration is only read when the cluster restarts. Here's a sample jwt-config
file:
{ "username_claim": "email", "methods": [ { "algorithms": [ "RS256" ], "secret": "-----BEGIN PUBLIC KEY-----\nMIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAs7t1xiasxa7uSvtMZ8+MtRSiRnxHBEQfLcssxWV7NEvkJTOhAn1KYyM8nMzh4H356aUwCYrOtekjIMmkuBljhic1LQ7kmjdzRc2M/qBXFlD4C9+OxwDtE2tTEHbO/dKuLFSTVGdGVvyLMJIE08hc6ri7xGi1PSYgxH85u7vWB6p43VgHpRH/iJBw6BLBTyfBfgAtbsD8AHm8Ucf8zIPhOVO7gTUqAopbV23eyuzLHFRtXuyDQzkQc8PY0hkHlnlJkDfr0SBgxr1+jPPt7VmrtXIlzNMfbsI5SkLMfoVmXLTqeC8UDA/C8ayWCDh+2a2zuQF0bZSSr1Y9pKDvojTbEQIDAQAB\n-----END PUBLIC KEY-----" }, { "algorithms": [ "ES512" ], "secret": "-----BEGIN PUBLIC KEY-----\nMHYwEAYHKoZIzj0CAQYFK4EEACIDYgAEQinMHQNolwDsI8/o0Ou3joss0m7n5MPR\n59ckzQELU+KDdSNJkTO/DVV6S9SpBoMVJ02hl3SQmZTZwy4cNtDHFVtD1UR6E9J8\naFbvsAi8PvSwaQ4ZP0mxgaEzpXfIH30+\n-----END PUBLIC KEY-----" } ] }
Create a JWT User
Note
Creating JWT users is only supported in SingleStoreDB clusters running SingleStoreDB v7.8.3 and later.
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