Keycloak OpenFGA Custom Event Listener

Here is a Custom Event Listener Extension known as Service Provider Interfaces (SPI) which helps to integrate Keycloak and OpenFGA. OpenFGA is an open source solution for Fine-Grained Authorization that applies the concept of ReBAC (created by the Auth0 inspired by Zanzibar).
The SPI implements these steps:

listens to the following Keycloak events based on his own Identity, Role and Group model (e.g., User Role Assignment, Role to Role Assignment, etc)
converts this event into an OpenFGA tuple based on the following OpenFGA Authorization Schema:

publishes the event to Kafka. Kafka is a messaging system that safely moves data between systems. When an event has published an OpenFGA Kafka consumer sends the event to the OpenFGA solution.

Solution Architecture Overview

This custom Keycloak OpenFGA Event Listener [Diagram Point B] is one of the components described in following links:

🖖 Article Keycloak integration with OpenFGA (based on Zanzibar) for Fine-Grained Authorization at Scale (ReBAC)

🖖 Workshop https://github.com/embesozzi/keycloak-openfga-workshop

A brief introduction is described here:

Core:
- Keycloak [A] is responsible for handling the authentication with the standard OpenID Connect and is managing the user access with his Role Model
- Keycloak is configured with a custom extension 🚀 [B] keycloak-openfga-event-listener which listens to the Keycloak events (User Role Assignment, Role to Role Assignment, etc), parses this event into an OpenFGA tuple based on the Keycloak Authz Schema and publishes the event to Kafka Cluster [C]
- Kafka OpenFGA Consumer [D] that using the OpenFGA SDK will publish the tuples to the OpenFGA Solution
- OpenFGA [E] is responsible for applying fine-grained access control. The OpenFGA service answers authorization checks by determining whether a relationship exists between an object and a user
Other components
- Store Web Application is integrated with Keycloak by OpenID Connect
- Store API is protected by OAuth 2.0 and it utilizes the OpenFGA SDK for FGA

How does it work?

The main purpose of this SPI is to listen to the Keycloak events and publish these events to an OpenFGA solution.

Here is a high level overview of the extension:

In this case, the extension listens to the Admin Events related to operation in Keycloak Identity, Role and Group model. So far, the extension proceeds with the following steps:

Parse and enrich the default Keycloak events in the following cases:

Keycloak Event (Friendly Name)	Description
User Role Assignment	User is assigned to a Keycloak Role
Role To Role Assignment	Role is assigned to a parent Keycloak Role
Group To Role Assignment	Group is assigned to a Keycloak Role
User Group Membership	User is assigned to a Group

Transform the Keycloak event into a OpenFGA tuple and check if that is handled by keycloak-openfga-authorization-model:

Keycloak Event (Friendly Name)	OpenFGA Tuple Event
User Role Assignment	User related to the object Role as assignee
Role To Role Assignment	Role related to the object Role as parent
Group To Role Assignment	Group related to the object Role as parent group
User Group Membership	User related to a Group as assignee

This is all the OpenFGA events handled by the provided keycloak-openfga-authorization-model. You can edit the authorization model to handle the desired events.

Publish the event to the Kafka Cluster

So far we don’t have an official Java SDK OpenFGA client to publish the authorization tuples to the OpenFGA. The extension is prepared for the future to use a http client for publishing the events. I will add the feature to the extension as soon as Auth0 releases a Java OpenFGA SDK.

How to install?

Download a release (*.jar file) that works with your Keycloak version from the list of releases. Or you can build with bash mvn clean package

Follow the below instructions depending on your distribution and runtime environment.

Quarkus-based distro (Keycloak.X)

Copy the jar to the providers folder and execute the following command:

${kc.home.dir}/bin/kc.sh build

Container image (Docker)

For Docker-based setups mount or copy the jar to

/opt/keycloak/providers for Keycloak.X from version 15.1.0

Warning:

With the release of Keycloak 17 the Quarkus-based distribution is now fully supported by the Keycloak team. Therefore, I have not tested this extension in Wildfly-based distro ❗ ️

Module Configuration

The following properties can be set via environment variables following the Keycloak specs, thus each variable MUST use the prefix KC_SPI_EVENTS_LISTENER_OPENFGA_EVENTS.

KC_SPI_EVENTS_LISTENER_OPENFGA_EVENTS_AUTHORIZATION_MODEL: The authorizationModel handled by this module. See keycloak-openfga-authorization-model
KC_SPI_EVENTS_LISTENER_OPENFGA_EVENTS_SERVICE_HANDLER_NAME: The serviceHandlerName is the name of the service for publishing the events. This version only supports the value: KAFKA
KC_SPI_EVENTS_LISTENER_OPENFGA_EVENTS_ADMIN_TOPIC : The adminTopic is the name of the kafka topic to where the OpenFGA tuple events will be produced to.
KC_SPI_EVENTS_LISTENER_OPENFGA_EVENTS_CLIENT_ID: The clientId used to identify the client in Kafka.
KC_SPI_EVENTS_LISTENER_OPENFGA_EVENTS_BOOTSTRAP_SERVERS: The bootstrapServers is a comma separated list of available brokers.

