Skip to content

DOC-1550 Unresolved Schema Registry AuthZ issues #1332

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 7 commits into
base: main
Choose a base branch
from
Open

DOC-1550 Unresolved Schema Registry AuthZ issues #1332

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
7 commits
Select commit Hold shift + click to select a range
0c7ecc3
DOC-1550
Feediver1 Aug 21, 2025
3974621
Update modules/manage/pages/schema-reg/schema-reg-authorization.adoc
Feediver1 Aug 21, 2025
6c956d9
CodeRabbit edit suggestions
Feediver1 Aug 21, 2025
d9af199
wip
Feediver1 Aug 21, 2025
bdaf56a
conditionalizations for cloud
Feediver1 Aug 22, 2025
f02cb60
Conditionalized out authN method reqmt for cloud because it is not re…
Feediver1 Aug 25, 2025
c016a80
Add info/link to Console/Cloud & fix links
micheleRP Aug 25, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
106 changes: 72 additions & 34 deletions modules/manage/pages/schema-reg/schema-reg-authorization.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -23,10 +23,16 @@ Starting in v25.2, Schema Registry Authorization provides fine-grained access co

=== How to manage Schema Registry Authorization

You can manage Schema Registry Authorization in two ways:
You can manage Schema Registry Authorization in the following ways:

- **Using rpk**: Use the xref:reference:rpk/rpk-security/rpk-security-acl-create.adoc[`rpk security acl create`] command, just like you would for other Kafka ACLs.
- **Using the API**: Use the link:/api/doc/schema-registry/operation/operation-get_security_acls[Redpanda Schema Registry API] endpoints.
- **rpk**: Use the xref:reference:rpk/rpk-security/rpk-security-acl-create.adoc[`rpk security acl create`] command, just like you would for other Kafka ACLs.
- **Schema Registry API**: Use the link:/api/doc/schema-registry/operation/operation-get_security_acls[Redpanda Schema Registry API] endpoints.
ifndef::env-cloud[]
- **{ui}**: After enabling Schema Registry Authorization for your cluster, you can use {ui} to manage Schema Registry ACLs. See xref:manage:security/authorization/acl.adoc[].
endif::[]
ifdef::env-cloud[]
- **{ui}**: After enabling Schema Registry Authorization for your cluster, you can use {ui} to manage Schema Registry ACLs. See xref:security:/authorization/acl.adoc[].
endif::[]

=== Schema Registry ACL resource types

Expand Down Expand Up @@ -197,11 +203,32 @@ For additional guidance on these operations, see the link:/api/doc/schema-regist
Before you can enable Schema Registry Authorization, you must have:

ifndef::env-cloud[]
* A valid Redpanda Enterprise license
* A valid Redpanda Enterprise license.
endif::[]

ifdef::env-cloud[]
* `rpk` v25.2+ installed. For installation instructions, see xref:manage:rpk/rpk-install.adoc[rpk installation].
endif::[]

ifndef::env-cloud[]
* `rpk` v25.2+ installed. For installation instructions, see xref:get-started:rpk-install.adoc[rpk installation].
endif::[]

* `rpk` v25.2+
* Cluster administrator permissions to modify cluster configuration
ifndef::env-cloud[]
* Authentication enabled using `schema_registry_api.authn_method`, which specifies how clients must authenticate when accessing the Schema Registry API. See xref:reference:properties/broker-properties.adoc#schema-registry[Schema Registry broker properties].
endif::[]

ifndef::env-cloud[]
* If you have listeners configured for Schema Registry, ensure you xref:manage:security/authentication.adoc#basic-authentication[configure authentication] for them and that your configuration points to the correct Schema Registry address (correct scheme, host, and port) for the same cluster you are targeting with your Kafka brokers.
endif::[]

* Cluster administrator permissions to modify cluster configurations.
For example, to enable management of Schema Registry ACLs by the principal `schema_registry_admin`, run:

[,bash]
----
rpk security acl create --allow-principal schema_registry_admin --cluster --operation alter
----

