# Use the AuthenticationHandler Class for Multi-Protocol Authentication in Confluent Platform Starting with Confluent Platform 7.7, a new handler class, `AuthenticationHandler`, is available only for REST-based services, including Schema Registry, Kafka REST, and Connect. The `AuthenticationHandler` handler class is designed to accept: - Identity provider (IdP) OAuth tokens - Confluent OAuth tokens provisioned by MDS - HTTP Basic Authentication - HTTP Basic Authentication using LDAP usernames and passwords - Mutual TLS (mTLS) certificates By accepting multiple authentication mechanisms, the `AuthenticationHandler` handler enables REST-based services in Confluent Platform to: - Upgrade from existing non-OAuth authentication mechanisms to support OAuth authentication without any downtime. - Simultaneously support multiple protocols based on your application requirements. The AuthenticationHandler can simultaneously handle requests from: - Existing legacy clients that use: - LDAP usernames and passwords - MDS tokens - New clients that use: - OAuth tokens - Mutual TLS (mTLS) certificates - Both OAuth tokens and mTLS certificates The AuthenticationHandler class can also provision metrics for each of the different authentication types. ## Example of multi-protocol authentication in Confluent Platform The diagram below illustrates an example of how the `AuthenticationHandler` class in Confluent Platform allows for flexible authentication for REST-based services by accepting multiple authentication mechanisms. Note the following: * The `AuthenticationHandler` class authenticates requests from multiple protocols, in this example, OAuth 2.0 and mTLS. * Application Client 1 and 2 use OAuth 2.0 to authenticate with the Confluent Platform services. The `AuthenticationHandler` class processes the OAuth tokens, verifies them, and provides access based on their validity, and the permissions granted. * Application Client 3 uses mTLS to authenticate with the Confluent Platform services. In this setup, both the client and server authenticate each other using certificates. The `AuthenticationHandler` class verifies the client certificates, ensuring both the client and server are trusted entities. ![The AuthenticationHandler class authenticates requests from multiple protocols.](images/authenticationhandler-multi-protocol.png) ## Use the AuthenticationHandler class You can use the AuthenticationHandler class for multi-protocol authentication in your Confluent Platform cluster by adding the following property: ```text rest.servlet.initializor.classes ``` ## Configuration examples Following are examples of how to configure the AuthenticationHandler class for supported authentication mechanisms. Adjust the property values according to your specific environment and requirements. ### Identity provider (IdP) OAuth tokens To configure the AuthenticationHandler for IdP OAuth tokens: ```properties rest.servlet.initializor.classes=io.confluent.common.security.jetty.initializer.AuthenticationHandler oauthbearer.jwks.endpoint.url=https://your-idp.com/.well-known/jwks.json oauthbearer.expected.issuer=https://your-idp.com oauthbearer.expected.audience=your-audience oauthbearer.sub.claim.name=sub oauthbearer.groups.claim.name=groups ``` ### Confluent OAuth tokens For Confluent OAuth tokens from Confluent Cloud: ```properties rest.servlet.initializor.classes=io.confluent.common.security.jetty.initializer.AuthenticationHandler oauthbearer.jwks.endpoint.url=https://confluent.cloud/.well-known/jwks.json oauthbearer.expected.issuer=https://confluent.cloud oauthbearer.expected.audience=your-confluent-cloud-audience oauthbearer.sub.claim.name=sub oauthbearer.groups.claim.name=groups ``` ### MDS tokens To configure the `AuthenticationHandler` class to accept both MDS-issued tokens and IdP-issued OAuth tokens, combine the `public.key.path` property with the `oauthbearer.*` properties. ```properties rest.servlet.initializor.classes=io.confluent.common.security.jetty.initializer.AuthenticationHandler oauthbearer.jwks.endpoint.url=https://your-idp.com/.well-known/jwks.json oauthbearer.expected.issuer=https://your-idp.com oauthbearer.expected.audience=your-audience public.key.path=/path/to/mds-pub.pem ``` * Combining `public.key.path` with the `oauthbearer.*` properties allows `AuthenticationHandler` to validate both MDS and OAuth tokens, rather than restricting authentication strictly to one token type. * `public.key.path` specifies the path to the public key used to verify MDS token signatures. * `oauthbearer.*` configures the handler to validate IdP-issued OAuth tokens alongside MDS tokens. This dual-token setup enables clients using MDS authentication and clients that have migrated to the IdP to operate side by side during a phased migration. For details on how MDS and IdP tokens interact, see [Metadata Service (MDS) as Token Issuer in Confluent Platform](../../../kafka/configure-mds/mds-token-issuer.md#mds-token-issuer). ### HTTP Basic Authentication To use HTTP Basic Authentication: ```properties rest.servlet.initializor.classes=io.confluent.common.security.jetty.initializer.AuthenticationHandler authentication.method=BASIC basic.auth.user.info=user1:password1,user2:password2 ``` ### HTTP Basic Authentication using LDAP usernames and passwords For HTTP Basic Authentication with LDAP: ```properties rest.servlet.initializor.classes=io.confluent.common.security.jetty.initializer.AuthenticationHandler authentication.method=BASIC basic.auth.ldap.url=ldap://your-ldap-server:389 basic.auth.ldap.user.base.dn=ou=users,dc=example,dc=com ``` ### mTLS To configure mTLS: ```properties rest.servlet.initializor.classes=io.confluent.common.security.jetty.initializer.AuthenticationHandler ssl.client.authentication=REQUIRED ssl.truststore.location=/path/to/truststore.jks ssl.truststore.password=truststore-password ssl.keystore.location=/path/to/keystore.jks ssl.keystore.password=keystore-password auth.ssl.principal.mapping.rules= ``` `auth.ssl.principal.mapping.rules` specifies the principal mapping rules applied to REST calls when the `AuthenticationHandler` class is in use. For rule syntax and examples, see [Use Principal Mapping in Confluent Platform](../mutual-tls/tls-principal-mapping.md#tls-principal-mapping). ## Monitoring authentication It’s useful to get the monitoring data of authentication requests, their success rates, and associated latencies. You can enable monitoring of authentication through the `AuthenticationHandler`. This class generates metrics for the different Confluent Platform authentication mechanisms, OAuth, mTLS, basic, and MDS over OAuth. To enable monitoring, set this property in the Confluent REST Proxy service: ```text rest.auth.jmx.enabled=true ``` You should begin to see metrics similar to the following: ```text Total successful auth requests Total unsuccessful auth requests Latency in successful auth request ( sampled ) Latency in un successful auth request (sampled ) Average latency of successful auth requests ( ms ) Max latency of successful auth requests (ms). 99 percentile of latency for successful auth requests (ms) 95 percentile of latency for successful auth requests (ms) ``` Confluent Platform uses JMX (Java Management Extensions) for exposing metrics from various services, including the Confluent REST Proxy. This allows you to monitor with Confluent Control Center or external tools like JConsole, Prometheus, and Grafana. For more information using these tools with Confluent Platform, see [Monitor Consumer Lag in Confluent Platform](../../../monitor/monitor-consumer-lag.md#consumer-lag).