Page History

...

This KIP proposes the addition of a single interface to the API and two additional configuration options to enable the client-side re-authentication and server-side expired-connection-kill features (both option value defaults to falsedefaults result in no functionality change, of course, so there is no change to existing behavior in the absence of an explicit opt-ins).  This KIP also proposes bumping the version number for the SASL_HANDSHAKE API and adjusting the wire format so that clients can determine if the broker they are connected to supports re-authentication and they can learn what maximum credential lifetime the broker supports (see below for details).  It also adds new metrics as described below.

...

The configuration option this KIP proposes to add to enable server-side expired-connection-kill is 'connections.max.reauth.ms' – it must be prefixed with listener prefix and SASL mechanism name in lower-case. For example, "sasl_ssl.oauthbearer.connections.max.reauth.ms=3600000".  The value defaults to 0.  When explicitly set to a non-zero value the server will reject any authentication or re-authentication attempt from a client that presents a bearer token whose lifetime exceeds the time at which the (re-)authentication occurs plus a number of milliseconds equal to the absolute value of the configured value (for example, the token lifetime must not exceed one hour past the time of (re-)authentication if the configured value is either -3600000 or +3600000).  When explicitly set to a positive number, in addition to the lifetime check, the server will disconnect any connection that does not re-authenticate and subsequently uses the connection for any purpose other than re-authentication at any point beyond the expiration point.  For example, if the configured value is 3600000 and the remaining token lifetime at the time of authentication is 45 minutes, the server would kill the connection if it is not re-authenticated within 45 minutes and it is then actively used for anything other than re-authentication.  As a further example, if the configured value is 3600000 and the mechanism is not OAUTHBEARER (e.g. it is PLAIN, SCRAM-related, or GSSAPI) then the server would kill the connection as soon as it is used more than 1 hour after the time of (re-)authentication (assuming the mechanism does not support re-authentication, which it will not for these mechanisms when this KIP is first delivered – but it could be added at a later time as described below in "How To Support Re-Authentication for Other SASL Mechanisms").

We support The 'connections.max.reauth.ms' configuration option supports positive and negative values to facilitate migration (see ; typically the value will first be set to a negative value and then it will be converted to its absolute value to fully enable the feature once metrics indicate all clients are upgraded and re-authenticating (see Migration Plan for details).

Neither of the above configuration options will be dynamically changeable, so restarts will be required if the either value is to be changed.

From a behavior perspective on the client side (again, including the broker when it is acting as an inter-broker client), when the client-side re-authentication option is enabled and a private credential implements ExpiringCredential, the existing configuration options sasl.login.refresh.{window.factor, window.jitter, min.period.seconds, min.buffer.seconds} define when the org.apache.kafka.common.security.auth.Login implementation on the client must generate a new private credential (e.g. when it must retrieve a new bearer token).  The default configuration values result in a new credential being retrieved sometime between 75% and 85% of the current credential's lifetime (e.g. sometime between 45 and 51 minutes after a token with an hour lifetime is initially retrieved).  At that time, when the new credential is retrieved, every connection that authenticated with the old credential and is connected to a broker that supports authentication will be told to re-authenticate.  Re-authentication will begin as soon as the connection is used.  If the re-authentication attempt fails then the connection will be closed by the broker; retries are not supported.  If re-authentication succeeds then any requests that queued up during re-authentication will subsequently be able to flow through, and eventually the connection will be told to re-authenticate again, etc.

...