You may want to check docker-compose.yml as an example.

Keycloak Configuration

Enable OpenFGA Event listener extension in Keycloak

Enable the Keycloak OpenFGA Event Listener extension in Keycloak:

Open administration console
Choose realm
Realm settings
Select Events tab and add openfga-events to Event Listeners.

Test Cases

The test cases are available in the workshop:

Workshop: https://github.com/embesozzi/keycloak-openfga-workshop

||||I|||| Skip to content Toggle navigation Sign up * Product + Actions Automate any workflow + Packages Host and manage packages + Security Find and fix vulnerabilities + Codespaces Instant dev environments + Copilot Write better code with AI + Code review Manage code changes + Issues Plan and track work + Discussions Collaborate outside of code + Explore + All features + Documentation + GitHub Skills + Blog * Solutions + For + Enterprise + Teams + Startups + Education + By Solution + CI/CD & Automation + DevOps + DevSecOps + Case Studies + Customer Stories + Resources * Open Source + GitHub Sponsors Fund open source developers + The ReadME Project GitHub community articles + Repositories + Topics + Trending + Collections * Pricing * In this repository All GitHub ↵ Jump to ↵ * No suggested jump to results * In this repository All GitHub ↵ Jump to ↵ * In this user All GitHub ↵ Jump to ↵ * In this repository All GitHub ↵ Jump to ↵ Sign in Sign up {{ message }} embesozzi / keycloak-openfga-event-listener Public * * Notifications * Fork 2 * Star 1 Keycloak OpenFGA Custom Event Listener for integrating Keycloak and OpenFGA for Fine-Grained Authorization License Apache-2.0 license 1 star 2 forks Star Notifications * Code * Issues 0 * Pull requests 0 * Actions * Projects 0 * Security * Insights More * Code * Issues * Pull requests * Actions * Projects * Security * Insights embesozzi/keycloak-openfga-event-listener This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository. main Switch branches/tags Branches Tags Could not load branches Nothing to show {{ refName }} default View all branches Could not load tags Nothing to show {{ refName }} default View all tags Name already in use A tag already exists with the provided branch name. Many Git commands accept both tag and branch names, so creating this branch may cause unexpected behavior. Are you sure you want to create this branch? Cancel Create 1 branch 0 tags Code * Local * Codespaces * Clone HTTPS GitHub CLI Use Git or checkout with SVN using the web URL. Work fast with our official CLI. Learn more. * Open with GitHub Desktop * Download ZIP Sign In Required Please sign in to use Codespaces. Launching GitHub Desktop If nothing happens, download GitHub Desktop and try again. Launching GitHub Desktop If nothing happens, download GitHub Desktop and try again. Launching Xcode If nothing happens, download Xcode and try again. Launching Visual Studio Code Your codespace will open once ready. There was a problem preparing your codespace, please try again. Latest commit Git stats * 10 commits Files Permalink Failed to load latest commit information. Type Name Latest commit message Commit time .github images src/ main .gitignore Dockerfile LICENSE README.md docker-compose.yml keycloak-openfga-authorization-model.json openfga-authorization-model.json pom.xml View code Keycloak OpenFGA Custom Event Listener Solution Architecture Overview How does it work? How to install? Quarkus-based distro (Keycloak.X) Container image (Docker) Module Configuration Keycloak Configuration Enable OpenFGA Event listener extension in Keycloak Test Cases README.md Keycloak OpenFGA Custom Event Listener Here is a Custom Event Listener Extension known as Service Provider Interfaces (SPI) which helps to integrate Keycloak and OpenFGA. OpenFGA is an open source solution for Fine-Grained Authorization that applies the concept of ReBAC (created by the Auth0 inspired by Zanzibar). The SPI implements these steps: 1. listens to the following Keycloak events based on his own Identity, Role and Group model (e.g., User Role Assignment, Role to Role Assignment, etc) 2. converts this event into an OpenFGA tuple based on the following OpenFGA Authorization Schema: 1. publishes the event to Kafka. Kafka is a messaging system that safely moves data between systems. When an event has published an OpenFGA Kafka consumer sends the event to the OpenFGA solution. Solution Architecture Overview This custom Keycloak OpenFGA Event Listener [Diagram Point B] is one of the components described in following links: 🖖 Article Keycloak integration with OpenFGA (based on Zanzibar) for Fine-Grained Authorization at Scale (ReBAC) 🖖 Workshop https://github.com/embesozzi/keycloak-openfga-workshop A brief introduction is described here: * Core: + Keycloak [A] is responsible for handling the authentication with the standard OpenID Connect and is managing the user access with his Role Model + Keycloak is configured with a custom extension 🚀 [B] keycloak-openfga-event-listener which listens to the Keycloak events (User Role Assignment, Role to Role Assignment, etc), parses this event into an OpenFGA tuple based on the Keycloak Authz Schema and publishes the event to Kafka Cluster [C] + Kafka OpenFGA Consumer [D] that using the OpenFGA SDK will publish the tuples to the OpenFGA Solution + OpenFGA [E] is responsible for applying fine-grained access control. The OpenFGA service answers authorization checks by determining whether a relationship exists between an object and a user * Other components + Store Web Application is integrated with Keycloak by OpenID Connect + Store API is protected by OAuth 2.0 and it utilizes the OpenFGA SDK for FGA How does it work? The main purpose of this SPI is to listen to the Keycloak events and publish these events to an OpenFGA solution. Here is a high level overview of the extension: In this case, the extension listens to the Admin Events related to operation in Keycloak Identity, Role and Group model. So far, the extension proceeds with the following steps: 1. Parse and enrich the default Keycloak events in the following cases: Keycloak Event (Friendly Name) Description User Role Assignment User is assigned to a Keycloak Role Role To Role Assignment Role is assigned to a parent Keycloak Role Group To Role Assignment Group is assigned to a Keycloak Role User Group Membership User is assigned to a Group 1. Transform the Keycloak event into a OpenFGA tuple and check if that is handled by keycloak-openfga-authorization-model: Keycloak Event (Friendly Name) OpenFGA Tuple Event User Role Assignment User related to the object Role as assignee Role To Role Assignment Role related to the object Role as parent Group To Role Assignment Group related to the object Role as parent group User Group Membership User related to a Group as assignee This is all the OpenFGA events handled by the provided keycloak-openfga-authorization-model. You can edit the authorization model to handle the desired events. 1. Publish the event to the Kafka Cluster So far we don’t have an official Java SDK OpenFGA client to publish the authorization tuples to the OpenFGA. The extension is prepared for the future to use a http client for publishing the events. I will add the feature to the extension as soon as Auth0 releases a Java OpenFGA SDK. How to install? Download a release (*.jar file) that works with your Keycloak version from the list of releases. Or you can build with bash mvn clean package Follow the below instructions depending on your distribution and runtime environment. Quarkus-based distro (Keycloak.X) Copy the jar to the providers folder and execute the following command: ${kc.home.dir}/bin/kc.sh build Container image (Docker) For Docker-based setups mount or copy the jar to * /opt/keycloak/providers for Keycloak.X from version 15.1.0 Warning : With the release of Keycloak 17 the Quarkus-based distribution is now fully supported by the Keycloak team. Therefore, I have not tested this extension in Wildfly-based distro ❗ ️ Module Configuration The following properties can be set via environment variables following the Keycloak specs, thus each variable MUST use the prefix KC_SPI_EVENTS_LISTENER_OPENFGA_EVENTS. * KC_SPI_EVENTS_LISTENER_OPENFGA_EVENTS_AUTHORIZATION_MODEL: The authorizationModel handled by this module. See keycloak-openfga-authorization-model * KC_SPI_EVENTS_LISTENER_OPENFGA_EVENTS_SERVICE_HANDLER_NAME: The serviceHandlerName is the name of the service for publishing the events. This version only supports the value: KAFKA * KC_SPI_EVENTS_LISTENER_OPENFGA_EVENTS_ADMIN_TOPIC : The adminTopic is the name of the kafka topic to where the OpenFGA tuple events will be produced to. * KC_SPI_EVENTS_LISTENER_OPENFGA_EVENTS_CLIENT_ID: The clientId used to identify the client in Kafka. * KC_SPI_EVENTS_LISTENER_OPENFGA_EVENTS_BOOTSTRAP_SERVERS: The bootstrapServers is a comma separated list of available brokers. You may want to check docker-compose.yml as an example. Keycloak Configuration Enable OpenFGA Event listener extension in Keycloak Enable the Keycloak OpenFGA Event Listener extension in Keycloak: * Open administration console * Choose realm * Realm settings * Select Events tab and add openfga-events to Event Listeners. Test Cases The test cases are available in the workshop: * Workshop: https://github.com/embesozzi/keycloak-openfga-workshop About Keycloak OpenFGA Custom Event Listener for integrating Keycloak and OpenFGA for Fine-Grained Authorization Topics keycloak authorization keycloak-spi fine-grained-authorization openfga Resources Readme License Apache-2.0 license Stars 1 star Watchers 1 watching Forks 2 forks Releases No releases published Sponsor this project * https://www.paypal.me/embesozzi Packages 0 No packages published Languages * Java 97.9% * Dockerfile 2.1% Footer © 2023 GitHub, Inc. Footer navigation * Terms * Privacy * Security * Status * Docs * Contact GitHub * Pricing * API * Training * Blog * About You can’t perform that action at this time. You signed in with another tab or window. Reload to refresh your session. You signed out in another tab or window. Reload to refresh your session.

Search across your past Websets

GitHub Repositories: ReBAC authorization server code

Search Criteria

Enrichments

Find more results