Enable OAuth2/OIDC support for Apache Kafka® REST proxy
Secure your Apache Kafka® resources by integrating OAuth 2.0/OpenID Connect (OIDC) with the Karapace REST proxy and enabling REST proxy authorization. This setup ensures that only authorized individuals can manage Apache Kafka resources through both token-based authentication and access control rules.
OAuth2/OIDC token handling
Karapace processes the JSON Web Token (JWT) obtained from the Authorization HTTP header, specifically when employing the Bearer authentication scheme. This allows OAuth2/OIDC credentials to be supplied directly to the REST proxy, which uses the provided token to authorize requests to Apache Kafka. When a Bearer token is presented, Kafka clients configured by Karapace use the SASL OAUTHBEARER mechanism to send the JWT for validation.
Authorization enforcement
In the underlying Aiven for Apache Kafka® service, the default mechanism
for authorization, uses the sub
claim from the JWT as the username.
This username is then verified against the configured Access Control
Lists (ACLs) to authorize user operations on Apache Kafka resources.
While the sub
claim is the default identifier, this setting is
configurable. You can specify a different JWT claim for authentication
by adjusting the kafka.sasl_oauthbearer_sub_claim_name
parameter. For
more information on configuring this, see
Enable OAuth2/OIDC via Aiven Console.
To authenticate and authorize a user in Aiven for Apache Kafka, you need a service user and an ACL entry that describes the permissions. The JWT claim value used for authentication should explicitly match the service user in the system. This service user needs to be associated with an ACL entry that outlines their permissions, ensuring that the identity of the user making the request aligns with both the service user and the ACL entry.
Managing token expiry
With OAuth2/OIDC enabled, Karapace manages Apache Kafka client connections for security and performance. It automatically cleans up idle clients and those with tokens nearing expiration, typically on a 5-minute cycle. This cleanup prevents unauthorized access with expired tokens and clears idle connections.
Before your token expires, remove any linked consumers and producers to avoid security issues and service interruptions. After removal, refresh your OAuth2 JWT tokens and reconnect with the new tokens.
Configure OAuth2/OIDC authentication
To establish OAuth2/OIDC authentication for the Karapace REST proxy, complete the following prerequisites and configuration steps:
Prerequisites
- Aiven for Apache Kafka® service running with OAuth2/OIDC enabled.
- Karapace schema registry and REST APIs enabled.
- Ensure access to an OIDC-compliant provider, such as Auth0, Okta, Google Identity Platform, or Azure.
Configuration steps
- Aiven Console
- Aiven CLI
- In the Aiven Console, select your project and choose your Aiven for Apache Kafka® service.
- Click Service settings.
- Go to Advanced configuration and click Configure.
- In the Advanced configuration window, click Add configuration options.
- Find the
kafka_rest_authorization
parameter and set it toEnabled
. - Click Save configurations.
To enable REST proxy authorization, use the following command in the
Aiven CLI, replacing SERVICE_NAME
with your actual service name:
avn service update -c kafka_rest_authorization=true SERVICE_NAME
Disable REST proxy authorization, use:
avn service update -c kafka_rest_authorization=false SERVICE_NAME
Enabling Apache Kafka REST proxy authorization can disrupt access for users if the Kafka access control rules have not been configured properly. For more information, see Enable Apache Kafka® REST proxy authorization.