SQL: OIDC

modules/ROOT/nav.adoc

@@ -335,17 +335,35 @@
 *** xref:develop:connect/cookbooks/jira.adoc[]
 
 * xref:sql:index.adoc[Redpanda SQL]
-// ** quickstart.adoc
-** xref:sql:get-started/what-is-redpanda-sql.adoc[Overview]
-*** xref:sql:get-started/oltp-vs-olap.adoc[]
-*** xref:sql:get-started/redpanda-sql-vs-postgresql.adoc[]
+// ============================================================================
+// DOC-1993 — Redpanda SQL IA (target BYOC AWS GA 2026-05-22)
+// Most placeholders below do not have linked pages until pages land (except DOC-1856). 
+// Add xrefs per ticket as pages are created.
+// ============================================================================
+// ** xref:sql:get-started/index.adoc[Get Started]
+// *** xref:sql:get-started/sql-quickstart.adoc[Quickstart]                              // DOC-1856 (in review, draft on DOC-1856 branch)
+// *** xref:sql:get-started/deploy-sql-cluster.adoc[Enable Redpanda SQL]                 // DOC-1856
+** Get Started
+*** Quickstart
+*** Enable Redpanda SQL
+*** xref:sql:get-started/what-is-redpanda-sql.adoc[Overview]
+**** 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/language-clients/psycopg2.adoc[]
 *** xref:sql:connect-to-sql/language-clients/java-jdbc.adoc[]
 *** xref:sql:connect-to-sql/language-clients/php-pdo.adoc[]
 *** xref:sql:connect-to-sql/language-clients/dotnet-dapper.adoc[]
+*** xref:sql:connect-to-sql/connect-with-oidc.adoc[Connect with OIDC]
+** Query data
+*** xref:sql:query-data/redpanda-catalogs.adoc[Redpanda Catalogs]
+*** Query Redpanda topics
+*** Query Iceberg
+** Manage Redpanda SQL
+*** xref:sql:manage/manage-access.adoc[Manage access]
 ** xref:sql:troubleshoot/index.adoc[Troubleshoot]
 *** xref:sql:troubleshoot/degraded-state-handling.adoc[]
+*** Memory management
 
 * xref:develop:index.adoc[Develop]
 ** xref:develop:kafka-clients.adoc[]
@@ -515,7 +533,6 @@
 
 * xref:reference:index.adoc[Reference]
 ** xref:reference:sql/index.adoc[Redpanda SQL Reference]
-*** xref:reference:sql/redpanda-catalogs.adoc[]
 *** xref:reference:sql/sql-statements/index.adoc[Statements]
 **** xref:reference:sql/sql-statements/keywords.adoc[]
 **** xref:reference:sql/sql-statements/alter-redpanda-catalog.adoc[]

modules/reference/pages/sql/system-catalogs/index.adoc

@@ -6,7 +6,7 @@ System catalogs are PostgreSQL-compatible metadata tables that store information
 
 [NOTE]
 ====
-System catalogs (`pg_*` tables) are unrelated to xref:reference:sql/redpanda-catalogs.adoc[Redpanda catalogs]. System catalogs provide PostgreSQL-compatible database metadata. Redpanda catalogs are named connections that map Redpanda topics to SQL tables.
+System catalogs (`pg_*` tables) are unrelated to xref:sql:query-data/redpanda-catalogs.adoc[Redpanda catalogs]. System catalogs provide PostgreSQL-compatible database metadata. Redpanda catalogs are named connections that map Redpanda topics to SQL tables.
 ====
 
 [NOTE]

modules/sql/pages/connect-to-sql/connect-with-oidc.adoc

@@ -0,0 +1,83 @@
+= Connect to Redpanda SQL with OIDC
+:description: Authenticate to Redpanda SQL using a bearer token issued by your OIDC identity provider.
+:page-topic-type: how-to
+:personas: app_developer, data_engineer, platform_admin
+:learning-objective-1: Obtain an OIDC bearer token from your identity provider
+:learning-objective-2: Connect to Redpanda SQL with the token using psql or a PostgreSQL client driver
+
+Authenticate to Redpanda SQL using a bearer token issued by your OIDC identity provider. OIDC authenticates the user to Redpanda SQL; per-user data access is enforced separately. See xref:sql:manage/manage-access.adoc[] for the access model.
+
+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].
+* OIDC configured for your Redpanda cluster. See xref:security:authorization/gbac/gbac_dp.adoc[Configure GBAC in the Data Plane] for the cluster-level OIDC setup. Configuring OIDC is not specific to Redpanda SQL.
+* https://www.postgresql.org/download/[`psql`^] or another PostgreSQL-compatible client.
+
+== Obtain a bearer token
+
+Redpanda SQL accepts bearer tokens issued by any OIDC-compliant identity provider configured on the cluster. The token flow you use depends on your scenario:
+
+* *Authorization Code flow* — for users connecting interactively (for example, through a developer workstation).
+* *Client Credentials flow* — for service-to-service connections (for example, a scheduled job or BI tool service account).
+
+// TODO: Confirm the validated IdP coverage with engineering (qa-questions.md #16).
+// E2E tests use Keycloak; Okta, Microsoft Entra ID, Auth0, and Google have not
+// yet been confirmed as explicitly tested for Redpanda SQL bearer-token auth.
+// List validated IdPs here once confirmed.
+
+Refer to your identity provider's documentation for the exact token request. The token must include the standard OIDC claims (`sub`, `aud`, `iss`, `exp`) so Redpanda SQL can verify it.
+
+== Connect with psql
+
+Pass the bearer token in place of the SCRAM password when you connect:
+
+// TODO: Confirm the exact `psql` connection-string format with engineering. Some
+// engines accept the token via the `password` field over a TLS connection;
+// others require an explicit OAUTHBEARER mechanism. Document the supported
+// pattern once confirmed.
+
+[source,bash]
+----
+PGPASSWORD="$BEARER_TOKEN" psql "host=<sql-host> port=<sql-port> dbname=oxla user=<oidc-username> sslmode=require"
+----
+
+The `<oidc-username>` value is the user identifier from your OIDC token (typically the `sub` or `preferred_username` claim, depending on your IdP).
+
+== Connect with a PostgreSQL client driver
+
+For language clients, set the connection password to the bearer token. The example below uses Python's `psycopg2`:
+
+[source,python]
+----
+import os
+import psycopg2
+
+conn = psycopg2.connect(
+    host="<sql-host>",
+    port=<sql-port>,
+    dbname="oxla",
+    user="<oidc-username>",
+    password=os.environ["BEARER_TOKEN"],
+    sslmode="require",
+)
+----
+
+For more language-client examples, see xref:sql:connect-to-sql/index.adoc[Connect to Redpanda SQL].
+
+== Token refresh
+
+OIDC bearer tokens expire. When a token expires, Redpanda SQL closes the connection. Your client must obtain a fresh token from the identity provider and reconnect.
+
+// TODO: Confirm whether Redpanda SQL supports any in-session token refresh
+// (for example, re-presenting a new token on an existing connection) or whether
+// reconnection is always required.
+
+== 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.

