Schema Registry Connection

If your topics carry Avro, Protobuf or JSON Schema messages, KafkIO needs the Schema Registry that holds their schemas: with it, it decodes those messages into readable JSON, can encode new ones when you produce, and lets you browse and manage the schemas themselves. You connect a registry per cluster, on the Schema Registry tab of the Cluster Properties dialog (Add Cluster, or Edit Cluster on a disconnected cluster; see Managing Cluster Configurations).

The registry is a REST API, separate from the brokers: it has its own URL, and its own login and TLS settings, which may or may not match the cluster's. Nothing on the Kafka Security tab applies to it. KafkIO works with Confluent Schema Registry and registries that speak the same API (Confluent Cloud, Karapace on Aiven, WarpStream's registry, for example).

Enabling Schema Registry

Switch on Use Schema Registry 1. The connection settings appear below it, and the only one you must fill in is URL(s): until it holds a valid URL, Save and Test Schema Registry stay greyed out. Everything else is optional and depends on how your registry is secured.

1 2 3 4 5 6 7

1. Use Schema Registry turns the registry on for this cluster.
2. URL(s): one or more registry URLs; see Endpoint URLs.
3. Check network reachability opens the Network Tool with the hosts and ports from the field.
4. Use proxy (if configured); see Using a proxy.
5. User:password for registries that use basic authentication.
6. Add header adds a row of Additional HTTP headers (but see the warning below).
7. Test Schema Registry tries the settings on this tab. It only shows while this tab is open.

With the registry switched on and the cluster connected, the cluster's Schema Registry section (greyed out in the cluster tree otherwise) lists its subjects and schemas (see Schema Registry), and Schema Registry becomes available, and is picked automatically where it fits, as the key and value deserializer when you read messages and the serializer when you produce them (see Deserialization & Formats). Switching it off later keeps what you typed, so you can switch it back on without re-entering it.

KafkIO doesn't contact the registry when it connects to the cluster, so a wrong setting here doesn't stop the cluster connecting: it shows up later, as errors when you open the Schema Registry section or read schema-encoded messages. Run the test before you save.

Endpoint URLs

Enter the registry's base URL, starting with http:// or https:// and including the port: http://localhost:8081 for a local Confluent registry (8081 is its default port), or the endpoint your provider gives you, such as https://psrc-xxxxx.eu-west-1.aws.confluent.cloud on Confluent Cloud. Use the base URL only, without a path such as /subjects. With an https:// URL, the SSL/TLS settings further down apply.

Multiple URLs (failover and round-robin)

If your registry runs as several instances behind no single load balancer, list them all, separated by commas. KafkIO spreads its requests over them in turn and, when one can't be reached, moves on to the next, so the registry stays usable while an instance is down. In the lab, http://localhost:8082,http://localhost:8081 (nothing listening on 8082) tested successfully; http://localhost:8082 alone failed.

Using a proxy

Tick Use proxy (if configured) when the registry can only be reached through the HTTP proxy set up under File ▸ Preferences ▸ Network (see Network, Proxy & Trust). Leave it unticked for a registry on your own network or machine. The box affects Schema Registry requests only.

KafkIO passes only the proxy's host name and port to the registry client: a proxy that needs a username and password won't work for Schema Registry. It also uses that host and port whenever the box is ticked, even if Custom proxy is switched off in the preferences, so untick the box here when you stop using the proxy.

Authentication

A registry on a development machine is usually open. Secured registries expect either a username and password (basic authentication) or an OAuth bearer token. Your provider's documentation, or the basic.auth.user.info / bearer.auth.* settings your applications already use, tell you which.

Basic authentication

Type the username and password into User:password 5, separated by a colon: storefront-app:s3cret-from-your-vault. This is the same value as the basic.auth.user.info setting of Confluent's serializers (the grey note under the label), with basic.auth.credentials.source=USER_INFO implied. On Confluent Cloud the username is the Schema Registry API key and the password its secret (see Provider Recipes).

Additional HTTP headers

Add header 6 adds a Header key / Header value row, and remove next to a row deletes it. The same field on the Kafka Connect and ksqlDB tabs adds the headers to every request, for gateways that want an extra API key header, for example.

OAuth

Registries secured with OAuth 2.0 (Confluent Cloud with identity pools, or a self-managed Confluent registry behind an identity provider such as Okta, Keycloak or Microsoft Entra ID) expect a bearer token on every request. Switch on Oauth 1 to show the settings. They are the bearer.auth.* settings of Confluent's Schema Registry client, named in the grey note under each label, so the values your applications use go straight in. Fields you leave blank use the client's default, which the grey example text in each field shows.

1 2 3 4 5 6 7 8 9 10

