Page History

package org.apache.kafka.common.security.oauthbearer;
 
/**
 * This class is responsible for refreshing logins for both Kafka client and
 * server when the credential is an OAuth 2 bearer token communicated over
 * SASL/OAUTHBEARER. An OAuth 2 bearer token has a limited lifetime, and an
 * instance of this class periodically refreshes it so that the client can
 * create new connections to brokers on an ongoing basis.
 * <p>
 * This class is set via the {@code sasl.login.class} client configuration
 * property or the {@code listener.name.sasl_ssl.oauthbearer.sasl.login.class}
 * broker configuration property.
 * <p>
 * The login callback handler seen by the {@link OAuthBearerLoginModule}
 * instance is set via the {@code sasl.login.callback.handler.class} client
 * configuration property or the
 * {@code listener.name.sasl_ssl.oauthbearer.sasl.login.callback.handler.class}
 * broker configuration property.
 * <p>
 * This class recognizes the following refresh-related configuration properties,
 * which must be set in the JAAS configuration:
 * <ul>
 * <li><b>clientRefreshWindowFactor</b> -- the background login refresh thread
 * will sleep until the specified window factor relative to the token's total
 * lifetime has been reached, at which time it will try to refresh the
 * credential. Legal values are between 0.5 (50%) and 1.0 (100%) inclusive; a
 * default value of 0.8 (80%) is used if a legal value is not specified.</li>
 * <li><b>clientRefreshWindowJitter</b> -- the maximum amount of random jitter
 * relative to the token's total lifetime that is added to the background login
 * refresh thread's sleep time. Legal values are between 0 and 0.25 (25%)
 * inclusive; a default value of 0.05 (5%) is used if a legal value is not
 * specified.</li>
 * <li><b>clientRefreshMinPeriodMillis<<li><b>clientRefreshMinPeriodSeconds</b> -- the desired minimum time to wait
 * before refreshing a token, in millisecondsseconds. Legal values are between 0 and
 * 900,000 (15
 * minutes); a default value of 60,000 (1 minute) is used if a legal
 * value is not
 * specified.</li>
 * <li><b>clientRefreshBufferSeconds</b> -- the amount of buffer time before
 * expiration to maintain when refreshing. If a refresh is scheduled to occur
 * closer to expiration than the number of seconds defined here then the refresh
 * will be moved up if possible so as to maintain the desired buffer. Legal
 * values are between 0 and 3,600 (1 hour); a default value of 120 (2 minutes)
 * is used if a legal value is not specified.</li>
 * </ul>
 * Note that SASL/OAUTHBEARER logins as managed by this class are only supported
 * when a single {@code LoginModule} implementing {@link OAuthBearerLoginModule}
 * is communicated to the code. This may be in a non-broker client client where
 * only 1 SASL mechanism can be declared; or it may be in an inter-broker
 * context where there is only one SASL mechanism defined for the cluster or
 * because the JAAS configuration is done via the dynamic functionality
 * introduced via <a href=
 * "https://cwiki.apache.org/confluence/display/KAFKA/KIP-226+-+Dynamic+Broker+Configuration">KIP-226</a>
 * that eliminates the mechanism-to-login-module ambiguity associated with
 * declaring multiple SASL mechanisms in a single broker JAAS configuration
 * file.
 *
 * @see OAuthBearerUnsecuredLoginCallbackHandler
 */
public class OAuthBearerRefreshingLogin implements Login {
    // etc...
}