modules/sql/pages/manage/manage-access.adoc

@@ -0,0 +1,75 @@
+= Manage access to Redpanda SQL
+:description: Authentication and authorization model for Redpanda SQL — OIDC for authentication, deny-all by default, admin-issued GRANT for per-user table access.
+:page-topic-type: concept
+:personas: platform_admin
+
+Redpanda SQL separates authentication and authorization:
+
+* *Authentication* into Redpanda SQL is handled by your OIDC identity provider, configured at the cluster level.
+* *Authorization* — the data a user can read after they authenticate — is enforced inside Redpanda SQL by table-level `GRANT` statements that an admin issues. Redpanda SQL is deny-all by default.
+
+This page describes the admin-side model. For the client-side connection guide, see xref:sql:connect-to-sql/connect-with-oidc.adoc[].
+
+== Authentication
+
+OIDC authenticates the user to Redpanda SQL. Configuring OIDC is not specific to Redpanda SQL — it is a cluster-level configuration. See xref:security:authorization/gbac/gbac_dp.adoc[Configure GBAC in the Data Plane] for the setup steps.
+
+When a user successfully authenticates with an OIDC bearer token, Redpanda SQL provisions the user automatically on first sign-in.
+
+[CAUTION]
+====
+// TODO: Tighten this caution wording with engineering before publishing
+// (qa-questions.md #17). The underlying issue is OXLA-9382 — concurrent
+// CREATE ROLE under OIDC auto-provisioning corrupts the privilege cache.
+
+Concurrent first-time sign-ins from a connection pool can trigger duplicate role creation under OIDC auto-provisioning, which can corrupt the privilege cache. To avoid this, stagger first-time sign-ins for new OIDC users, or have an admin pre-create the role before the user signs in. Track https://redpandadata.atlassian.net/browse/OXLA-9382[OXLA-9382^] for fix status.
+====
+
+// 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 — regardless of which user issued them — connect to the underlying Redpanda cluster as a single super-user SASL credential associated with the default Redpanda catalog (`default_redpanda_connection`). The super-user credential is provisioned automatically when Redpanda SQL is enabled.
+
+This means:
+
+* Kafka ACLs do not gate query-time access — every query reaches the topics under the super-user SASL credential.
+* The boundary that prevents users from reading data they should not see is enforced inside Redpanda SQL, by `GRANT` and `REVOKE` on the SQL tables themselves.
+
+== Authorization
+
+// TODO: Confirm the GRANT mechanism with engineering (qa-questions.md #21).
+// Specifically: does the SQL `GRANT` statement alone enforce per-user table
+// access, or is an additional ACL / Kafka-side step required? Document the
+// exact scope and granularity (table only, schema-wide, etc.) once confirmed.
+
+Redpanda SQL is deny-all by default. After a user authenticates, they cannot read any table until the admin explicitly grants access. To allow a user to query a table:
+
+. Create a role for the user.
++
+[source,sql]
+----
+CREATE ROLE analyst LOGIN PASSWORD '<password>';
+----
+
+. Grant the role `SELECT` on the table.
++
+[source,sql]
+----
+GRANT SELECT ON TABLE default_redpanda_connection=>orders TO analyst;
+----
+
+. To remove access, revoke the privilege.
++
+[source,sql]
+----
+REVOKE SELECT ON TABLE default_redpanda_connection=>orders FROM analyst;
+----
+
+== Next steps
+
+* xref:sql:connect-to-sql/connect-with-oidc.adoc[Connect with OIDC]: how a user obtains a bearer token and connects to Redpanda SQL.
+* xref:security:authorization/gbac/gbac_dp.adoc[Configure GBAC in the Data Plane]: cluster-level OIDC and GBAC setup.