Docs Cloud Manage Schema Registry Schema Registry Authorization Schema Registry Authorization Page options Copy as Markdown Copied! View as plain text Ask AI about this topic Add MCP server to VS Code Schema Registry Authorization enables fine-grained restriction of operations to Schema Registry resources by user or role through access control lists (ACLs). About Schema Registry Authorization Schema Registry Authorization allows you to control which users and applications can perform specific operations within the Redpanda Schema Registry. This ensures that only authorized entities can read, write, modify, delete, or configure schemas and their settings. Before v25.2, Schema Registry supported authentication, but once a user was authenticated, they had full access to all Schema Registry operations, including reading, modifying, and deleting schemas and configuration both per-subject and globally. Starting in v25.2, Schema Registry Authorization provides fine-grained access control through ACLs. You can now restrict access to specific subjects and operations. How to manage Schema Registry Authorization You can manage Schema Registry Authorization in the following ways: rpk: Use the rpk security acl create command, just like you would for other Kafka ACLs. Schema Registry API: Use the Redpanda Schema Registry API endpoints. Redpanda Cloud: After enabling Schema Registry Authorization for your cluster, you can use Redpanda Cloud to manage Schema Registry ACLs. See Configure ACLs. Schema Registry ACL resource types Schema Registry Authorization introduces two new ACL resource types in addition to the standard Kafka ACL resources (topic, group, cluster, and transactional_id): registry: Controls whether or not to grant ACL access to global, or top-level Schema Registry operations. Specify using the flag registry-global. subject: Controls ACL access for specific Schema Registry subjects. Specify using the flag registry-subject. Supported operations Redpanda Schema Registry ACLs support the following specific subset of Schema Registry endpoints and operations: Not all Kafka operations are supported when using Redpanda Schema Registry ACLs. Endpoint HTTP method Operation Resource /config GET describe_configs registry /config PUT alter_configs registry /config/{subject} GET describe_configs subject /config/{subject} PUT alter_configs subject /config/{subject} DELETE alter_configs subject /mode GET describe_configs registry /mode PUT alter_configs registry /mode/{subject} GET describe_configs subject /mode/{subject} PUT alter_configs subject /mode/{subject} DELETE alter_configs subject /schemas/types GET none/open - /schemas/ids/{id} GET read subject /schemas/ids/{versions} GET describe registry /schemas/ids/{subjects} GET describe registry /subjects GET describe subject /subjects/{subject} POST write subject /subjects/{subject} DELETE delete subject /subjects/{subject}/versions GET describe subject /subjects/{subject}/versions POST write subject /subjects/{subject}/versions/{version} GET read subject /subjects/{subject}/versions/{version} DELETE delete subject /subjects/{subject}/versions/schema GET read subject /subjects/{subject}/versions/referencedby GET describe registry /compatibility/subjects/{subject}/versions/{version} POST read subject /status/ready GET none/open - /security/acls GET describe cluster /security/acls POST alter cluster /security/acls DELETE alter cluster For additional guidance on these operations, see the Redpanda Schema Registry API. Operation definitions You can use the following operations to control access to Schema Registry resources: read: Allows user to read schemas and their content. Required for consuming messages that use Schema Registry, fetching specific schema versions, and reading schema content by ID. write: Allows user to register new schemas and schema versions. Required for producing messages with new schemas and updating existing subjects with new schema versions. delete: Allows user to delete schema versions and subjects. Required for cleanup operations and removing deprecated schemas. describe: Allows user to list and describe Schema Registry resources. Required for discovering available subjects, listing schema versions, and viewing metadata. describe_configs: Allows user to read configuration settings. Required for viewing compatibility settings, reading modes (IMPORT/READWRITE), and checking global or per-subject configurations. alter_configs: Allows user to modify configuration settings. Required for changing compatibility levels, setting IMPORT mode for migrations, and updating global or per-subject configurations. Common use cases The following examples show which operations are required for common Schema Registry tasks: Schema Registry migration When migrating schemas between clusters, you must have different ACLs for source and target clusters. Source cluster (read-only): # Read schemas from source Schema Registry rpk security acl create \ --allow-principal User:migrator-user \ --operation read,describe \ --registry-global \ --brokers <source-brokers> This grants: read - Read schemas by ID from source describe - List all subjects in source The describe_configs operation is required to read Schema Registry configuration settings, including compatibility modes and IMPORT mode status. Target cluster (read-write): # Write schemas to target Schema Registry and manage IMPORT mode rpk security acl create \ --allow-principal User:migrator-user \ --operation write,describe,alter_configs,describe_configs \ --registry-global \ --brokers <target-brokers> This grants: write - Register schemas in target with preserved IDs describe - List all subjects in target alter_configs - Set IMPORT mode on target Schema Registry describe_configs - Read compatibility settings and mode Schema Registry ACLs are only for Schema Registry operations. For complete data migration, you must also use Kafka ACLs: Topics: READ (source), WRITE/CREATE/DESCRIBE/ALTER (target) Consumer groups: READ (source), CREATE/READ (target) Cluster: DESCRIBE (both), CREATE (target) See Configure Access Control Lists for Kafka ACL configuration. The target Schema Registry must be in IMPORT mode to preserve schema IDs during migration. Only superusers or principals with alter_configs permission on the registry resource can change the global mode. See Set global mode. Complete migration setup workflow For a complete migration setup, follow this workflow: Bootstrap superusers - Configure superusers using .bootstrap.yaml before enabling authentication Create migration user - Create dedicated migration user with minimal required permissions Configure Schema Registry ACLs - Grant read access on source, read-write access on target Configure Kafka ACLs - Grant topic read/write, consumer group, and cluster permissions Enable SASL authentication - Enable SASL/SCRAM-SHA-256 on both clusters Enable ACL authorization - Enable kafka_enable_authorization and schema_registry_enable_authorization Set target to IMPORT mode - Enable IMPORT mode on target Schema Registry Start migration - Begin data and schema migration Verify ACLs - Test that permissions work correctly and restrictions are enforced Complete migration - Disable IMPORT mode after migration completes For a complete working example with Docker Compose, see the Redpanda Migrator Demo. Schema Registry Internal Client Authentication: When SASL authentication is enabled on your Kafka cluster, the Schema Registry’s internal Kafka client must also be configured with SASL credentials. Configure these using node-level properties: --set schema_registry_client.scram_username=<username> --set schema_registry_client.scram_password=<password> --set schema_registry_client.sasl_mechanism=SCRAM-SHA-256 Without these credentials, Schema Registry operations that interact with Kafka (like storing schema data) will fail with "broker_not_available" errors. Read-only access for consumers Applications that only consume messages with schemas require: # For consuming with schema validation rpk security acl create \ --allow-principal consumer-app \ --operation read \ --registry-subject "orders-*" \ --resource-pattern-type prefixed This allows: Reading schema content by ID (embedded in messages) Viewing specific schema versions This does not allow listing all subjects or modifying schemas. Producer access Applications that produce messages with schemas require: # For producing with new schemas rpk security acl create \ --allow-principal producer-app \ --operation read,write,describe \ --registry-subject "orders-*" \ --resource-pattern-type prefixed This allows: Checking if schemas already exist (describe) Reading existing schema versions (read) Registering new schema versions (write) Schema administrator access Schema administrators who manage compatibility and cleanup require: # For full schema management rpk security acl create \ --allow-principal schema-admin \ --operation all \ --registry-global This grants all operations, including: Managing compatibility settings Deleting deprecated schemas Viewing and modifying configurations Listing all subjects and schemas Pattern-based ACLs for Schema Registry When using subject name patterns (like orders-*), always specify --resource-pattern-type prefixed: # Correct - matches all subjects starting with "orders-" rpk security acl create \ --allow-principal User:app \ --operation read \ --registry-subject "orders-" \ --resource-pattern-type prefixed # Incorrect - treats "orders-*" as literal subject name rpk security acl create \ --allow-principal User:app \ --operation read \ --registry-subject "orders-*" Pattern types: prefixed - Matches subjects starting with the specified string (for example, orders- matches orders-value, orders-key) literal - Matches exact subject name only (default if not specified) Redpanda recommends using the topic naming strategy where subjects follow the pattern <topicName>-key or <topicName>-value. With this strategy, you can use a single prefixed ACL to grant access to both key and value subjects for a topic. Example: --registry-subject "orders-" --resource-pattern-type prefixed grants access to both orders-key and orders-value subjects. Enable Schema Registry Authorization Prerequisites Before you can enable Schema Registry Authorization, you must have: rpk v25.2+ installed. For installation instructions, see rpk installation. 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 To enable Schema Registry Authorization for your cluster, run: rpk cluster config set schema_registry_enable_authorization true For details, see schema_registry_enable_authorization. Create and manage Schema Registry ACLs This section shows you how to create and manage ACLs for Schema Registry resources. Create an ACL for a topic and Schema Registry subject This example creates an ACL that allows the principal panda to read from both the topic bar and the Schema Registry subject bar-value. This pattern is common when you want to give a user or application access to both the Kafka topic and its associated schema. rpk security acl create --allow-principal panda --operation read --topic bar --registry-subject bar-value PRINCIPAL HOST RESOURCE-TYPE RESOURCE-NAME RESOURCE-PATTERN-TYPE OPERATION PERMISSION ERROR User:panda * SUBJECT bar-value LITERAL READ ALLOW User:panda * TOPIC bar LITERAL READ ALLOW Create an ACL for global Schema Registry access This example grants the user jane global read and write access to the Schema Registry, plus read and write access to the topic private. The --registry-global flag creates ACLs for all global Schema Registry operations. 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: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 User jane now has global read and write access to the Schema Registry and to the topic private. Create a role with Schema Registry ACLs You can combine Schema Registry ACLs with role-based access control (RBAC) to create reusable roles. This approach simplifies permission management when you need to assign the same set of permissions to multiple users. This example creates a role called SoftwareEng and assigns it ACLs for both topic and Schema Registry access: # Create the role rpk security role create SoftwareEng # Create ACLs for the role rpk security acl create \ --operation read,write \ --topic private \ --registry-subject private-key,private-value \ --allow-role SoftwareEng # You can add more ACLs to this role later rpk security acl create --allow-role "SoftwareEng" [additional-acl-flags] After creating the role, assign it to users: rpk security role assign SoftwareEng --principal User:john,User:jane Successfully assigned role "SoftwareEng" to NAME PRINCIPAL-TYPE john User jane User Troubleshooting ACL creation When creating ACLs that include Schema Registry subjects, you might encounter errors if the subject doesn’t exist or if there are configuration issues. Subject not found Sometimes an ACL for a Kafka topic is created successfully, but the Schema Registry subject ACL fails: rpk security acl create --allow-principal alice --operation read --topic bar --registry-subject bar-value PRINCIPAL HOST RESOURCE-TYPE RESOURCE-NAME RESOURCE-PATTERN-TYPE OPERATION PERMISSION ERROR User:alice * SUBJECT bar-value LITERAL READ ALLOW Not found User:alice * TOPIC bar LITERAL READ ALLOW In this example, the ACL for topic bar was created successfully, but the ACL for Schema Registry subject bar-value failed with a "Not found" error. Common causes: Incorrect Schema Registry URL configuration Using the incorrect version of Redpanda Debugging with verbose output To get more detailed information about ACL creation failures, use the -v flag for verbose logging. In this case, the user gets a Not found error after attempting to create two ACLs, one for the subject and one for the topic: rpk security acl create --allow-principal alice --operation read --topic bar --registry-subject bar-value -v 12:17:33.911 DEBUG opening connection to broker {"addr": "127.0.0.1:9092", "broker": "seed_0"} 12:17:33.912 DEBUG connection opened to broker {"addr": "127.0.0.1:9092", "broker": "seed_0"} 12:17:33.912 DEBUG issuing api versions request {"broker": "seed_0", "version": 4} 12:17:33.912 DEBUG wrote ApiVersions v4 {"broker": "seed_0", "bytes_written": 31, "write_wait": 13.416µs", "time_to_write": "17.75µs", "err": null} 12:17:33.912 DEBUG read ApiVersions v4 {"broker": "seed_0", "bytes_read": 266, "read_wait": 16.209µs", "time_to_read": "8.360666ms", "err": null} 12:17:33.920 DEBUG connection initialized successfully {"addr": "127.0.0.1:9092", "broker": "seed_0"} 12:17:33.920 DEBUG wrote CreateACLs v2 {"broker": "seed_0", "bytes_written": 43, "write_wait": 9.0985ms, "time_to_write": "14µs", "err": null} 12:17:33.935 DEBUG read CreateACLs v2 {"broker": "seed_0", "bytes_read": 19, "read_wait": 23.792µs, "time_to_read": "14.323041ms", "err": null} 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} PRINCIPAL HOST RESOURCE-TYPE RESOURCE-NAME RESOURCE-PATTERN-TYPE OPERATION PERMISSION ERROR User:alice * SUBJECT bar-value LITERAL READ ALLOW Not found 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}. 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. Inconsistent listener configuration This error occurs when the user tries to create an ACL for a principal: 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 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: 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: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 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. Schema Registry "broker_not_available" errors If Schema Registry operations fail with broker_not_available errors after enabling SASL: {"error_code":50302,"message":"{ node: -1 }, { error_code: broker_not_available [8] }"} Cause: The Schema Registry’s internal Kafka client is not configured with SASL credentials. Solution: Configure the Schema Registry client credentials: rpk cluster config set schema_registry_client.scram_username <username> rpk cluster config set schema_registry_client.scram_password <password> rpk cluster config set schema_registry_client.sasl_mechanism SCRAM-SHA-256 Then restart the Schema Registry service. Pattern-based ACL not working If a pattern-based ACL (like orders-*) is not matching expected subjects: Cause: Missing --resource-pattern-type prefixed flag. Solution: Recreate the ACL with the correct pattern type: # Delete incorrect ACL rpk security acl delete \ --allow-principal User:app \ --operation read \ --registry-subject "orders-*" # Create correct ACL with pattern type rpk security acl create \ --allow-principal User:app \ --operation read \ --registry-subject "orders-" \ --resource-pattern-type prefixed Pattern matching uses the string without the asterisk when using prefixed type. Suggested reading Redpanda Schema Registry rpk registry Schema Registry API Monitor Schema Registry service-level metrics Deserialization Back to top × Simple online edits For simple changes, such as fixing a typo, you can edit the content directly on GitHub. Edit on GitHub Or, open an issue to let us know about something that you want us to change. Open an issue Contribution guide For extensive content updates, or if you prefer to work locally, read our contribution guide . Was this helpful? thumb_up thumb_down group Ask in the community mail Share your feedback group_add Make a contribution 🎉 Thanks for your feedback! Use the Schema Registry API Deserialization