Content for OAuth2/OIDC support for Kafka REST proxy

_toc.yml

@@ -587,6 +587,7 @@ entries:
             - file: docs/products/kafka/karapace/howto/enable-kafka-rest-proxy-authorization
             - file: docs/products/kafka/karapace/howto/manage-schema-registry-authorization
             - file: docs/products/kafka/karapace/howto/manage-kafka-rest-proxy-authorization
+            - file: docs/products/kafka/karapace/howto/enable-oauth-oidc-kafka-rest-proxy
 
   # -------- FLINK --------
   - file: docs/products/flink

docs/products/kafka/howto/enable-oidc.rst

@@ -90,3 +90,7 @@ To enable OAuth2/OIDC authentication for your Aiven for Apache Kafka service usi
 For detailed explanations on the OIDC parameters, refer to the :ref:`console-authentication` section above.
 
 
+
+See also
+--------
+- Enable OAuth2/OIDC support for Apache Kafka® REST proxy 

docs/products/kafka/karapace/howto/enable-oauth-oidc-kafka-rest-proxy.rst

@@ -0,0 +1,63 @@
+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
+----------------------------
+
+The underlying Aiven for Apache Kafka® service uses the ``sub`` claim from the JWT as the username, checking it against configured Access Control Lists (ACLs) to authorize operations on Kafka resources.
+
+
+Managing token expiry
+------------------------------
+
+With OAuth2/OIDC enabled, Karapace manages 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.
+
+.. note:: 
+    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
+```````````````
+* :doc:`Aiven for Apache Kafka® </docs/products/kafka/getting-started>` service running with :doc:`OAuth2/OIDC enabled </docs/products/kafka/howto/enable-oidc>`.
+* :doc:`Karapace schema registry and REST APIs enabled </docs/products/kafka/karapace/howto/enable-karapace>`.
+* Ensure access to an OIDC-compliant provider, such as Auth0, Okta, Google Identity Platform, or Azure.
+
+Configuration via Aiven Console
+```````````````````````````````````
+1. In `Aiven Console <https://console.aiven.io/>`_, select your project and then choose your Aiven for Apache Kafka® service.
+2. On the **Overview** page, scroll down to **Advanced configuration** and select **Configure**.
+3. In the **Advanced configuration** screen, select **Add configuration options**.
+4. Look for  ``kafka_rest_authorization`` parameter and set it to ``True``. 
+
+Configuration via Aiven CLI
+`````````````````````````````
+
+To enable REST proxy authorization, use the following command in the Aiven CLI, replacing ``SERVICE_NAME`` with your actual service name:
+
+.. code:: 
+
+    avn service update -c kafka_rest_authorization=true SERVICE_NAME
+
+Disable REST proxy authorization, use: 
+
+.. code:: 
+
+    avn service update -c kafka_rest_authorization=false SERVICE_NAME
+
+.. warning:: 
+    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 :doc:`Manage Apache Kafka® REST proxy authorization <../howto/manage-kafka-rest-proxy-authorization>`.
+
+