=== Enable authorization

Expand All @@ -212,13 +239,6 @@ To enable Schema Registry Authorization for your cluster, run:
rpk cluster config set schema_registry_enable_authorization true
----

To enable management of Schema Registry ACLs by the principal `schema_registry_admin`, run:

[,bash]
----
rpk security acl create --allow-principal schema_registry_admin --cluster --operation alter
----

For details, see xref:reference:properties/cluster-properties.adoc#schema_registry_enable_authorization[`schema_registry_enable_authorization`].

== Create and manage Schema Registry ACLs
Expand Down Expand Up @@ -287,7 +307,7 @@ rpk security acl create \
--allow-role SoftwareEng

# You can add more ACLs to this role later
rpk security acl create --allow-role "RedpandaRole:SoftwareEng" [additional-acl-flags]
rpk security acl create --allow-role "SoftwareEng" [additional-acl-flags]
----

After creating the role, assign it to users:
Expand All @@ -306,7 +326,7 @@ jane User

When creating ACLs that include Schema Registry subjects, you might encounter errors if the subject doesn't exist or if there are configuration issues.

==== Common error: Subject not found
==== Subject not found

Sometimes an ACL for a Kafka topic is created successfully, but the Schema Registry subject ACL fails:

Expand Down Expand Up @@ -349,31 +369,49 @@ User:alice * SUBJECT bar-value LITERAL READ
User:alice * TOPIC bar LITERAL READ ALLOW
----

The `Not found` error occurs in the request: `12:17:33.935 DEBUG sending request {"method": "POST", "URL: "http://127.0.0.1:8081/security/acls", "has_bearer": false,
"has_basic_auth": false}`, meaning that the endpoint is not available (because you are using an older Redpanda version). You must upgrade to the current version of Redpanda.
The `Not found` error occurs in the request: `12:17:33.935 DEBUG sending request {"method": "POST", "URL: "http://127.0.0.1:8081/security/acls", "has_bearer": false,
"has_basic_auth": false}`. This typically means the endpoint is unavailable. Verify:
* You're on Redpanda v25.2+.
* `schema_registry_enable_authorization` is set to `true`.
* Your rpk Schema Registry URL points to the correct host/scheme/port.
Upgrade if needed and correct configuration before retrying.

ifndef::env-cloud[]
This next error occurs when the user tries to create two ACLs, one for a topic and one for a registry-subject:
==== Inconsistent listener configuration

[bash]
This error occurs when the user tries to create an ACL for a principal:

[,bash]
----
$ rpk security acl create --topic private --allow-principal mary --operation read --registry-subject private-key -v
18:27:05.485 DEBUG opening connection to broker {"addr": "127.0.0.1:9092", "broker": "seed_0"}
18:27:05.485 DEBUG connection opened to broker {"addr": "127.0.0.1:9092", "broker": "seed_0"}
18:27:05.485 DEBUG issuing api versions request {"broker": "seed_0", "version": 4}
18:27:05.485 DEBUG wrote ApiVersions v4 {"broker": "seed_0", "bytes_written": 31, "write_wait": "14.584µs", "time_to_write": "18.25µs", "err": null}
18:27:05.487 DEBUG read ApiVersions v4 {"broker": "seed_0", "bytes_read": 331, "read_wait": "23.583µs", "time_to_read": "1.847542ms", "err": null}
18:27:05.487 DEBUG connection initialized successfully {"addr": "127.0.0.1:9092", "broker": "seed_0"}
18:27:05.487 DEBUG wrote CreateACLs v2 {"broker": "seed_0", "bytes_written": 45, "write_wait": "2.564792ms", "time_to_write": "8.75µs", "err": null}
18:27:05.489 DEBUG read CreateACLs v2 {"broker": "seed_0", "bytes_read": 19, "read_wait": "20.042µs", "time_to_read": "1.465375ms", "err": null}
18:27:05.489 DEBUG sending request {"method": "POST", "URL": "http://127.0.0.1:8081/security/acls", "has_bearer": false, "has_basic_auth": false}
rpk security acl create --allow-principal "superuser" --operation "all" --registry-global -v
13:07:02.810 DEBUG opening connection to broker {"addr": "seed-036d6a67.d2hiu9c8ljef72usuu20.fmc.prd.cloud.redpanda.com:9092", "broker": "seed_0"}
...
13:07:03.304 DEBUG sending request {"method": "POST", "URL": "https://127.0.0.1:8080/security/acls", "has_bearer": false, "has_basic_auth": true}
PRINCIPAL HOST RESOURCE-TYPE RESOURCE-NAME RESOURCE-PATTERN-TYPE OPERATION PERMISSION ERROR
User:superuser * REGISTRY LITERAL ALL ALLOW unable to POST "https://127.0.0.1:8080/security/acls": Post "https://127.0.0.1:8080/security/acls": http: server gave HTTP response to HTTPS client
----

