OAuth 2.0 Authentication

This topic describes how to enable OAuth 2.0 authentication in StarRocks.

From v3.5.0 onwards, StarRocks supports authenticating client access using OAuth 2.0. You can enable OAuth 2.0 authentication over HTTP for the Web UI and the JDBC driver.

StarRocks uses the Authorization Code flow which exchanges an authorization code for a token. Generally, the flow includes the following steps:

1. The StarRocks coordinator redirects the user’s browser to the Authorization Server.
2. The user authenticates from the Authorization Server.
3. After the request is approved, the browser is redirected back to the StarRocks FE with an authorization code.
4. the StarRocks coordinator exchanges the authorization code for a token.

This topic describes how to manually create and authenticate users using OAuth 2.0 in StarRocks. For instructions on how to integrate StarRocks with your OAuth 2.0 service using security integration, see Authenticate with Security Integration. For more information on how to authenticate user groups in your OAuth 2.0 service, see Authenticate User Groups.

Prerequisites

If you want to connect to StarRocks from a MySQL client, the MySQL client version must be 9.2 or later. For more information, see MySQL official document.

Create a user with OAuth 2.0

When creating a user, specify the authentication method as OAuth 2.0 by IDENTIFIED WITH authentication_oauth2 AS '{xxx}'. {xxx} is the OAuth 2.0 properties of the user.

Syntax:

CREATE USER <username> IDENTIFIED WITH authentication_oauth2 AS 
'{
  "auth_server_url": "<auth_server_url>",
  "token_server_url": "<token_server_url>",
  "client_id": "<client_id>",
  "client_secret": "<client_secret>",
  "redirect_url": "<redirect_url>",
  "jwks_url": "<jwks_url>",
  "principal_field": "<principal_field>",
  "required_issuer": "<required_issuer>",
  "required_audience": "<required_audience>"
}'

Properties:

• auth_server_url: The authorization URL. The URL to which the users’ browser will be redirected in order to begin the OAuth 2.0 authorization process.
• token_server_url: The URL of the endpoint on the authorization server from which StarRocks obtains the access token.
• client_id: The public identifier of the StarRocks client.
• client_secret: The secret used to authorize StarRocks client with the authorization server.
• redirect_url: The URL to which the users’ browser will be redirected after the OAuth 2.0 authentication succeeds. The authorization code will be sent to this URL. In most cases, it need to be configured as http://<starrocks_fe_url>:<fe_http_port>/api/oauth2.
• jwks_url: The URL to the JSON Web Key Set (JWKS) service or the path to the local file under the conf directory.
• principal_field: The string used to identify the field that indicates the subject (sub) in the JWT. The default value is sub. The value of this field must be identical with the username for logging in to StarRocks.
• required_issuer (Optional): The list of strings used to identify the issuers (iss) in the JWT. The JWT is considered valid only if one of the values in the list match the JWT issuer.
• required_audience (Optional): The list of strings used to identify the audience (aud) in the JWT. The JWT is considered valid only if one of the values in the list match the JWT audience.

Example:

CREATE USER tom IDENTIFIED WITH authentication_oauth2 AS 
'{
  "auth_server_url": "http://localhost:38080/realms/master/protocol/openid-connect/auth",
  "token_server_url": "http://localhost:38080/realms/master/protocol/openid-connect/token",
  "client_id": "12345",
  "client_secret": "LsWyD9vPcM3LHxLZfzJsuoBwWQFBLcoR",
  "redirect_url": "http://localhost:8030/api/oauth2",
  "jwks_url": "http://localhost:38080/realms/master/protocol/openid-connect/certs",
  "principal_field": "preferred_username",
  "required_issuer": "http://localhost:38080/realms/master",
  "required_audience": "12345"
}';

Connect from JDBC client with OAuth 2.0

StarRocks supports the MySQL protocol. You can customize a MySQL plugin to automatically launch the browser login method.

For the example code of the JDBC OAuth2 plugin, see the official document for starrocks-jdbc-oauth2-plugin.

Connect from MySQL client with OAuth 2.0

If you cannot access a browser in your environment (such as using terminal or server), you can also access StarRocks via native MySQL client or JDBC driver:

• When you first connect to StarRocks, a URL will be returned.
• You need to access this URL on a browser and complete the authentication.
• After the authentication, you can then interact with StarRocks.