// Module included in the following module:
//
// con-oauth-config.adoc

[id='proc-oauth-authorization-broker-config-{context}']
= Configuring {oauth} authorization support

This procedure describes how to configure Kafka brokers to use {oauth} authorization using {keycloak-server} Authorization Services.

.Before you begin
Consider the access you require or want to limit for certain users.
You can use a combination of {keycloak-server} _groups_, _roles_, _clients_, and _users_ to configure access in {keycloak-server}.

Typically, groups are used to match users based on organizational departments or geographical locations.
And roles are used to match users based on their function.

With {keycloak-server}, you can store users and groups in LDAP, whereas clients and roles cannot be stored this way.
Storage and access to user data may be a factor in how you choose to configure authorization policies.

NOTE: xref:ref-kafka-authorization-super-user-deployment-configuration-kafka[Super users] always have unconstrained access to a Kafka broker regardless of the authorization implemented on the Kafka broker.

.Prerequisites

* {ProductName} must be configured to use {oauth} with {keycloak-server} for xref:assembly-oauth-authentication_str[token-based authentication].
You use the same {keycloak-server} server endpoint when you set up authorization.
* You need to understand how to manage policies and permissions for {keycloak-server} Authorization Services, as described in the {keycloak-server-doc}.

.Procedure

. Access the {keycloak-server} Admin Console or use the {keycloak-server} Admin CLI to enable Authorization Services for the Kafka broker client you created when setting up {oauth} authentication.
. Use Authorization Services to define resources, authorization scopes, policies, and permissions for the client.
. Bind the permissions to users and clients by assigning them roles and groups.
. Configure the Kafka brokers to use {keycloak-server} authorization by updating the Kafka broker configuration (`Kafka.spec.kafka`) of your `Kafka` resource in an editor.
+
[source,shell]
----
kubectl edit kafka my-cluster
----

. Configure the Kafka broker `kafka` configuration to use `keycloak` authorization, and to be able to access the authorization server and Authorization Services.
+
For example:
+
[source,yaml,subs="+quotes,attributes"]
----
apiVersion: {KafkaApiVersion}
kind: Kafka
metadata:
  name: my-cluster
spec:
  kafka
  # ...
  authorization:
    type: *keycloak* <1>
    tokenEndpointUri: <__https://<auth-server-address>/auth/realms/external/protocol/openid-connect/token__> <2>
    clientId: kafka <3>
    delegateToKafkaAcls: false <4>
    disableTlsHostnameVerification: false <5>
    superUsers: <6>
      - CN=fred
      - sam
      - CN=edward
    tlsTrustedCertificates: <7>
    - secretName: oauth-server-cert
      certificate: ca.crt
  #...
----
<1> Type `keycloak` enables {keycloak-server} authorization.
<2> URI of the {keycloak-server} token endpoint. For production, always use HTTPs.
<3> The client ID of the {oauth} client definition in {keycloak-server} that has Authorization Services enabled. Typically, `kafka` is used as the ID.
<4> (Optional) Delegate authorization to Kafka `SimpleACLAuthorizer` if access is denied by {keycloak-server} Authorization Services policies.
The default is `false`.
<5> (Optional) Disable TLS hostname verification. Default is `false`.
<6> (Optional) Designated xref:ref-kafka-authorization-super-user-deployment-configuration-kafka[super users].
<7> (Optional) Trusted certificates for TLS connection to the authorization server.

. Save and exit the editor, then wait for rolling updates to complete.

. Check the update in the logs or by watching the pod state transitions:
+
[source,shell,subs="+quotes,attributes"]
----
kubectl logs -f ${POD_NAME} -c kafka
kubectl get po -w
----
+
The rolling update configures the brokers to use {oauth} authorization.

. Verify the configured permissions by accessing Kafka brokers as clients or  users with specific roles, making sure they have the necessary access, or do not have the access they are not supposed to have.
