[id="con-mapping-keycloak-authz-services-to-kafka-model_{context}"]
= Mapping authorization models

[role="_abstract"]
The Kafka authorization model is used as a basis for defining the Keycloak roles and resources that control access to Kafka.

To grant Kafka permissions to user accounts or service accounts, you first create an _OAuth client specification_ in Keycloak for the Kafka cluster.
You then specify Keycloak Authorization Services rules on the client.
Typically, the client ID of the OAuth client that represents the Kafka cluster is `kafka`.
The xref:proc-oauth-authorization-keycloak-example_str[example configuration files] provided with Strimzi use `kafka` as the OAuth client id.

[NOTE]
====
If you have multiple Kafka clusters, you can use a single OAuth client (`kafka`) for all of them.
This gives you a single, unified space in which to define and manage authorization rules.
However, you can also use different OAuth client ids (for example, `my-cluster-kafka` or `cluster-dev-kafka`) and define authorization rules for each cluster within each client configuration.
====

The `kafka` client definition must have the *Authorization Enabled* option enabled in the Keycloak Admin Console.

All permissions exist within the scope of the `kafka` client. 
If you have different Kafka clusters configured with different OAuth client IDs, they each need a separate set of permissions even though they're part of the same Keycloak realm.

When the Kafka client uses OAUTHBEARER authentication, the Keycloak authorizer (`KeycloakAuthorizer`) uses the access token of the current session to retrieve a list of grants from the Keycloak server.
To grant permissions, the authorizer evaluates the grants list (received and cached) from Keycloak Authorization Services based on the access token owner's policies and permissions.

.Uploading authorization scopes for Kafka permissions

An initial Keycloak configuration usually involves uploading authorization scopes to create a list of all possible actions that can be performed on each Kafka resource type.
This step is performed once only, before defining any permissions.
You can add authorization scopes manually instead of uploading them.

Authorization scopes should contain the following Kafka permissions regardless of the resource type:

* `Create`
* `Write`
* `Read`
* `Delete`
* `Describe`
* `Alter`
* `DescribeConfigs`
* `AlterConfigs`
* `ClusterAction`
* `IdempotentWrite`

If you're certain you won't need a permission (for example, `IdempotentWrite`), you can omit it from the list of authorization scopes.
However, that permission won't be available to target on Kafka resources.

[NOTE]
====
The `All` permission is not supported.
====

.Resource patterns for permissions checks

Resource patterns are used for pattern matching against the targeted resources when performing permission checks.
The general pattern format is `<resource_type>:<pattern_name>`.

The resource types mirror the Kafka authorization model.
The pattern allows for two matching options:

* Exact matching (when the pattern does not end with `*`)
* Prefix matching (when the pattern ends with `*`)

.Example patterns for resources
[source]
----
Topic:my-topic
Topic:orders-*
Group:orders-*
Cluster:*
----

Additionally, the general pattern format can be prefixed by `kafka-cluster:<cluster_name>` followed by a comma, where `<cluster_name>` refers to the `metadata.name` in the Kafka custom resource.

.Example patterns for resources with cluster prefix
[source]
----
kafka-cluster:my-cluster,Topic:*
kafka-cluster:*,Group:b_*
----

When the `kafka-cluster` prefix is missing, it is assumed to be `kafka-cluster:*`.

When defining a resource, you can associate it with a list of possible authorization scopes which are relevant to the resource.
Set whatever actions make sense for the targeted resource type.

Though you may add any authorization scope to any resource, only the scopes supported by the resource type are considered for access control.

.Policies for applying access permission

Policies are used to target permissions to one or more user accounts or service accounts.
Targeting can refer to:

* Specific user or service accounts
* Realm roles or client roles
* User groups

A policy is given a unique name and can be reused to target multiple permissions to multiple resources.

.Permissions to grant access

Use fine-grained permissions to pull together the policies, resources, and authorization scopes that grant access to users.

The name of each permission should clearly define which permissions it grants to which users.
For example, `Dev Team B can read from topics starting with x`.
