From b7a0ee0c7fba67fdb6e77025a981a33d04776243 Mon Sep 17 00:00:00 2001 From: PaulRMellor <47596553+PaulRMellor@users.noreply.github.com> Date: Tue, 17 Sep 2024 10:40:43 +0100 Subject: [PATCH] docs(keycloak): updates from review by keycloak dev (#10581) Signed-off-by: prmellor --- .../con-kafka-keycloak-authz-models.adoc | 32 ++++++------------- ...eycloak-authz-services-to-kafka-model.adoc | 1 + ...-oauth-authorization-keycloak-example.adoc | 28 ++++++++-------- documentation/shared/attributes.adoc | 1 + 4 files changed, 25 insertions(+), 37 deletions(-) diff --git a/documentation/modules/oauth/con-kafka-keycloak-authz-models.adoc b/documentation/modules/oauth/con-kafka-keycloak-authz-models.adoc index 527bacab043..9d30a4c5ba0 100644 --- a/documentation/modules/oauth/con-kafka-keycloak-authz-models.adoc +++ b/documentation/modules/oauth/con-kafka-keycloak-authz-models.adoc @@ -2,16 +2,10 @@ = Kafka and Keycloak authorization models [role="_abstract"] -Kafka and Keycloak Authorization Services use different authorization models. - -* Kafka's authorization model uses _resource types_ and _operations_ to describe ACLs for the _user_ -* The Keycloak Authorization Services model has four concepts for defining and granting permissions: -** _resources_ -** _authorization scopes_ -** _policies_ -** _permissions_ +Kafka and Keycloak use different authorization models. .Kafka authorization model +Kafka's authorization model uses _resource types_ and _operations_ to describe ACLs for a user. When a Kafka client performs an action on a broker, the broker uses the configured `KeycloakAuthorizer` to check the client's permissions, based on the action and resource type. Each resource type has a set of available permissions for operations. @@ -19,21 +13,13 @@ For example, the `Topic` resource type has `Create` and `Write` permissions amon Refer to the https://kafka.apache.org/documentation/#security_authz_primitives[Kafka authorization model] in the Kafka documentation for the full list of resources and permissions. -.Keycloak Authorization Services model - -The Keycloak Authorization Services model defines authorized actions. - -Resources:: Resources are matched with permitted actions. -A resource might be an individual topic, for example, or all topics with names starting with the same prefix. -A resource definition is associated with a set of available authorization scopes, which represent a set of all actions available on the resource. -Often, only a subset of these actions is actually permitted. +.Keycloak authorization model -Authorization scopes:: An authorization scope is a set of all the available actions on a specific resource definition. -When you define a new resource, you add scopes from the set of all scopes. +Keycloak's authorization services model has four concepts for defining and granting permissions: -Policies:: A policy is an authorization rule that uses criteria to match against a list of accounts. -Policies can match: -* _Service accounts_ based on client ID or roles -* _User accounts_ based on username, groups, or roles. +* Resources +* Scopes +* Policies +* Permissions -Permissions:: A permission grants a subset of authorization scopes on a specific resource definition to a set of users. +For information on these concepts, see the guide to {keycloak-authorization-services}. diff --git a/documentation/modules/oauth/con-mapping-keycloak-authz-services-to-kafka-model.adoc b/documentation/modules/oauth/con-mapping-keycloak-authz-services-to-kafka-model.adoc index e21d3864347..48694a7b208 100644 --- a/documentation/modules/oauth/con-mapping-keycloak-authz-services-to-kafka-model.adoc +++ b/documentation/modules/oauth/con-mapping-keycloak-authz-services-to-kafka-model.adoc @@ -17,6 +17,7 @@ However, you can also use different OAuth client ids (for example, `my-cluster-k ==== The `kafka` client definition must have the *Authorization Enabled* option enabled in the Keycloak Admin Console. +For information on enabling authorization services, see the guide to {keycloak-authorization-services}. 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. diff --git a/documentation/modules/oauth/proc-oauth-authorization-keycloak-example.adoc b/documentation/modules/oauth/proc-oauth-authorization-keycloak-example.adoc index 3457daca9bd..45412d3d07d 100644 --- a/documentation/modules/oauth/proc-oauth-authorization-keycloak-example.adoc +++ b/documentation/modules/oauth/proc-oauth-authorization-keycloak-example.adoc @@ -116,24 +116,24 @@ An affirmative policy means that at least one policy must be satisfied for a cli . In the Keycloak Admin Console, go to *Groups*, *Users*, *Roles* and *Clients* to view the realm configuration. + -Groups:: `Groups` are used to create user groups and set user permissions. Groups are sets of users with a name assigned. They are used to compartmentalize users into geographical, organizational or departmental units. -Groups can be linked to an LDAP identity provider. You can make a user a member of a group through a custom LDAP server admin user interface, for example, to grant permissions on Kafka resources. +Groups:: `Groups` organize users and set permissions. +Groups can be linked to an LDAP identity provider and used to compartmentalize users, such as by region or department. +Users can be added to groups through a custom LDAP interface to manage permissions for Kafka resources. +For more information on using KeyCloak's LDAP provider, see the the guide to {keycloak-admin-guide}. -Users:: `Users` are used to create users. For this example, `alice` and `bob` are defined. `alice` is a member of the `ClusterManager` group and `bob` is a member of `ClusterManager-my-cluster` group. -Users can be stored in an LDAP identity provider. +Users:: `Users` define individual users. +In this example, `alice` (in the `ClusterManager` group) and `bob` (in `ClusterManager-my-cluster`) are created. +Users can also be stored in an LDAP identity provider. -Roles:: `Roles` mark users or clients as having certain permissions. -Roles are a concept analogous to groups. They are usually used to _tag_ users with organizational roles and have the requisite permissions. -Roles cannot be stored in an LDAP identity provider. -If LDAP is a requirement, you can use groups instead, and add Keycloak roles to the groups so that when users are assigned a group they also get a corresponding role. +Roles:: `Roles` assign specific permissions to users or clients. +Roles function like tags to give users certain rights. +While roles cannot be stored in LDAP, you can add Keycloak roles to groups to combine both roles and permissions. -Clients:: `Clients` can have specific configurations. For this example, `kafka`, `kafka-cli`, `team-a-client`, and `team-b-client` clients are configured. +Clients:: `Clients` define configurations for Kafka interactions. + -* The `kafka` client is used by Kafka brokers to perform the necessary OAuth 2.0 communication for access token validation. -This client also contains the authorization services resource definitions, policies, and authorization scopes used to perform authorization on the Kafka brokers. -The authorization configuration is defined in the `kafka` client from the *Authorization* tab, which becomes visible when *Authorization Enabled* is switched on from the *Settings* tab. -* The `kafka-cli` client is a public client that is used by the Kafka command line tools when authenticating with username and password to obtain an access token or a refresh token. -* The `team-a-client` and `team-b-client` clients are confidential clients representing services with partial access to certain Kafka topics. +* The `kafka` client handles OAuth 2.0 token validation for brokers and contains authorization policies (which require authorization to be enabled). +* The `kafka-cli` client is used by command line tools to obtain access or refresh tokens. +* `team-a-client` and `team-b-client` represent services with partial access to specific Kafka topics. . In the Keycloak Admin Console, go to *Authorization* > *Permissions* to see the granted permissions that use the resources and policies defined for the realm. + diff --git a/documentation/shared/attributes.adoc b/documentation/shared/attributes.adoc index 576f23a61ba..15fa0797de3 100644 --- a/documentation/shared/attributes.adoc +++ b/documentation/shared/attributes.adoc @@ -57,6 +57,7 @@ :keycloak-server-doc: link:https://www.keycloak.org/documentation.html[Keycloak documentation^] :keycloak-server-install-doc: link:https://www.keycloak.org/operator/installation[Installing the Keycloak Operator^] :keycloak-authorization-services: link:https://www.keycloak.org/docs/latest/authorization_services/index.html[Keycloak Authorization Services^] +:keycloak-admin-guide: link:https://www.keycloak.org/docs/latest/authorization_services/index.html[Keycloak Server Administration^] :OAuthVersion: 0.15.0 :oauth-demo-keycloak: link:https://github.com/strimzi/strimzi-kafka-oauth/tree/{OAuthVersion}/examples[Using Keycloak as the OAuth 2.0 authorization server^] :oauth-demo-hydra: link:https://github.com/strimzi/strimzi-kafka-oauth/tree/{OAuthVersion}/examples/docker#running-with-hydra-using-ssl-and-opaque-tokens[Using Hydra as the OAuth 2.0 authorization server^]