io.strimzi.kafka.oauth.server

Class JaasServerOauthValidatorCallbackHandler

java.lang.Object

io.strimzi.kafka.oauth.server.JaasServerOauthValidatorCallbackHandler

All Implemented Interfaces:

javax.security.auth.callback.CallbackHandler, org.apache.kafka.common.security.auth.AuthenticateCallbackHandler

public class JaasServerOauthValidatorCallbackHandler
extends java.lang.Object
implements org.apache.kafka.common.security.auth.AuthenticateCallbackHandler

This CallbackHandler implements the OAuth2 support. It is designed for use with the org.apache.kafka.common.security.oauthbearer.OAuthBearerLoginModule which provides SASL/OAUTHBEARER authentication support to Kafka brokers. With this CallbackHandler installed, the client authenticates with SASL/OAUTHBEARER mechanism, authenticating with an access token which this CallbackHandler validates, and either accepts or rejects.

This CallbackHandler supports two different validation mechanism:

• Fast local signature check by using JWKS certificates to validate the signature on the token
• Introspection endpoint based mechanism where token is sent to the authorization server for validation

To install this CallbackHandler in your Kafka listener, specify the following in your 'server.properties':

     # Declare a listener
     listeners=CLIENT://kafka:9092

     # Specify whether the TCP connection is unsecured or protected with TLS
     #listener.security.protocol.map=CLIENT:SASL_PLAINTEXT
     listener.security.protocol.map=CLIENT:SASL_SSL

     # Enable SASL/OAUTHBEARER authentication mechanism on your listener in addition to any others
     #sasl.enabled.mechanisms: PLAIN,OAUTHBEARER
     sasl.enabled.mechanisms: OAUTHBEARER

     # Install the SASL/OAUTHBEARER LoginModule using per-listener sasl.jaas.config
     listener.name.client.oauthbearer.sasl.jaas.config=org.apache.kafka.common.security.oauthbearer.OAuthBearerLoginModule required \
         oauth.valid.issuer.uri="https://java-server" \
         oauth.jwks.endpoint.uri="http://java-server/certs" \
         oauth.username.claim="preferred_username";

     # Install this CallbackHandler to provide custom handling of authentication
     listener.name.client.oauthbearer.sasl.server.callback.handler.class=io.strimzi.kafka.oauth.server.JaasServerOauthValidatorCallbackHandler
 

There is additional sasl.jaas.config configuration that may need to be specified in order for this CallbackHandler to work with your authorization server.

Note: The following configuration keys can be specified as parameters to sasl.jaas.config in Kafka `server.properties` file, or as ENV vars in which case an all-uppercase key name is also attempted with '.' replaced by '_' (e.g. OAUTH_VALID_ISSUER_URI). They can also be specified as system properties. The priority is in reverse - system property overrides the ENV var, which overrides `server.properties`. When not specified as the parameters to sasl.jaas.config, the configuration keys will apply to all listeners.

Configuring the fast local token validation

Required sasl.jaas.config configuration:

• oauth.jwks.endpoint.uri A URL of the authorization server endpoint where certificates are available in JWKS format
  The certificates are used to check JWT token signatures.
• oauth.valid.issuer.uri A URL of the authorization server's token endpoint.
  The token endpoint is used to authenticate to authorization server with the clientId and the secret received over username and password parameters.

Optional sasl.jaas.config configuration:

• oauth.jwks.refresh.seconds Configures how often the JWKS certificates are refreshed.
  The refresh interval has to be at least 60 seconds shorter then the expiry interval specified in oauth.jwks.expiry.seconds. Default value is 300.
• oauth.jwks.expiry.seconds Configures how often the JWKS certificates are considered valid.
  The expiry interval has to be at least 60 seconds longer then the refresh interval specified in oauth.jwks.refresh.seconds. Default value is 360.
• oauth.jwks.refresh.min.pause.seconds The minimum pause between two consecutive refreshes.
  When an unknown signing key is encountered the refresh is scheduled immediately, but will always wait for this minimum pause. Default value is 1.

Configuring the introspection endpoint based token validation

Required sasl.jaas.config configuration:

• oauth.introspection.endpoint.uri A URL of the token introspection endpoint to which token validation is delegates.
  It can be used to validate opaque non-JWT tokens which can't be checked using fast local token validation.
• oauth.client.id OAuth client id which the Kafka broker uses to authenticate against the authorization server to use the introspection endpoint.
• oauth.client.secret The OAuth client secret which the Kafka broker uses to authenticate to the authorization server and use the introspection endpoint.

Optional sasl.jaas.config configuration:

• oauth.userinfo.endpoint.uri A URL of the token introspection endpoint which can be used to validate opaque non-JWT tokens.
  
• oauth.valid.token.type If set, the token type returned by the introspection endpoint has to match the configured value.
  

Common optional sasl.jaas.config configuration:

