diff --git a/modules/ROOT/nav.adoc b/modules/ROOT/nav.adoc index 142049a66..038cede58 100644 --- a/modules/ROOT/nav.adoc +++ b/modules/ROOT/nav.adoc @@ -347,6 +347,7 @@ **** xref:sql:get-started/oltp-vs-olap.adoc[] **** xref:sql:get-started/redpanda-sql-vs-postgresql.adoc[] ** xref:sql:connect-to-sql/index.adoc[Connect to Redpanda SQL] +*** xref:sql:connect-to-sql/authenticate.adoc[Authenticate] *** xref:sql:connect-to-sql/language-clients/psycopg2.adoc[] *** xref:sql:connect-to-sql/language-clients/java-jdbc.adoc[] *** xref:sql:connect-to-sql/language-clients/php-pdo.adoc[] @@ -356,6 +357,7 @@ *** xref:sql:query-data/query-streaming-topics.adoc[Query Streaming Topics] *** xref:sql:query-data/query-iceberg-topics.adoc[Query Iceberg Topics] ** xref:sql:manage/index.adoc[Manage Redpanda SQL] +*** xref:sql:manage/manage-access.adoc[Manage access] ** xref:sql:troubleshoot/index.adoc[Troubleshoot] *** xref:sql:troubleshoot/degraded-state-handling.adoc[] *** xref:sql:troubleshoot/memory-management.adoc[Memory Management] @@ -541,12 +543,17 @@ **** xref:reference:sql/sql-statements/alter-redpanda-catalog.adoc[] **** xref:reference:sql/sql-statements/alter-storage.adoc[] **** xref:reference:sql/sql-statements/alter-table.adoc[] +**** xref:reference:sql/sql-statements/alter-user.adoc[] **** xref:reference:sql/sql-statements/create-redpanda-catalog.adoc[] **** xref:reference:sql/sql-statements/create-storage.adoc[] **** xref:reference:sql/sql-statements/create-table.adoc[] +**** xref:reference:sql/sql-statements/create-user.adoc[] **** xref:reference:sql/sql-statements/drop-redpanda-catalog.adoc[] **** xref:reference:sql/sql-statements/drop-storage.adoc[] **** xref:reference:sql/sql-statements/drop-table.adoc[] +**** xref:reference:sql/sql-statements/drop-user.adoc[] +**** xref:reference:sql/sql-statements/grant.adoc[] +**** xref:reference:sql/sql-statements/revoke.adoc[] **** xref:reference:sql/sql-statements/select.adoc[] **** xref:reference:sql/sql-statements/copy-to.adoc[] **** xref:reference:sql/sql-statements/describe.adoc[] diff --git a/modules/reference/pages/sql/sql-statements/alter-user.adoc b/modules/reference/pages/sql/sql-statements/alter-user.adoc new file mode 100644 index 000000000..e5e52ec79 --- /dev/null +++ b/modules/reference/pages/sql/sql-statements/alter-user.adoc @@ -0,0 +1,51 @@ += ALTER USER +:description: The ALTER USER statement changes the password or superuser status of an existing user. +:page-topic-type: reference + +The `ALTER USER` statement changes the password or superuser status of an existing user. `ALTER ROLE` is a synonym for `ALTER USER`, provided for PostgreSQL compatibility. + +A superuser can alter any user. A non-superuser can alter their own user (for example, to change their own password) but cannot change their own superuser status. + +== Syntax + +[source,sql] +---- +ALTER { USER | ROLE } user_name [WITH] + [ PASSWORD 'password' ] + [ SUPERUSER | NOSUPERUSER ]; +---- + +* `user_name`: Name of the existing user to alter. Use the reserved keyword `CURRENT_USER` or `CURRENT_ROLE` to alter the user running the statement. +* `PASSWORD 'password'`: Optional. The new password. Must be a non-empty string literal if specified. +* `SUPERUSER`: Optional. Promotes the user to superuser. Requires superuser privileges on the current session. +* `NOSUPERUSER`: Optional. Removes superuser status from the user. The protected system superuser cannot be demoted. +* `WITH`: Optional. Has no effect; provided for PostgreSQL compatibility. + +== Examples + +Change the password for an existing user: + +[source,sql] +---- +ALTER USER "alice@example.com" WITH PASSWORD 'new_secret'; +---- + +Change your own password (as the current user): + +[source,sql] +---- +ALTER USER CURRENT_USER WITH PASSWORD 'new_secret'; +---- + +Promote a regular user to superuser: + +[source,sql] +---- +ALTER USER "alice@example.com" SUPERUSER; +---- + +== Suggested reading + +* xref:reference:sql/sql-statements/create-user.adoc[CREATE USER] +* xref:reference:sql/sql-statements/drop-user.adoc[DROP USER] +* xref:sql:manage/manage-access.adoc[Manage access to Redpanda SQL] diff --git a/modules/reference/pages/sql/sql-statements/create-user.adoc b/modules/reference/pages/sql/sql-statements/create-user.adoc new file mode 100644 index 000000000..1f9f55e11 --- /dev/null +++ b/modules/reference/pages/sql/sql-statements/create-user.adoc @@ -0,0 +1,48 @@ += CREATE USER +:description: The CREATE USER statement creates a new user in Redpanda SQL with a required password. Only a superuser can create users. +:page-topic-type: reference + +The `CREATE USER` statement creates a new user in Redpanda SQL. `CREATE ROLE` is a synonym for `CREATE USER`, provided for PostgreSQL compatibility. Only a superuser can run this statement. + +A password is required when creating a user. + +[NOTE] +==== +Error messages from the SQL engine refer to users as "roles" (for example, `role "alice@example.com" does not exist`). This is consistent with PostgreSQL terminology and refers to the same object that `CREATE USER` produces. +==== + +== Syntax + +[source,sql] +---- +CREATE { USER | ROLE } user_name [WITH] PASSWORD 'password' [SUPERUSER | NOSUPERUSER]; +---- + +* `user_name`: Name of the new user. Cannot be `CURRENT_USER` or `CURRENT_ROLE`. +* `PASSWORD 'password'`: Required. The password must be a non-empty string literal. +* `SUPERUSER`: Optional. Grants superuser privileges to the new user. Superusers bypass authorization checks. +* `NOSUPERUSER`: Optional. Explicitly marks the user as a non-superuser. Default when neither `SUPERUSER` nor `NOSUPERUSER` is specified. +* `WITH`: Optional. Has no effect; provided for PostgreSQL compatibility. + +== Examples + +Create a regular user with a password: + +[source,sql] +---- +CREATE USER "alice@example.com" WITH PASSWORD 'secret123'; +---- + +Create a superuser: + +[source,sql] +---- +CREATE USER "admin@example.com" WITH PASSWORD 'admin_secret' SUPERUSER; +---- + +== Suggested reading + +* xref:reference:sql/sql-statements/alter-user.adoc[ALTER USER] +* xref:reference:sql/sql-statements/drop-user.adoc[DROP USER] +* xref:reference:sql/sql-statements/grant.adoc[GRANT] +* xref:sql:manage/manage-access.adoc[Manage access to Redpanda SQL] diff --git a/modules/reference/pages/sql/sql-statements/drop-user.adoc b/modules/reference/pages/sql/sql-statements/drop-user.adoc new file mode 100644 index 000000000..7c1c1c4f9 --- /dev/null +++ b/modules/reference/pages/sql/sql-statements/drop-user.adoc @@ -0,0 +1,48 @@ += DROP USER +:description: The DROP USER statement removes an existing user. The user cannot own objects or hold grants when dropped. +:page-topic-type: reference + +The `DROP USER` statement removes an existing user from Redpanda SQL. `DROP ROLE` is a synonym for `DROP USER`, provided for PostgreSQL compatibility. Only a superuser can run this statement. + +A user cannot be dropped while they own objects (for example, a catalog or table created by that user) or hold privilege grants. Reassign or drop the owned objects and revoke the grants first, then drop the user. + +== Syntax + +[source,sql] +---- +DROP { USER | ROLE } [IF EXISTS] user_name; +---- + +* `user_name`: Name of the user to drop. Cannot be `CURRENT_USER` or `CURRENT_ROLE`. The user running the statement cannot drop themselves, and the protected system superuser cannot be dropped. +* `IF EXISTS`: Optional. Prevents an error if the user does not exist. + +== Examples + +Drop an existing user: + +[source,sql] +---- +DROP USER "alice@example.com"; +---- + +Drop a user only if it exists: + +[source,sql] +---- +DROP USER IF EXISTS "legacy-account@example.com"; +---- + +If the user has dependent grants or owned objects, the statement fails with an error listing the objects. Revoke the grants and reassign or drop owned objects first: + +[source,sql] +---- +REVOKE SELECT ON EXTERNAL SOURCE default_redpanda_catalog FROM "alice@example.com"; +DROP USER "alice@example.com"; +---- + +== Suggested reading + +* xref:reference:sql/sql-statements/create-user.adoc[CREATE USER] +* xref:reference:sql/sql-statements/alter-user.adoc[ALTER USER] +* xref:reference:sql/sql-statements/revoke.adoc[REVOKE] +* xref:sql:manage/manage-access.adoc[Manage access to Redpanda SQL] diff --git a/modules/reference/pages/sql/sql-statements/grant.adoc b/modules/reference/pages/sql/sql-statements/grant.adoc new file mode 100644 index 000000000..f39fd5e7b --- /dev/null +++ b/modules/reference/pages/sql/sql-statements/grant.adoc @@ -0,0 +1,118 @@ += GRANT +:description: The GRANT statement assigns privileges on a database object to a role. Only a superuser can grant privileges. +:page-topic-type: reference + +The `GRANT` statement assigns privileges on a database object to a role. Only a superuser can grant privileges. + +Redpanda SQL is deny-all by default. A role has no access to any object until a superuser grants it. For the broader access model, see xref:sql:manage/manage-access.adoc[]. + +== Privilege levels + +A privilege is associated with a level. Each level supports a specific set of privilege types: + +[cols="<25%,<40%,<35%",options="header"] +|=== +|Level |Object |Privilege types + +|Database +|The Redpanda SQL database +|`CONNECT` + +|Schema +|A schema in the database +|`USAGE`, `CREATE` + +|Table +|A native SQL table +|`SELECT`, `INSERT`, `UPDATE`, `DELETE` + +|External source +|A Redpanda catalog or SQL storage definition +|`SELECT` +|=== + +`ALL PRIVILEGES` resolves to the full set of privilege types at the given level. For external sources, `ALL PRIVILEGES` resolves to `SELECT` only. + +== Syntax + +=== Grant on a table + +[source,sql] +---- +GRANT { privilege [, ...] | ALL [PRIVILEGES] } ON TABLE table_name TO role_name; +---- + +=== Grant on an external source + +A Redpanda catalog (the object created by `CREATE REDPANDA CATALOG`) and a SQL storage definition (the object created by `CREATE STORAGE`) are both external sources. + +The catalog-level form grants the privilege on every relation reachable through the source. The pattern form scopes the grant to relations whose name matches the pattern. + +[source,sql] +---- +GRANT { SELECT | ALL [PRIVILEGES] } ON EXTERNAL SOURCE source_name TO role_name; +GRANT { SELECT | ALL [PRIVILEGES] } ON EXTERNAL SOURCE source_name => 'pattern' TO role_name; +---- + +* `pattern`: A string literal that matches a relation name. The wildcard `*` is only allowed at the end of the pattern (for example, `'orders_*'`). + +=== Grant on a schema + +[source,sql] +---- +GRANT { privilege [, ...] | ALL [PRIVILEGES] } ON SCHEMA schema_name TO role_name; +---- + +Schema-level privileges affect visibility and creation rights for objects in the schema. Without `USAGE` on a schema, a user cannot see catalogs in that schema or reference objects in it by name. + +=== Grant on the database + +Redpanda SQL exposes a single database, `oxla`. + +[source,sql] +---- +GRANT CONNECT ON DATABASE oxla TO role_name; +---- + +== Examples + +Grant `SELECT` on a topic surfaced through a Redpanda catalog: + +[source,sql] +---- +GRANT SELECT ON EXTERNAL SOURCE default_redpanda_catalog => 'orders' TO "alice@example.com"; +---- + +Grant `SELECT` on every topic in a Redpanda catalog: + +[source,sql] +---- +GRANT SELECT ON EXTERNAL SOURCE default_redpanda_catalog TO "alice@example.com"; +---- + +Grant `SELECT` on every topic whose name starts with `orders_`: + +[source,sql] +---- +GRANT SELECT ON EXTERNAL SOURCE default_redpanda_catalog => 'orders_*' TO "alice@example.com"; +---- + +Grant `USAGE` on a schema so the user can see the catalogs and storage in it: + +[source,sql] +---- +GRANT USAGE ON SCHEMA public TO "alice@example.com"; +---- + +Grant `SELECT` and `INSERT` on a native SQL table: + +[source,sql] +---- +GRANT SELECT, INSERT ON TABLE summary_data TO "alice@example.com"; +---- + +== Suggested reading + +* xref:reference:sql/sql-statements/revoke.adoc[REVOKE] +* xref:reference:sql/sql-statements/create-user.adoc[CREATE USER] +* xref:sql:manage/manage-access.adoc[Manage access to Redpanda SQL] diff --git a/modules/reference/pages/sql/sql-statements/revoke.adoc b/modules/reference/pages/sql/sql-statements/revoke.adoc new file mode 100644 index 000000000..a4d06c2b6 --- /dev/null +++ b/modules/reference/pages/sql/sql-statements/revoke.adoc @@ -0,0 +1,84 @@ += REVOKE +:description: The REVOKE statement removes privileges that were previously granted to a role. Only a superuser can revoke privileges. +:page-topic-type: reference + +The `REVOKE` statement removes privileges that were previously granted to a role with xref:reference:sql/sql-statements/grant.adoc[GRANT]. Only a superuser can revoke privileges. + +For the privilege levels and types that apply to each object, see xref:reference:sql/sql-statements/grant.adoc#privilege-levels[Privilege levels]. + +== Syntax + +=== Revoke on a table + +[source,sql] +---- +REVOKE { privilege [, ...] | ALL [PRIVILEGES] } ON TABLE table_name FROM role_name; +---- + +=== Revoke on an external source + +[source,sql] +---- +REVOKE { SELECT | ALL [PRIVILEGES] } ON EXTERNAL SOURCE source_name FROM role_name; +REVOKE { SELECT | ALL [PRIVILEGES] } ON EXTERNAL SOURCE source_name => 'pattern' FROM role_name; +---- + +* `pattern`: A string literal that matches a relation name. The wildcard `*` is only allowed at the end of the pattern. + +=== Revoke on a schema + +[source,sql] +---- +REVOKE { privilege [, ...] | ALL [PRIVILEGES] } ON SCHEMA schema_name FROM role_name; +---- + +=== Revoke on the database + +Redpanda SQL exposes a single database, `oxla`. + +[source,sql] +---- +REVOKE CONNECT ON DATABASE oxla FROM role_name; +---- + +== Behavior + +* *Pattern that matches no existing grant.* When revoking on an external source with a non-wildcard pattern, the statement errors if the pattern does not match any existing grant for the role. List current grants with `SELECT * FROM information_schema.role_external_relation_grants`. +* *Catalog-level revoke is idempotent.* The catalog-level form (no pattern) is idempotent and silently no-ops if no grants exist for the role on that source. Cleanup scripts can safely run it. +* *Wildcard grants cannot be partially revoked.* If a role has a wildcard grant (for example `'*'` or `'orders_*'`), you cannot punch a hole in it. Revoke the wildcard grant in full, then re-grant the narrower pattern you want. + +== Examples + +Revoke `SELECT` on a single topic: + +[source,sql] +---- +REVOKE SELECT ON EXTERNAL SOURCE default_redpanda_catalog => 'orders' FROM "alice@example.com"; +---- + +Revoke a wildcard grant: + +[source,sql] +---- +REVOKE SELECT ON EXTERNAL SOURCE default_redpanda_catalog => 'orders_*' FROM "alice@example.com"; +---- + +Revoke all grants on a catalog: + +[source,sql] +---- +REVOKE SELECT ON EXTERNAL SOURCE default_redpanda_catalog FROM "alice@example.com"; +---- + +Revoke `USAGE` on a schema: + +[source,sql] +---- +REVOKE USAGE ON SCHEMA public FROM "alice@example.com"; +---- + +== Suggested reading + +* xref:reference:sql/sql-statements/grant.adoc[GRANT] +* xref:reference:sql/sql-statements/drop-user.adoc[DROP USER] +* xref:sql:manage/manage-access.adoc[Manage access to Redpanda SQL] diff --git a/modules/sql/pages/connect-to-sql/authenticate.adoc b/modules/sql/pages/connect-to-sql/authenticate.adoc new file mode 100644 index 000000000..ad8416c75 --- /dev/null +++ b/modules/sql/pages/connect-to-sql/authenticate.adoc @@ -0,0 +1,162 @@ += Authenticate to Redpanda SQL +:description: Authenticate to Redpanda SQL with an OIDC bearer token, OIDC client credentials, or a SCRAM username and password for legacy clients. +:page-topic-type: how-to +:personas: app_developer, data_engineer, platform_admin +:learning-objective-1: Connect to Redpanda SQL with an OIDC bearer token or client credentials +:learning-objective-2: Set up a SCRAM username and password so a legacy client can connect to Redpanda SQL + +Authenticate to Redpanda SQL with an glossterm: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 xref:sql:manage/manage-access.adoc[]. + +After completing these steps, you will be able to: + +* [ ] {learning-objective-1} +* [ ] {learning-objective-2} + +== Prerequisites + +* A Redpanda BYOC cluster on AWS with Redpanda SQL enabled. See xref:sql:get-started/deploy-sql-cluster.adoc[Enable Redpanda SQL]. +* https://www.postgresql.org/download/[`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 xref:security:authorization/rbac/rbac_dp.adoc[Configure RBAC in the Data Plane]. + +== Authentication modes + +Redpanda SQL supports three authentication modes, selected by the connection-string `options` parameter: + +[cols="<25%,<30%,<45%",options="header"] +|=== +|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 <>. +|=== + +Redpanda SQL treats a glossterm: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`. + +For OIDC tokens, the token must include the standard claims (`sub`, `aud`, `iss`, `exp`) and must use one of these signing algorithms: `RS256`, `RS384`, `RS512`, or `ES256`. Redpanda SQL rejects tokens signed with `alg: none`. + +// TODO: At Cloud GA the IdP is Auth0 (single-IdP architecture per RFC + SME +// comments). External IdP federation and customer-owned IdPs are not supported. +// Once federation lands, document the validated external IdPs here. + +== 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 xref:sql:get-started/sql-quickstart.adoc[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 +[source,bash] +---- +PGPASSWORD="$BEARER_TOKEN" \ + psql "host= port= dbname=oxla user=ignored options='auth_method=bearer' sslmode=require" +---- + +.Python (psycopg2) +[source,python] +---- +import os +import psycopg2 + +conn = psycopg2.connect( + host="", + 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 xref:sql:connect-to-sql/index.adoc[Connect to Redpanda SQL]. + +// TODO: OXLA-9382 (concurrent first-time login via connection pool produces +// duplicate role entries in the distributed catalog) is marked Done in Jira +// but has no fixVersions set. Confirm with SME the fix is in the GA 2026-05-22 +// build before publishing this note. If confirmed in GA, delete this comment. +// If NOT confirmed, restore the user-facing NOTE below: +// +// [NOTE] +// ==== +// *Concurrent first-time logins.* First-time logins through a connection pool +// can occasionally produce duplicate role entries in the distributed catalog, +// after which DDL operations against the role fail. Track +// https://redpandadata.atlassian.net/browse/OXLA-9382[OXLA-9382^]. As a +// workaround, have each user log in once with a single connection before +// using a connection pool against that account. +// ==== + +== 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. + +[source,bash] +---- +PGPASSWORD="$CLIENT_SECRET" \ + psql "host= port= dbname=oxla user= options='auth_method=client_secret' sslmode=require" +---- + +// TODO: Reconcile token-endpoint timeout. The RFC says 5s +// ("Token Endpoint Client — HTTP POST for client credentials exchange. 5s timeout.") +// but oxla/src/net/http/http_client.h defaults to 10s. Confirm with SME which is +// authoritative for GA, then document the correct value here. + +== 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. + +. 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 xref:security:authorization/rbac/rbac_dp.adoc[Configure RBAC in the Data Plane]. + +. As a *SQL: Manage* user, set a known password on the provisioned account. The username is the email on the service account: ++ +[source,sql] +---- +ALTER USER "service-account@example.com" WITH PASSWORD 'shared_secret'; +---- + +. Configure the legacy client to connect with that username and password. Do not set the `auth_method` option: ++ +[source,bash] +---- +PGPASSWORD='shared_secret' \ + psql "host= 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. + +Two distinct cluster settings affect TLS: + +* The cluster's SSL mode controls TLS on the `psql` connection to Redpanda SQL itself. To reject connections that aren't using TLS, configure the cluster to reject all non-TLS connections. ++ +// TODO: Confirm the correct cross-link for the cluster SSL mode setting in Redpanda Cloud. The previous reference to `security:authorization/gbac/gbac_dp.adoc` was misdirected (GBAC covers group-claim mapping, not SSL mode). +* `oidc.require_tls` (default `true`) controls whether Redpanda SQL uses HTTPS when contacting Redpanda Cloud's identity provider: the OIDC discovery document URL, the JWKS endpoint, and the token endpoint for the client-credentials flow. This setting does not gate TLS on the client's `psql` connection. + +== 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 + +* xref:sql:manage/manage-access.adoc[Manage access]: how the admin grants per-user access after authentication. +* xref:sql:connect-to-sql/index.adoc[Connect to Redpanda SQL]: language-client connection guides. diff --git a/modules/sql/pages/manage/manage-access.adoc b/modules/sql/pages/manage/manage-access.adoc new file mode 100644 index 000000000..98baa79ff --- /dev/null +++ b/modules/sql/pages/manage/manage-access.adoc @@ -0,0 +1,110 @@ += Manage Access to Redpanda SQL +:description: Authentication and authorization model for Redpanda SQL: OIDC authentication and admin GRANT for per-user access to topics and catalogs. +:page-topic-type: concept +:personas: platform_admin +:learning-objective-1: Distinguish between the SQL: Manage and SQL: Access data-plane RBAC permissions +:learning-objective-2: Choose the right privilege level when granting access to a Redpanda topic, catalog, or schema +:learning-objective-3: Recognize how grants on Redpanda catalogs differ from grants on native SQL tables + +Redpanda SQL separates authentication and authorization: + +* *Authentication*: Redpanda Cloud validates the user with OIDC (default) or SCRAM password (for legacy clients), against the engine's preconfigured OIDC settings. For the client-side guide, see xref:sql:connect-to-sql/authenticate.adoc[]. +* *Authorization*: Two roles control what a user can do once they authenticate: +** *SQL: Manage*: SQL engine superuser. Can read every topic, create catalogs and tables, and grant access to other users. +** *SQL: Access*: Regular user. Can connect to the SQL engine but cannot read any catalog or table they don't own. By default, a *SQL: Access* user owns nothing; a *SQL: Manage* user grants `SELECT` on specific resources to give them access. + +After reading this page, you will be able to: + +* [ ] {learning-objective-1} +* [ ] {learning-objective-2} +* [ ] {learning-objective-3} + +== Authentication + +Redpanda Cloud preconfigures the SQL engine's OIDC settings when SQL is enabled on the cluster, so you do not need to configure an external identity provider for the SQL engine. The engine validates bearer tokens minted by Redpanda Cloud, regardless of whether you sign in to Redpanda Cloud with email and password or SSO. + +When a user is 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. No manual `CREATE USER` is required. To assign roles, go to *Organization IAM > Roles*; SQL permissions are under the *Data Plane* tab when you create or edit a role. See xref:security:authorization/rbac/rbac_dp.adoc[]. + +// TODO: Confirm validated IdP coverage with engineering (qa-questions.md #16). +// Add an "IdPs validated for Redpanda SQL" section listing the providers +// engineering has explicitly tested (Keycloak is confirmed; Okta, Microsoft +// Entra ID, Auth0, and Google have not yet been confirmed for SQL). + +== How queries reach the underlying topics + +All Redpanda SQL queries connect to the underlying Redpanda cluster as a single internal SASL credential associated with the default Redpanda catalog (`default_redpanda_catalog`), regardless of which SQL user issued the query. The internal credential is provisioned automatically when Redpanda SQL is enabled and is not a user-facing role. + +This means: + +* Kafka ACLs do not gate query-time access. Every query reaches the topics under the internal SASL credential. +* The boundary that prevents users from reading data they should not see is enforced inside Redpanda SQL by `GRANT` and `REVOKE` against the SQL-level roles. + +== Authorization + +A *SQL: Manage* user uses standard SQL xref:reference:sql/sql-statements/grant.adoc[GRANT] statements to give a *SQL: Access* user access to specific topics, catalogs, or schemas. The user identifier is the email on the user's Redpanda Cloud account. + +. Assign the user a role with the *SQL: Access* permission (see <>). + +. As a *SQL: Manage* user, grant `SELECT` on a topic surfaced through a Redpanda catalog: ++ +[source,sql] +---- +GRANT SELECT ON EXTERNAL SOURCE default_redpanda_catalog => 'orders' TO "alice@example.com"; +---- ++ +Or grant `SELECT` on multiple topics that match a wildcard pattern. The wildcard `*` is only allowed at the end of the pattern: ++ +[source,sql] +---- +GRANT SELECT ON EXTERNAL SOURCE default_redpanda_catalog => 'orders_*' TO "alice@example.com"; +---- ++ +To grant `SELECT` on every topic in a catalog, omit the relation pattern: ++ +[source,sql] +---- +GRANT SELECT ON EXTERNAL SOURCE default_redpanda_catalog TO "alice@example.com"; +---- + +. To remove access, revoke the privilege: ++ +[source,sql] +---- +REVOKE SELECT ON EXTERNAL SOURCE default_redpanda_catalog => 'orders' FROM "alice@example.com"; +---- + +=== Grant behavior for Redpanda catalogs + +A few details affect how grants on Redpanda catalogs behave: + +* Privilege type: `SELECT` is the only privilege type that has effect on a Redpanda catalog. `GRANT ALL PRIVILEGES` on a catalog resolves to `SELECT` only. +* `REVOKE` on a non-matching pattern: `REVOKE SELECT ... \=> 'pattern'` errors if the pattern matches no existing grant for the role. The catalog-level form (no pattern) is idempotent and silently no-ops if no grants exist, so cleanup scripts can safely run it. +* Inspecting current grants: To see which roles have grants on which catalogs and relations, query `information_schema.role_external_relation_grants`. Catalog-level grants also appear as rows in `information_schema.role_table_grants`, where `table_name` is the catalog name. + +=== Schema-level privileges for Redpanda catalogs and SQL storage + +Redpanda catalogs and SQL storage definitions live in a schema (`public` by default). To work with them, a user needs schema-level privileges in addition to any per-relation grants: + +* `USAGE` on the schema: required to see catalogs in `system.catalogs` and `SHOW CATALOGS`, and to reference any object in the schema by name. Without `USAGE`, the catalog is hidden from the user. +* `CREATE` on the schema: required for a non-superuser to run `CREATE REDPANDA CATALOG` or `CREATE STORAGE` in that schema. + +Grant schema-level privileges with the `ON SCHEMA` form: + +[source,sql] +---- +GRANT USAGE ON SCHEMA public TO "alice@example.com"; +GRANT CREATE ON SCHEMA public TO "alice@example.com"; +---- + +== Next steps + +* xref:sql:connect-to-sql/authenticate.adoc[Authenticate to Redpanda SQL]: how a user connects with a bearer token, client credentials, or a SCRAM password. +* xref:security:authorization/rbac/rbac_dp.adoc[Configure RBAC in the Data Plane]: assign the data-plane RBAC roles that gate SQL engine access. + +== Suggested reading + +* xref:reference:sql/sql-statements/grant.adoc[GRANT] +* xref:reference:sql/sql-statements/revoke.adoc[REVOKE] +* xref:reference:sql/sql-statements/create-user.adoc[CREATE USER] +* xref:reference:sql/sql-statements/alter-user.adoc[ALTER USER] +* xref:reference:sql/sql-statements/drop-user.adoc[DROP USER]