When using Schema Registry Authorization, ensure that your Kafka brokers and Schema Registry address target the same cluster and that the Schema Registry address uses the correct scheme/host/port. In the example above, `rpk` communicates with a remote broker (`...:9092`) but posts to a local Schema Registry address over HTTPS (`https://127.0.0.1:8080/security/acls`), while the local Schema Registry appears to be HTTP-only. To align them:
* Set the correct Schema Registry address (host and scheme) for the target cluster.
* Ensure TLS settings match the Schema Registry endpoint (HTTP vs HTTPS).
* Avoid mixing remote broker addresses with a local Schema Registry address unless it is intentional and properly configured.

See xref:reference:rpk/rpk-registry/rpk-registry.adoc[rpk registry] for Schema Registry configuration commands.

==== Resource names do not appear

The following output appears to suggest that there are missing resource names for the registry resource types:

[,bash]
----
rpk security acl create --allow-principal jane --operation read,write --topic private --registry-global
PRINCIPAL HOST RESOURCE-TYPE RESOURCE-NAME RESOURCE-PATTERN-TYPE OPERATION PERMISSION ERROR
User:mary * SUBJECT private-key LITERAL READ ALLOW Invalid license: not present
User:mary * TOPIC private LITERAL READ ALLOW
User:jane * REGISTRY LITERAL READ ALLOW
User:jane * REGISTRY LITERAL WRITE ALLOW
User:jane * TOPIC private LITERAL READ ALLOW
User:jane * TOPIC private LITERAL WRITE ALLOW
----

The `Invalid license: not present` error indicates that the user is trying to create an ACL for a resource that requires a license, but no license is present. See xref:get-started:licensing/overview.adoc[Licensing overview] for details on how to obtain a license.
endif::[]
When using the `--registry-global` option, be aware that `REGISTRY` resource types are global and apply to all of Schema Registry. They do not have a resource name because they are not tied to a specific resource. There are no resource names missing here.

== Suggested reading

Expand Down
8 changes: 7 additions & 1 deletion modules/reference/pages/properties/cluster-properties.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -5679,15 +5679,21 @@ Always normalize schemas. If set, this overrides the `normalize` parameter in re
=== schema_registry_enable_authorization

Enables ACL-based authorization for Schema Registry requests. When `true`, Schema Registry
uses ACL-based authorization instead of the default `public/user/superuser` authorization model. Requires authentication to be enabled using the xref:reference:properties/broker-properties.adoc#schema_registry_auth_method[`authentication_method`] property in the `schema_registry_api` broker configuration.
uses ACL-based authorization instead of the default `public/user/superuser` authorization model.

ifndef::env-cloud[]
Requires authentication to be enabled using the xref:reference:properties/broker-properties.adoc#schema_registry_auth_method[`authentication_method`] property in the `schema_registry_api` broker configuration.
endif::[]

*Requires restart:* No

*Visibility:* `user`

*Type:* boolean

ifndef::env-cloud[]
*Enterprise license required:* `true`
endif::[]

*Default:* `false`

Expand Down