• oauth.username.claim The attribute key that should be used to extract the user id. If not set `sub` attribute is used.
  The attribute key refers to the JWT token claim when fast local validation is used, or to attribute in the response by introspection endpoint when introspection based validation is used. It has no default value.
• oauth.fallback.username.claim The fallback username claim to be used for the user id if the attribute key specified by `oauth.username.claim`
  is not present. This is useful when `client_credentials` authentication only results in the client id being provided in another claim.
• oauth.fallback.username.prefix The prefix to use with the value of oauth.fallback.username.claim to construct the user id.
  This only takes effect if oauth.fallback.username.claim is true, and the value is present for the claim. Mapping usernames and client ids into the same user id space is useful in preventing name collisions.
• oauth.check.issuer Enable or disable issuer checking.
  By default issuer is checked using the value configured by oauth.valid.issuer.uri. Default value is true
• oauth.check.audience Enable or disable audience checking.
  Enabling audience check limits access only to tokens explicitly issued for access to your Kafka broker. If enabled, the oauth.client.id also has to be configured. Default value is false
• oauth.access.token.is.jwt Configure whether the access token is treated as JWT.
  This must be set to false if the authorization server returns opaque tokens. Default value is true.
• oauth.tokens.not.jwt Deprecated. Same as oauth.access.token.is.jwt with opposite meaning.
• oauth.check.access.token.type Configure whether the access token type check is performed or not.
  This should be set to false if the authorization server does not include typ claim in JWT token. Default value is true.
• oauth.validation.skip.type.check Deprecated. Same as oauth.check.access.token.type with opposite meaning.
• oauth.custom.claim.check The optional mechanism to validate the JWT token or the introspection endpoint response by using any claim or attribute with a JSONPath filter query that evaluates to true or false. If it evaluates to true the check passes, otherwise the token is rejected. See JsonPathFilterQuery.

TLS sasl.jaas.config configuration for TLS connectivity with the authorization server:

• oauth.ssl.truststore.location The location of the truststore file on the filesystem.
  If not present, oauth.ssl.truststore.location is used as a fallback configuration key to avoid unnecessary duplication when already present for the purpose of client authentication.
• oauth.ssl.truststore.password The password for the truststore.
  If not present, oauth.ssl.truststore.password is used as a fallback configuration key to avoid unnecessary duplication when already present for the purpose of client authentication.
• oauth.ssl.truststore.type The truststore type.
  If not present, oauth.ssl.truststore.type is used as a fallback configuration key to avoid unnecessary duplication when already present for the purpose of client authentication. If not set, the Java KeyStore default type is used.
• oauth.ssl.secure.random.implementation The random number generator implementation. See Java SDK documentation.
  If not present, oauth.ssl.secure.random.implementation is used as a fallback configuration key to avoid unnecessary duplication when already present for the purpose of client authentication. If not set, the Java platform SDK default is used.
• oauth.ssl.endpoint.identification.algorithm Specify how to perform hostname verification. If set to empty string the hostname verification is turned off.
  If not present, oauth.ssl.endpoint.identification.algorithm is used as a fallback configuration key to avoid unnecessary duplication when already present for the purpose of client authentication. If not set, the default value is HTTPS which enforces hostname verification for server certificates.

Constructor Summary

Constructors

Constructor and Description
JaasServerOauthValidatorCallbackHandler()

Method Summary

Modifier and Type	Method and Description
void	close()
void	configure(java.util.Map<java.lang.String,?> configs, java.lang.String saslMechanism, java.util.List<javax.security.auth.login.AppConfigurationEntry> jaasConfigEntries)
PrincipalExtractor	getPrincipalExtractor()
javax.net.ssl.SSLSocketFactory	getSocketFactory()
javax.net.ssl.HostnameVerifier	getVerifier()
void	handle(javax.security.auth.callback.Callback[] callbacks)
boolean	isJwt()

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

JaasServerOauthValidatorCallbackHandler

public JaasServerOauthValidatorCallbackHandler()

Method Detail

configure

public void configure(java.util.Map<java.lang.String,?> configs,
                      java.lang.String saslMechanism,
                      java.util.List<javax.security.auth.login.AppConfigurationEntry> jaasConfigEntries)

Specified by:

configure in interface org.apache.kafka.common.security.auth.AuthenticateCallbackHandler

close

public void close()

Specified by:

close in interface org.apache.kafka.common.security.auth.AuthenticateCallbackHandler

handle

public void handle(javax.security.auth.callback.Callback[] callbacks)
            throws javax.security.auth.callback.UnsupportedCallbackException

Specified by:

handle in interface javax.security.auth.callback.CallbackHandler

Throws:

javax.security.auth.callback.UnsupportedCallbackException

isJwt

public boolean isJwt()

getSocketFactory

public javax.net.ssl.SSLSocketFactory getSocketFactory()

getVerifier

public javax.net.ssl.HostnameVerifier getVerifier()

getPrincipalExtractor

public PrincipalExtractor getPrincipalExtractor()