Cloud

Authenticate to Redpanda SQL

Authenticate to Redpanda SQL with an OpenID Connect (OIDC) bearer token, OIDC client credentials, or a SCRAM password for clients that don’t support OIDC. For how an admin grants users access to topics and catalogs, see Manage Access to Redpanda SQL.

After completing these steps, you will be able to:

  • Connect to Redpanda SQL with an OIDC bearer token or client credentials

  • Set up a SCRAM username and password so a legacy client can connect to Redpanda SQL

Prerequisites

  • A Redpanda BYOC cluster on AWS with Redpanda SQL enabled. See Enable Redpanda SQL.

  • psql or another PostgreSQL-compatible client.

  • A user or service account assigned a role with the SQL: Access or SQL: Manage permission in Redpanda Cloud’s data-plane RBAC. Redpanda Cloud provisions a corresponding user in the SQL engine when the role is assigned. To assign roles, go to Organization IAM > Roles; SQL permissions are under the Data Plane tab when you create or edit a role. See Configure RBAC in the Data Plane.

Authentication modes

Redpanda SQL supports three authentication modes, selected by the connection-string options parameter:

Mode options value When to use

Bearer token

auth_method=bearer

You already hold a JSON Web Token (JWT) issued by Redpanda Cloud (for example, returned by rpk cloud auth token).

Client credentials

auth_method=client_secret

Service-to-service connections (scheduled jobs, BI tools). Redpanda SQL exchanges a Redpanda Cloud service account’s client ID and client secret for a token against Redpanda Cloud’s token endpoint, then validates the returned token.

SCRAM password

(omit options)

Legacy clients that don’t support bearer-token or client-credentials authentication. The username is the Redpanda Cloud account or service account email; the password is set by a SQL: Manage user with ALTER USER. See Connect with SCRAM for legacy clients.

Redpanda SQL treats a bearer token in the password field without auth_method=bearer as a SCRAM password, and the connection fails. To use a bearer token, you must set options='auth_method=bearer'.

Connect with a bearer token

Use bearer-token authentication for human users who hold a JWT issued by Redpanda Cloud. Run rpk cloud auth token to obtain a token you can pass directly; see Quickstart for the end-to-end setup.

Set options='auth_method=bearer' in the connection string and pass the token in the password field. Redpanda SQL ignores the user= field and takes the session identity from the principal claim in the token.

psql
PGPASSWORD=$(rpk cloud auth token) \
  psql "host=<sql-host> port=<sql-port> dbname=oxla user=ignored options='auth_method=bearer' sslmode=require"
Python (psycopg2)
import os
import psycopg2

# Set BEARER_TOKEN before running, for example:
#   export BEARER_TOKEN=$(rpk cloud auth token)
conn = psycopg2.connect(
    host="<sql-host>",
    port=<sql-port>,
    dbname="oxla",
    user="ignored",
    password=os.environ["BEARER_TOKEN"],
    options="auth_method=bearer",
    sslmode="require",
)

cur = conn.cursor()
cur.execute("SELECT current_user")
# current_user is the principal from the token, not "ignored"

For more language-client examples, see Connect to Redpanda SQL.

Connect with client credentials

Use client-credentials authentication for service-to-service connections: scheduled jobs, BI tools, or other automated clients that can’t perform interactive sign-in. Each Redpanda Cloud service account has a client ID and client secret; Redpanda SQL exchanges those credentials for a token against Redpanda Cloud’s token endpoint and validates it.

Set options='auth_method=client_secret', pass the Redpanda Cloud service account’s client ID in user=, and the client secret in the password field. The resolved principal becomes the session identity.

PGPASSWORD="$CLIENT_SECRET" \
  psql "host=<sql-host> port=<sql-port> dbname=oxla user=<client-id> options='auth_method=client_secret' sslmode=require"

Connect with SCRAM for legacy clients

For applications and tools that don’t support OIDC, set a SCRAM username and password directly on the user’s account in Redpanda SQL. The legacy client then connects with that username and password.

This path still relies on Redpanda Cloud to provision the user in the SQL engine. Cloud’s auto-provisioning generates an internal password that is not exposed to you, so a SQL: Manage user must explicitly set a known password with ALTER USER before the legacy client can sign in.

  1. In Redpanda Cloud, create or designate a service account for the legacy client, then assign it the SQL: Access (or SQL: Manage) data-plane RBAC permission. Redpanda Cloud provisions a corresponding user in the SQL engine. See Configure RBAC in the Data Plane.

  2. As a SQL: Manage user, set a known password on the provisioned account. The username is the email on the service account:

    ALTER USER "service-account@example.com" WITH PASSWORD 'shared_secret';

  3. Configure the legacy client to connect with that username and password. Do not set the auth_method option:

    PGPASSWORD='shared_secret' \
  psql "host=<sql-host> port=<sql-port> dbname=oxla user=service-account@example.com sslmode=require"

ALTER USER …​ WITH PASSWORD persists across cluster operations: Redpanda Cloud’s user reconciler only changes a role’s superuser attribute or revokes access, never resets the password. If the service account loses its SQL: Access (or SQL: Manage) role assignment in Redpanda Cloud, however, the reconciler revokes CONNECT and the legacy client can no longer sign in.

Use TLS on connections

Credentials travel in the password field of the PostgreSQL startup message, whether you authenticate with a bearer token, client credentials, or a SCRAM password. To protect them in transit, set sslmode=require on every connection.

On Redpanda Cloud BYOC, the SQL endpoint requires TLS. Connections without TLS are rejected by the server.

Reconnect when a token expires

OIDC bearer tokens are short-lived. Redpanda SQL validates the token once at connection time and does not re-validate it over the lifetime of the session. After the token expires, the database session continues until it closes for some other reason, but new connections must present a fresh token. Run rpk cloud auth token to obtain a new token, then reconnect.

Next steps