1. Oauth shows or hides the OAuth settings. Values stay saved while it's off.
2. Credentials source: OAUTHBEARER (the default) or STATIC_TOKEN; see below.
3. Issuer Endpoint URL: the identity provider's token endpoint (OAUTHBEARER), with its own Check network reachability link.
4. Token: the fixed bearer token (STATIC_TOKEN only).
5. Client ID and, below it, Client secret: the application's credentials at the identity provider (OAUTHBEARER).
6. Scope: the scope to request with the token, if your provider wants one.
7. Scope claim name and, below it, Subject claim name: only if your provider names these token claims differently (defaults scope and sub).
8. Logical cluster: the registry's ID on Confluent Cloud (lsrc-…).
9. Identity pool ID: the Confluent Cloud identity pool (pool-…).
10. Cache expiry buffer (seconds); see below.

OAUTHBEARER: client credentials

With OAUTHBEARER, KafkIO fetches tokens itself with the OAuth 2.0 client credentials flow: it sends the Client ID, Client secret and Scope to the Issuer Endpoint URL (which must start with http:// or https://), and sends the token it gets back to the registry. It keeps the token and asks for a new one shortly before it expires; Cache expiry buffer (seconds) is how long before (0 to 3600; blank means 300, five minutes). Leave Token empty.

STATIC_TOKEN: a fixed token

With STATIC_TOKEN, KafkIO sends whatever you paste into Token (a JWT usually starting eyJ), unchanged, until you replace it. That suits a long-lived token or a quick test with one you got elsewhere; once it expires, requests fail with an authentication error until you edit the cluster and paste a new one. The issuer, client and scope fields are ignored.

Confluent Cloud: logical cluster and identity pool

Confluent Cloud's OAuth support needs two more values, which Confluent's client sends as request headers: Logical cluster, the registry's ID (lsrc-…, shown in the Confluent Cloud console with the registry's endpoint), and Identity pool ID (pool-…), the identity pool that maps your OAuth application to its permissions. Other registries ignore both; leave them empty.

OAuth and basic authentication are alternatives: fill in one or the other.

TLS for Schema Registry

The SSL/TLS section at the bottom of the tab applies when a URL starts with https://. It has the same fields as the Kafka Security tab's, but they're separate settings (the grey notes say schema.registry.ssl.*): KafkIO doesn't reuse the brokers' truststore or keystore for the registry, so if both need the same files, choose them on both tabs.

1 2 3 4 5 6 7

1. Truststore file: the certificates to trust. Leave it blank for the registry's certificate to be checked against KafkIO's default trust (below).
2. Truststore type: Java KeyStore (JKS), P12 / PFX / PKCS12 or CRT / PEM / X.509, as on the Kafka Security tab.
3. Truststore password, if the file has one (hidden for PEM).
4. SSL validation: check that the certificate matches the host name.
5. Two-way SSL/TLS? for registries that ask for a client certificate.
6. The client certificate and private key: Keystore file, Keystore type, Keystore password and Keystore private key password.
7. Want to create a JKS? opens the JKS Converter.

What to fill in depends on the registry's certificate:

• Signed by a public certificate authority (Confluent Cloud, Aiven and most managed services): nothing. Leave Truststore file blank.
• Signed by your organisation's own CA, or self-signed: either choose a truststore that holds the CA certificate here, or add the certificate once under File ▸ Preferences ▸ Network (Trusted certificates), which then covers the Schema Registry and Kafka Connect endpoints of every cluster (not ksqlDB, which needs its own truststore: see ksqlDB Connections). With Truststore file blank, KafkIO trusts what Java trusts plus the certificates added there (or anything, if Accept non-trusted certificates automatically is ticked there).
• Mutual TLS: also switch on Two-way SSL/TLS? and choose the keystore with your client certificate and key, as for brokers. The keystore fields are only used while the switch is on.

SSL validation is unticked on a new cluster, which means KafkIO checks that the certificate is trusted but not that it was issued for the host in the URL. Tick it for anything beyond local testing; see Hostname validation. A truststore or keystore file you choose must exist, or the dialog won't save.

Testing the connection

Click Test Schema Registry 7 (on the first screenshot). KafkIO builds a registry client from the tab as it is now (nothing needs saving first) and asks the registry for its global compatibility level, a small request any working registry and login can answer. A connection was successfully made! means the URL, proxy, login and TLS settings all work. Otherwise an Error connecting dialog shows the underlying error, with the full exception under Show Details.

Errors you're likely to see, and what they usually mean:

A successful test covers the connection only: whether your login may also read or change particular subjects is decided by the registry when you use them. More on reading errors in Troubleshooting Connections.

Related

• Managing Cluster Configurations
• Security & Authentication
• Provider Recipes
• Troubleshooting Connections
• Schema Registry (browsing and managing schemas)
• Deserialization & Formats
• Network, Proxy & Trust
• Kafka & Timeouts