How to Enable the Apicurio Auth Proxy

This guide shows you how to enable the Auth Proxy sidecar in front of Apicurio Registry, set the secret it derives Basic Auth credentials from, move the registry ingresses onto a hostname reserved for the web UI, and allow that hostname on the Keycloak client.

Type

How-to guide

Goal

Accept both OAuth (JWT) and Basic Auth client connections against one Apicurio Registry.

Audience

Platform Operator who can edit the Axual Streaming values, create Secrets, and administer the Apicurio Keycloak realm.

When to use

Use this guide when clients authenticate with OAuth tokens while Governance or other clients still use Basic Auth.

Contents

The sections below cover each task in this guide:

Prerequisites

Confirm the following before you begin.

Access and permissions required

You need the following access and permissions:

  • Permission to edit the Axual Streaming values and apply them.

  • Administrator access to the Apicurio Keycloak realm, to edit the apicurio-web client.

  • Permission to create the DNS record and the TLS Secret for the second hostname the web UI moves to.

Tools and versions required

You need the following tools:

  • helm >= 3.12, or access to the pipeline that applies the values.

  • curl and jq, for the verification step.

Resources that must exist before starting

The following must already exist:

  • A running Apicurio Registry v3, from How to Enable Apicurio Registry.

  • Keycloak authentication on the registry, from How to Configure Apicurio Authentication, because the web UI and the apicurio-web client come from that realm.

  • An OpenID Connect issuer for the OAuth clients, with a JWKS endpoint the registry pod can reach.

  • A second DNS name and TLS certificate for the web UI, because the Auth Proxy takes over the hostname clients use today.

Enable the Auth Proxy sidecar

Apicurio Registry authenticates with one method at a time, so serving OAuth and Basic Auth clients together needs the Auth Proxy sidecar in front of it. Authentication and the Auth Proxy describes what the sidecar does and traces both authentication flows.

Set authProxy.enabled to true in the Axual Streaming values.

values.yaml
apicurio-registry-v3:
  authProxy:
    enabled: true

Then give the proxy the issuer and the JSON Web Token (JWT) key set of the identity provider that mints your clients' tokens. valid-issuer-uri and jwks-endpoint-uri have no defaults, and the proxy rejects every token without them. Those keys, the listening port and the backend address the proxy forwards to are in Auth Proxy configuration.

Configure the Auth Proxy secrets

For a Basic Auth client, the proxy derives the credential it presents to the registry from the client’s username and a salt. The salt is what stops one environment’s derived credentials from working in another, so set a different one per environment.

Replace every <VALUE> placeholder with your own value before applying the values or running a command.
secrets.yaml
apicurio-registry-v3:
  authProxy:
    secrets:
      auth-proxy:
        client-secret-salt: "<CLIENT_SECRET_SALT>"
<CLIENT_SECRET_SALT> is a credential. An installation that keeps credentials out of its values file mounts an existing Kubernetes Secret with authProxy.existingSecretName instead. Both forms, and the optional hash algorithm, are in Auth Proxy secrets.

Swap the ingress hostnames

The Auth Proxy becomes the entry point for every client connection and every Platform Manager call, so it takes the hostname clients already use. The registry’s own ingresses move to a second hostname reserved for the web UI. Make both edits together: a client whose endpoint still resolves to ingress.backend bypasses the proxy and reaches the registry unvalidated.

Table 1. Hostnames before and after the Auth Proxy is enabled
Ingress (values key) Serves before Serves after

ingress.backend

Clients, Platform Manager and the web UI, on apicurio.<DOMAIN>

The web UI only, on apicurio-without-auth-proxy.<DOMAIN>

ingress.ui

The web UI, on apicurio.<DOMAIN>

The web UI, on apicurio-without-auth-proxy.<DOMAIN>

authProxy.ingress

Not deployed

Clients and Platform Manager, on apicurio.<DOMAIN>

Point the Auth Proxy ingress at the clients' hostname

Give authProxy.ingress the hostname ingress.backend served before the Auth Proxy was enabled, for example apicurio.<DOMAIN>. Existing clients and Platform Manager keep working without changing their endpoint, because the proxy now answers at that address.

authProxy.ingress takes a hosts list rather than the single host string the other two ingresses take. Its shape is in authProxy.ingress.

Move the backend and UI ingresses to a second hostname

ingress.backend serves the registry API at /apis and ingress.ui serves the web console at /. They are path-separated, so both take the same second hostname, for example apicurio-without-auth-proxy.<DOMAIN>. Point ui.config.registryApiUrl and security.authentication.keycloak.webRedirectUrl at that hostname too, and see ingress.backend and ingress.ui for the values.

These two ingresses now carry web UI traffic only: the browser loads the console from ingress.ui and calls the registry API through ingress.backend. Those calls have to bypass the Auth Proxy, because the console authenticates against the Apicurio Keycloak, whose tokens the proxy does not validate.

Allow the UI hostname on the Keycloak client

The Keycloak client named by security.authentication.keycloak.webClientId, which the imported realm ships as apicurio-web, must list the console’s new hostname. Without it, login succeeds and every API call the console makes returns 401. This is a Keycloak client setting rather than a chart value.

  1. Open the Apicurio Keycloak admin console.

  2. Open Clients, then the apicurio-web client, then Settings.

  3. Set the two fields to the hostname from the previous section:

    Valid redirect URIs:  https://apicurio-without-auth-proxy.<DOMAIN>/*
Web origins:          https://apicurio-without-auth-proxy.<DOMAIN>

Confirm both client types reach the registry

Apply the values, then call the registry through the Auth Proxy hostname twice, once with a JWT and once with Basic Auth credentials. A proxy that serves one method and rejects the other is the common failure here, so check both.

TOKEN=$(curl -sk -X POST \
  "<VALID_ISSUER_URI>/protocol/openid-connect/token" \
  -d "grant_type=client_credentials&client_id=<CLIENT_ID>&client_secret=<CLIENT_SECRET>" \
  | jq -r '.access_token')

curl -sk -o /dev/null -w '%{http_code}\n' \
  -H "Authorization: Bearer $TOKEN" \
  "https://apicurio.<DOMAIN>/apis/registry/v3/search/artifacts"

curl -sk -o /dev/null -w '%{http_code}\n' \
  -u "<BASIC_AUTH_USERNAME>:<BASIC_AUTH_PASSWORD>" \
  "https://apicurio.<DOMAIN>/apis/registry/v3/search/artifacts"

Both calls return 200. <VALID_ISSUER_URI> is the value set on authProxy.config.auth-proxy.valid-issuer-uri, and Self-Service generates the Basic Auth username and password, as described in Apicurio Registry Authentication for SerDes.

A 401 on the OAuth call means the proxy rejected the token, so check valid-issuer-uri and jwks-endpoint-uri against the issuer that minted it. A 401 on the Basic Auth call means the credentials are not valid for this Instance, so check that Client Authentication is enabled on it.

Then open the web console at the UI hostname. It loads the artifact list after the Apicurio Keycloak login. A console that logs in and then reports 401 on its own API calls is missing the Keycloak client setting from the previous section.

With both methods answering, enable OAuth as a client authentication method on the Instance, described in Client Authentication support for an Instance.