// Module included in the following assemblies:
//
// assembly-oauth.adoc

[id='con-oauth-authentication-client-options-{context}']
= {oauth} client authentication flow

In this section, we explain and visualize the communication flow between Kafka client, Kafka broker, and authorization server during Kafka session initiation.
The flow depends on the client and server configuration.

When a Kafka client sends an access token as credentials to a Kafka broker, the token needs to be validated.

Depending on the authorization server used, and the configuration options available, you may prefer to use:

* Fast local token validation based on JWT signature checking and local token introspection, without contacting the authorization server
* An {oauth} introspection endpoint provided by the authorization server

Using fast local token validation requires the authorization server to provide a JWKS endpoint with public certificates that are used to validate signatures on the tokens.

Another option is to use an {oauth} introspection endpoint on the authorization server.
Each time a new Kafka broker connection is established, the broker passes the access token received from the client to the authorization server, and checks the response to confirm whether or not the token is valid.

Kafka client credentials can also be configured for:

* Direct local access using a previously generated long-lived access token
* Contact with the authorization server for a new access token to be issued

NOTE: An authorization server might only allow the use of opaque access tokens, which means that local token validation is not possible.

== Example client authentication flows

Here you can see the communication flows, for different configurations of Kafka clients and brokers, during Kafka session authentication.

* xref:oauth-introspection-endpoint-{context}[Client using client ID and secret, with broker delegating validation to authorization server]
* xref:oauth-jwt-{context}[Client using client ID and secret, with broker performing fast local token validation]
* xref:oauth-token-endpoint-{context}[Client using long-lived access token, with broker delegating validation to authorization server]
* xref:oauth-token-jwt-{context}[Client using long-lived access token, with broker performing fast local validation]

[id='oauth-introspection-endpoint-{context}']
.Client using client ID and secret, with broker delegating validation to authorization server

image:oauth-introspection-endpoint.png[Client using client ID and secret with broker delegating validation to authorization server]

. Kafka client requests access token from authorization server, using client ID and secret, and optionally a refresh token.
. Authorization server generates a new access token.
. Kafka client authenticates with the Kafka broker using the _SASL OAUTHBEARER_ mechanism to pass the access token.
. Kafka broker validates the access token by calling a token introspection endpoint on authorization server, using its own client ID and secret.
. Kafka client session is established if the token is valid.

[id='oauth-jwt-{context}']
.Client using client ID and secret, with broker performing fast local token validation

image:oauth-jwt-signature.png[Client using client ID and secret with broker performing fast local token validation]

. Kafka client authenticates with authorization server from the token endpoint, using a client ID and secret, and optionally a refresh token.
. Authorization server generates a new access token.
. Kafka client authenticates with the Kafka broker using the _SASL OAUTHBEARER_ mechanism to pass the access token.
. Kafka broker validates the access token locally using a JWT token signature check, and local token introspection.

[id='oauth-token-endpoint-{context}']
.Client using long-lived access token, with broker delegating validation to authorization server

image:oauth-introspection-endpoint-long-token.png[Client using long-lived access token with broker delegating validation to authorization server]

. Kafka client authenticates with the Kafka broker using the _SASL OAUTHBEARER_ mechanism to pass the long-lived access token.
. Kafka broker validates the access token by calling a token introspection endpoint on authorization server, using its own client ID and secret.
. Kafka client session is established if the token is valid.

[id='oauth-token-jwt-{context}']
.Client using long-lived access token, with broker performing fast local validation

image:oauth-jwt-signature-token.png[Client using long-lived access token with broker performing fast local validation]

. Kafka client authenticates with the Kafka broker using the _SASL OAUTHBEARER_ mechanism to pass the long-lived access token.
. Kafka broker validates the access token locally using JWT token signature check, and local token introspection.

WARNING: Fast local JWT token signature validation is suitable only for short-lived tokens as there is no check with the authorization server if a token has been revoked.
Token expiration is written into the token, but revocation can happen at any time, so cannot be accounted for without contacting the authorization server.
Any issued token would be considered valid until it expires.
