Skip to main content

Enable OAuth 2.0/OIDC authentication for Aiven for Apache Kafka® Schema Registry

Use OAuth 2.0/OpenID Connect (OIDC) to authenticate requests to Karapace Schema Registry with JSON Web Tokens (JWTs) issued by your identity provider.

You can also enable role-based authorization to control which Schema Registry operations clients can perform.

OAuth 2.0/OIDC token handling​

Karapace Schema Registry validates JWTs sent with the Bearer authentication scheme. It checks tokens against the OIDC provider settings for the Aiven for Apache Kafka service.

This differs from the Karapace REST proxy, where Apache Kafka validates the bearer token. Schema Registry also validates the token.

When you enable OIDC authentication, clients can use a bearer token or basic authentication. Enabling OIDC authentication does not turn off basic authentication.

note

Keep basic authentication on while you migrate clients to JWT authentication. After all clients use JWT authentication, turn off basic authentication.

Authorization enforcement​

By default, any client with a valid token can access Schema Registry. To restrict access, enable role-based authorization.

Karapace extracts roles from the JWT using a configured claim path. It checks those roles against the roles allowed for the requested HTTP method.

Enable OIDC authentication before you enable role-based authorization.

Prerequisites​

Before you begin, make sure you have:

  • An Aiven for Apache Kafka® service with Schema Registry enabled
  • Karapace version 6.2.1 or later
  • Access to an OIDC-compliant identity provider
  • OIDC provider settings configured for your Aiven for Apache Kafka service, including kafka.sasl_oauthbearer_jwks_endpoint_url, kafka.sasl_oauthbearer_expected_issuer, and kafka.sasl_oauthbearer_expected_audience

Schema Registry uses the same OIDC provider settings as Apache Kafka. Those settings include the JWKS endpoint, the expected issuer, and the expected audience.

The Aiven Console does not require the issuer and audience. Schema Registry uses them to validate tokens.

For more information about configuring these settings, see Enable OAuth 2.0/OIDC authentication for Apache Kafka®.

note

If your service runs a Karapace version earlier than 6.2.1, apply the available maintenance update first. For more information, see Set the Karapace version.

Enable OIDC authentication​

  1. In the Aiven Console, select your project and choose your Aiven for Apache Kafka service.
  2. Click Service settings.
  3. Click Advanced configuration > Configure.
  4. Click Add configuration options.
  5. Add schema_registry_config.sasl_oauthbearer_authentication_enabled.
  6. Set the option to Enabled.
  7. Click Save configuration.

Enable role-based authorization​

Enable role-based authorization to restrict Schema Registry operations based on roles in the JWT.

Before you enable authorization, set schema_registry_config.sasl_oauthbearer_authentication_enabled to Enabled.

You can customize how Karapace reads and applies roles:

  • schema_registry_config.sasl_oauthbearer_roles_claim_path: Claim path used to extract roles from the JWT. The default is resource_access.karapace.roles. Set this option if your identity provider stores roles at a different path.
  • schema_registry_config.sasl_oauthbearer_method_roles: Maps HTTP methods to the roles allowed to use them. Set this option to customize access for GET, POST, PUT, and DELETE requests.

Role names use the karapace. prefix, for example karapace.schema:read.

Default HTTP method roles​

If you do not set schema_registry_config.sasl_oauthbearer_method_roles, Karapace allows only read access.

ActionHTTP methodDefault roles
Read schemasGETkarapace.schema:read, karapace.subject:read
Register or update schemasPOST, PUTNone
Delete schemasDELETENone

An empty array ([]) means no role can use that method.

Karapace uses the following default mapping:

{
  "GET": [
    "karapace.schema:read",
    "karapace.subject:read"
  ],
  "POST": [],
  "PUT": [],
  "DELETE": []
}

To allow write access, set schema_registry_config.sasl_oauthbearer_method_roles.

Configure authorization​

  1. In the Aiven Console, select your project and choose your Aiven for Apache Kafka service.
  2. Click Service settings.
  3. Click Advanced configuration > Configure.
  4. Make sure schema_registry_config.sasl_oauthbearer_authentication_enabled is set to Enabled.
  5. Click Add configuration options.
  6. Add schema_registry_config.sasl_oauthbearer_authorization_enabled and set it to Enabled.
  7. Optional: Add schema_registry_config.sasl_oauthbearer_roles_claim_path if your JWT stores roles somewhere other than resource_access.karapace.roles.
  8. Optional: Add schema_registry_config.sasl_oauthbearer_method_roles to customize which roles can use each HTTP method.
  9. Click Save configuration.

Configure roles for HTTP methods​

Set schema_registry_config.sasl_oauthbearer_method_roles to JSON that maps each HTTP method to the roles that can use it.

Clients with karapace.schema:read can read schemas. Clients with karapace.schema:write can read and write schemas.

RoleAllowed actions
karapace.schema:readRead schemas (GET)
karapace.schema:writeRead and write schemas (GET, POST, PUT, DELETE)

Each key in the JSON is an HTTP method. Each value is the list of roles allowed for that method:

{
  "GET": [
    "karapace.schema:read",
    "karapace.schema:write"
  ],
  "POST": [
    "karapace.schema:write"
  ],
  "PUT": [
    "karapace.schema:write"
  ],
  "DELETE": [
    "karapace.schema:write"
  ]
}

When you set this option, include GET, POST, PUT, and DELETE. To block a method, set its value to [].

Send a request to Schema Registry​

Send the JWT in the Authorization header of each Schema Registry request. You can use curl or any HTTP client that supports bearer tokens.

On the service Overview page, open Connection information and copy the Schema Registry URL.

The following example lists subjects:

curl \
  --header "Authorization: Bearer ACCESS_TOKEN" \
  "SCHEMA_REGISTRY_URL/subjects"

Replace the following:

  • ACCESS_TOKEN: a valid JWT from your identity provider
  • SCHEMA_REGISTRY_URL: the Schema Registry URL from Connection information

This example uses GET, so it works with the default read roles. If authorization is on, a POST, PUT, or DELETE request needs a write role.

Disable OAuth 2.0/OIDC authentication​

To turn off OIDC authentication and authorization, set both options to Disabled. This does not turn off basic authentication.

  1. In the Aiven Console, select your project and choose your Aiven for Apache Kafka service.
  2. Click Service settings.
  3. Click Advanced configuration > Configure.
  4. Set schema_registry_config.sasl_oauthbearer_authorization_enabled to Disabled.
  5. Set schema_registry_config.sasl_oauthbearer_authentication_enabled to Disabled.
  6. Click Save configuration.

Related pages