Connect to the Kafka Schema Registry

To use the Kafka Schema Registry you need three things: its URL, credentials, and permission on the subjects your application touches.

Prerequisites

A Kafka cluster, or a Pulsar cluster with the Kafka protocol enabled, on StreamNative Cloud.
A service account with an API key. See Create an API key.
Schema Registry permissions for that service account, granted through role-based access control (RBAC). See Grant access.

Get the Schema Registry URL

The URL depends on the cluster type.

Kafka cluster
Pulsar cluster
Cloud Console

The Schema Registry is served at the cluster’s HTTP service URL, with no sub-path:

https://<kafka-cluster-dns-name>

snctl get schemaregistry <cluster-name> \
  -o jsonpath='https://{.status.serviceEndpoints[?(@.type=="external")].dnsName}{"\n"}'

On a Pulsar cluster with the Kafka protocol enabled, the URL is the cluster’s HTTP service URL with /kafka appended:

https://<pulsar-cluster-dns-name>/kafka

snctl get pulsarcluster <cluster-name> \
  -o jsonpath='https://{.spec.serviceEndpoints[?(@.type=="service")].dnsName}/kafka{"\n"}'

Go to the Cluster Details page.
Find the HTTP Service URL in the cluster dashboard.
On a Pulsar cluster, append /kafka.

The /kafka sub-path applies only to Pulsar clusters. A URL copied from one cluster type won’t work on the other.

The registry listens on port 443 over HTTPS. See Networking for all cluster endpoints and ports.

Authenticate

Three mechanisms are available.

Basic authentication

Works with every Kafka client. Supply your API key as the password; the username can be any non-empty string.

props.put(KafkaAvroSerializerConfig.SCHEMA_REGISTRY_URL_CONFIG, schemaRegistryUrl);
props.put(KafkaAvroSerializerConfig.BASIC_AUTH_CREDENTIALS_SOURCE, "USER_INFO");
props.put(KafkaAvroSerializerConfig.USER_INFO_CONFIG, String.format("%s:%s", "any-user", apiKey));

Only the password is used as the credential. The username is ignored, so pass any non-empty placeholder.

OAuth2

Available for the Kafka Java client. Add the oauth-client dependency alongside your Kafka client and serializer:

<dependency>
  <groupId>org.apache.kafka</groupId>
  <artifactId>kafka-clients</artifactId>
  <version>3.6.1</version>
</dependency>
<dependency>
  <groupId>io.streamnative.pulsar.handlers</groupId>
  <artifactId>oauth-client</artifactId>
  <version>3.2.2.6</version>
</dependency>
<dependency>
  <groupId>io.confluent</groupId>
  <artifactId>kafka-avro-serializer</artifactId>
  <version>7.5.0</version>
</dependency>

Minimum versions: kafka-clients 3.4.0, oauth-client 3.1.0.4, kafka-avro-serializer 7.5.0.

Before version 3.2.2.6, oauth-client requires Java 17 or later.

On top of the properties that already configure OAuth2 for the Kafka connection, add:

props.put(KafkaAvroSerializerConfig.SCHEMA_REGISTRY_URL_CONFIG, schemaRegistryUrl);
props.put(KafkaAvroSerializerConfig.BEARER_AUTH_CUSTOM_PROVIDER_CLASS,
    "io.streamnative.pulsar.handlers.kop.security.oauth.schema.OauthCredentialProvider");
props.put(KafkaAvroSerializerConfig.BEARER_AUTH_CREDENTIALS_SOURCE, "CUSTOM");

See Configure Kafka clients with OAuth 2.0 for the Kafka-connection half of the configuration.

mTLS

When the cluster presents a TLS listener and mutual TLS is configured, the client certificate identifies the caller and the Authorization header is ignored.

Grant access

Assign one of the Schema Registry roles, scoped to the subjects the client uses:

Role	Grants
`schema-reader`	Read schema definitions.
`schema-writer`	Create and update schemas.
`schema-manager`	Manage compatibility policies, plus everything `schema-writer` grants.
`schema-owner`	Full control, including deleting subjects.

A producer that registers schemas needs schema-writer; a consumer that only resolves them needs schema-reader. See Manage RBAC roles for how to bind a role to a service account.

Some Pulsar clusters authorize Schema Registry access through a single ACL on the registry’s backing topic instead of RBAC. See Kafka Schema Registry on Pulsar clusters.

Verify the connection

List the schema formats the registry supports. A successful response confirms the URL and your credentials:

curl -u "any-user:$API_KEY" https://<schema-registry-url>/schemas/types

["AVRO","JSON","PROTOBUF"]

Then list the subjects registered on the cluster:

curl -u "any-user:$API_KEY" https://<schema-registry-url>/subjects

/subjects returns only the subjects your credentials can read, rather than failing with a permission error. An empty array can mean the registry is empty or that your role doesn’t cover any existing subject.

Introduction

Get Started

Kafka Clusters

Process

Lakehouse

Governance

Migrate

Kafka Clients

Prerequisites

Get the Schema Registry URL

Authenticate

Basic authentication

OAuth2

mTLS

Grant access

Verify the connection

Next steps

Confluent compatibility

Schema ID validation

​Prerequisites

​Get the Schema Registry URL

​Authenticate

​Basic authentication

​OAuth2

​mTLS

​Grant access

​Verify the connection

​Next steps

Confluent compatibility

Schema ID validation

Prerequisites

Get the Schema Registry URL

Authenticate

Basic authentication

OAuth2

mTLS

Grant access

Verify the connection

Next steps