:_mod-docs-content-type: CONCEPT

To configure OAuth client authentication, set the `type` property to `oauth`.

OAuth authentication can be configured using one of the following options:

* Client ID and secret
* Client ID and refresh token
* Access token
* Username and password
* TLS

.Client ID and secret
You can configure the address of your authorization server in the `tokenEndpointUri` property together with the client ID and client secret used in authentication.
The OAuth client will connect to the OAuth server, authenticate using the client ID and secret and get an access token which it will use to authenticate with the Kafka broker.
In the `clientSecret` property, specify a link to a `Secret` containing the client secret.

.Example client ID and client secret configuration
[source,yaml,subs=attributes+]
----
authentication:
  type: oauth
  tokenEndpointUri: https://<auth_server_address>/<path_to_token_endpoint>
  clientId: my-client-id
  clientSecret:
    secretName: my-client-oauth-secret
    key: client-secret
----

Optionally, `scope` and `audience` can be specified if needed. `grantType` can also be specified for custom client credentials implementations.

.Client ID and refresh token
You can configure the address of your OAuth server in the `tokenEndpointUri` property together with the OAuth client ID and refresh token.
The OAuth client will connect to the OAuth server, authenticate using the client ID and refresh token and get an access token which it will use to authenticate with the Kafka broker.
In the `refreshToken` property, specify a link to a `Secret` containing the refresh token.

.Example client ID and refresh token configuration
[source,yaml,subs=attributes+]
----
authentication:
  type: oauth
  tokenEndpointUri: https://<auth_server_address>/<path_to_token_endpoint>
  clientId: my-client-id
  refreshToken:
    secretName: my-refresh-token-secret
    key: refresh-token
----

.Access token
You can configure the access token used for authentication with the Kafka broker directly.
In this case, you do not specify the `tokenEndpointUri`.
In the `accessToken` property, specify a link to a `Secret` containing the access token.
Alternatively, use `accessTokenLocation` property, and specify a path to the token file.

.Example access token only configuration
[source,yaml,subs=attributes+]
----
authentication:
  type: oauth
  accessToken:
    secretName: my-access-token-secret
    key: access-token
----

.Example (service account) access token configuration specifying a mounted file
[source,yaml,subs=attributes+]
----
authentication:
  type: oauth
  accessTokenLocation: `/var/run/secrets/kubernetes.io/serviceaccount/token`
----

.Username and password
OAuth username and password configuration uses the OAuth _Resource Owner Password Grant_ mechanism. The mechanism is deprecated, and is only supported to enable integration in environments where client credentials (ID and secret) cannot be used. You might need to use user accounts if your access management system does not support another approach or user accounts are required for authentication.

A typical approach is to create a special user account in your authorization server that represents your client application. You then give the account a long randomly generated password and a very limited set of permissions. For example, the account can only connect to your Kafka cluster, but is not allowed to use any other services or login to the user interface.

Consider using a refresh token mechanism first.

You can configure the address of your authorization server in the `tokenEndpointUri` property together with the client ID, username and the password used in authentication.
The OAuth client will connect to the OAuth server, authenticate using the username, the password, the client ID, and optionally even the client secret to obtain an access token which it will use to authenticate with the Kafka broker.

In the `passwordSecret` property, specify a link to a `Secret` containing the password.

Normally, you also have to configure a `clientId` using a public OAuth client. 
If you are using a confidential OAuth client, you also have to configure a `clientSecret`.

.Example username and password configuration with a public client
[source,yaml,subs=attributes+]
----
authentication:
  type: oauth
  tokenEndpointUri: https://<auth_server_address>/<path_to_token_endpoint>
  username: my-username
  passwordSecret:
    secretName: my-password-secret-name
    password: my-password-field-name
  clientId: my-public-client-id
----

.Example username and password configuration with a confidential client
[source,yaml,subs=attributes+]
----
authentication:
  type: oauth
  tokenEndpointUri: https://<auth_server_address>/<path_to_token_endpoint>
  username: my-username
  passwordSecret:
    secretName: my-password-secret-name
    password: my-password-field-name
  clientId: my-confidential-client-id
  clientSecret:
    secretName: my-confidential-client-oauth-secret
    key: client-secret
----

Optionally, `scope` and `audience` can be specified if needed.

.TLS
Accessing the OAuth server using the HTTPS protocol does not require any additional configuration as long as the TLS certificates used by it are signed by a trusted certification authority and its hostname is listed in the certificate.

If your OAuth server uses self-signed certificates or certificates signed by an untrusted certification authority, use the `tlsTrustedCertificates` property to specify the secrets containing them. 
The certificates must be in X.509 format.

.Example configuration specifying TLS certificates
[source,yaml,subs=attributes+]
----
authentication:
  type: oauth
  tokenEndpointUri: https://<auth_server_address>/<path_to_token_endpoint>
  clientId: my-client-id
  refreshToken:
    secretName: my-refresh-token-secret
    key: refresh-token
  tlsTrustedCertificates:
    - secretName: oauth-server-ca
      pattern: "*.crt"
----

The OAuth client will by default verify that the hostname of your OAuth server matches either the certificate subject or one of the alternative DNS names.
If it is not required, you can disable the hostname verification.

.Example configuration to disable TLS hostname verification
[source,yaml,subs=attributes+]
----
authentication:
  type: oauth
  tokenEndpointUri: https://<auth_server_address>/<path_to_token_endpoint>
  clientId: my-client-id
  refreshToken:
    secretName: my-refresh-token-secret
    key: refresh-token
  disableTlsHostnameVerification: true
----
