SQL: OIDC and access management

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[]

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]

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]

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]

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]

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]