:_mod-docs-content-type: CONCEPT

[id='assembly-oauth-server-config-{context}']
= Server-side configuration

[role="_abstract"]
Server-side configuration enables OAuth 2.0 token-based authentication on Kafka listeners.

To configure OAuth 2.0 on the server side, define the `custom` authentication type on the listeners used by clients. 
The configuration specifies how Kafka brokers validate tokens. 

Strimzi supports OAuth 2.0 for both server-side and client-side authentication. 
Kafka brokers validate tokens using the OAuth configuration defined on the listener, and Kafka components, such as Kafka Connect, MirrorMaker 2, and the HTTP Bridge authenticate as OAuth clients when connecting to Kafka.

If using Keycloak as an authorization server, you can also enable authorization via Authorization Services, which provides fine-grained policy-based permissions management for Kafka resources.
For more information, see xref:con-oauth-authz-config-{context}[Enabling authorization on Kafka brokers].

The following sections describe the minimal configuration required for:

* Preparing an OAuth 2.0 authorization server
* Configuring token-based authentication on Kafka listeners

NOTE: Advanced OAuth settings such as timeouts, JWKS refresh, introspection, and TLS options are described
in the {oauth-project}.
Keycloak-specific examples for use with Strimzi are provided in the xref:config-examples-{context}[example configuration files].

== Requirements for the authorization server

To use OAuth 2.0 token-based security with Strimzi, you need an OAuth 2.0–compliant authorization server that issues access tokens for Kafka clients.

The authorization server must provide the following capabilities:

* An endpoint for issuing access tokens.
* A JWKS endpoint for publishing signing keys, or an introspection endpoint for validating opaque tokens.
* TLS support for secure communication with Kafka brokers.
* Client registrations when the broker or Kafka clients must authenticate to protected endpoints.
For example, a client ID and secret are required when using a protected introspection endpoint.

Only one validation method is required:

* **Local: JWT validation** using the JWKS endpoint  
* **Remote: Token introspection** using the introspection endpoint  

The authorization server must expose the selected endpoint externally so that Kafka brokers can validate tokens at runtime.

== Configuring authentication on Kafka listeners

To enable OAuth 2.0 token-based authentication on a Kafka listener, configure the `custom` authentication type with the `OAUTHBEARER` SASL mechanism. The listener configuration specifies the callback handler and JAAS module used to validate tokens.

All OAuth 2.0 validation settings (such as JWKS or token introspection) are provided through the JAAS configuration string inside the listener configuration.

=== JWT validation example

The following example shows a minimal listener configuration that validates JSON Web Tokens (JWTs) using a JWKS endpoint.

[source,yaml]
----
# ...
listeners:
  - name: tls
    port: 9093
    type: internal
    tls: true
    authentication:
      type: custom
      sasl: true
      listenerConfig:
        sasl.enabled.mechanisms: OAUTHBEARER
        oauthbearer.sasl.server.callback.handler.class: io.strimzi.kafka.oauth.server.JaasServerOauthValidatorCallbackHandler
        oauthbearer.sasl.jaas.config: |
          org.apache.kafka.common.security.oauthbearer.OAuthBearerLoginModule required
            oauth.valid.issuer.uri="https://${SSO_HOST}/realms/kafka-authz"
            oauth.jwks.endpoint.uri="https://${SSO_HOST}/realms/kafka-authz/protocol/openid-connect/certs"
            oauth.username.claim="preferred_username"
            oauth.ssl.truststore.location="/mnt/oauth-certs/tls.crt"
            oauth.ssl.truststore.type="PEM";
        connections.max.reauth.ms: 3600
----

In this configuration:

* The listener uses the `OAUTHBEARER` SASL mechanism.
* Tokens are validated locally using the JWKS endpoint published by the authorization server.
* The JAAS module and callback handler perform token validation and map a specified token claim to the Kafka principal.
* The truststore is mounted into the Kafka pod and used for TLS connections to the JWKS endpoint.
* The listener requires periodic re-authentication.
The `connections.max.reauth.ms` setting ensures that the broker prompts clients to re-authenticate at regular intervals, allowing expiring OAuth access tokens to be refreshed without closing the connection.

=== Token introspection example

The following example shows a listener configuration that validates opaque access tokens using an OAuth 2.0 introspection endpoint. 
The Kafka broker authenticates to the authorization server using a client ID and a client secret configured in the JAAS module.

[source,yaml]
----
# ...
spec:
  kafka:
    listeners:
      - name: tls
        port: 9093
        type: internal
        tls: true
        authentication:
          type: custom
          sasl: true
          listenerConfig:
            sasl.enabled.mechanisms: OAUTHBEARER
            oauthbearer.sasl.server.callback.handler.class: io.strimzi.kafka.oauth.server.JaasServerOauthValidatorCallbackHandler
            oauthbearer.sasl.jaas.config: |
              org.apache.kafka.common.security.oauthbearer.OAuthBearerLoginModule required
                oauth.access.token.is.jwt="false"
                oauth.introspection.endpoint.uri="https://${SSO_HOST}/realms/myrealm/protocol/openid-connect/token/introspect"
                oauth.client.id="kafka-broker"
                oauth.client.secret="<client-secret-value>"
                oauth.valid.issuer.uri="https://${SSO_HOST}/realms/myrealm"
                oauth.username.claim="preferred_username"
                oauth.ssl.truststore.location="/opt/oauth-certs/tls.crt"
                oauth.ssl.truststore.type="PEM";
    # ...            
----

In this configuration:

* The listener uses the `OAUTHBEARER` SASL mechanism.
* Tokens are validated by calling the OAuth 2.0 introspection endpoint for each new client connection.
* The broker authenticates to the protected introspection endpoint using a client ID and client secret configured in the JAAS module.
* The JAAS login module and callback handler perform token validation and map the `preferred_username` value from the introspection endpoint response to a Kafka principal.
* The truststore used for TLS connections to the authorization server is specified by `oauth.ssl.truststore.location` and `oauth.ssl.truststore.type`.
* The `oauth.access.token.is.jwt="false"` setting ensures that the broker does not attempt to interpret access tokens as JWTs (for example, if debug logging is enabled).

NOTE: In production deployments, store the client secret securely, such as in a `Secret`, and inject it through an environment variable or other secure mechanism.
For more information, see xref:assembly-loading-config-with-providers-{context}[Loading configuration values from external sources].

=== Authenticating brokers to protected authorization-server endpoints

Some authorization servers expose the JWKS endpoint publicly but require authentication when accessing protected endpoints, such as the introspection endpoint.

When the broker accesses a protected endpoint, it must authenticate to the authorization server.

To configure HTTP Basic authentication, set the following properties:

* `oauth.client.id`
* `oauth.client.secret`

To configure HTTP Bearer authentication, set one of the following properties:

* `oauth.server.bearer.token.location` to specify the file path that contains the bearer token.
* `oauth.server.bearer.token` to specify the bearer token in clear text.

NOTE: In production environments, avoid storing credentials or bearer tokens in clear text. 
Use a secure mechanism to provide these values to the broker.