keycloak auth utils
Installation
1. Django/DRF
pip install keycloak-utils[django]
2. Django/DRF with synchronization
pip install keycloak-utils[django-sync]
3. FastAPI
pip install keycloak-utils[fastapi]
Usage
1. Django/DRF
# authentication.py
from django.contrib.auth import get_user_model
from keycloak_utils.authentication.rest_framework import BaseDRFKCAuthentication
User = get_user_model()
class KeycloakDRFAuthentication(BaseDRFKCAuthentication):
kc_host = "localhost:8443"
kc_realm = "your-realm-name"
kc_algorithms = ["RS256"]
kc_audience = "account"
auth_scheme = "Bearer"
def get_or_create_user(self, claims: dict):
# override this method to get or create user
# return User.objects.get_or_create(email=claims["email"])
return user_instance
# views.py
from rest_framework.views import APIView
class TestView(APIView):
authentication_classes = [KeycloakDRFAuthentication] # Add authentication class here
def get(self, request):
return Response({"message": "Hello, world!"})
2. FastAPI
# middlewares.py
import typing
from fastapi import Request
from keycloak_utils.authentication.fastapi import BaseFastAPIKCAuthentication
from keycloak_utils.backend.fastapi import FastAPIKeycloakAuthBackend
class BearerAuthBackend(FastAPIKeycloakAuthBackend):
kc_host = "localhost:8443"
kc_realm = "test"
kc_algorithms = ["RS256"]
kc_audience = "account"
auth_scheme = "Bearer"
class AuthenticationMiddleware(BaseFastAPIKCAuthentication):
backends = [BearerAuthBackend]
def post_process_claims(
self,
claims: typing.Optional[dict],
request: Request,
) -> Request:
# do something with `claims` here
return request
# main.py
from fastapi import FastAPI
app = FastAPI()
app.add_middleware(AuthenticationMiddleware) # Add middleware here
@app.get("/")
def read_root():
return {"Hello": "World"}
Example cURL request
curl --location 'https://localhost:8443/path/to/resource/' \
--header 'Authorization: <AUTH_SCHEME> <JWT_ACCESS_TOKEN>'
- Replace the
JWT_ACCESS_TOKENwith the actual access token.AUTH_SCHEMEwith the actual auth scheme. For example,BearerorTokenor anything you defined withauth_schemeclass attribute.
Usage Advanced
1. Support for multiple authentication classes/backends
Django/DRF
# authentication.py
from django.contrib.auth import get_user_model
from keycloak_utils.authentication.rest_framework import BaseDRFKCAuthentication
User = get_user_model()
class KCBearerAuth(BaseDRFKCAuthentication):
kc_host = "localhost:8443"
kc_realm = "your-realm-name"
kc_algorithms = ["RS256"]
kc_audience = "account"
auth_scheme = "Bearer"
def get_or_create_user(self, claims: dict):
# override this method to get or create user
# return User.objects.get_or_create(email=claims["email"])
return user_instance
class KCRandomAuth(BaseDRFKCAuthentication):
kc_host = "localhost:1234" # using a different KeyCloak host
kc_realm = "realm-2" # using a different realm
kc_algorithms = ["RS256"]
kc_audience = "account"
auth_scheme = "Random" # This should be unique across all the authentication classes
def get_or_create_user(self, claims: dict):
# override this method to get or create user
# return User.objects.get_or_create(email=claims["email"])
return user_instance
# views.py
from rest_framework.views import APIView
class TestView(APIView):
authentication_classes = [KCBearerAuth, KCRandomAuth] # Add authentication class here
def get(self, request):
return Response({"message": "Hello, world!"})
FastAPI
# middlewares.py
import typing
from fastapi import Request
from keycloak_utils.authentication.fastapi import BaseFastAPIKCAuthentication
from keycloak_utils.backend.fastapi import FastAPIKeycloakAuthBackend
class BearerAuthBackend(FastAPIKeycloakAuthBackend):
kc_host = "localhost:8443"
kc_realm = "test"
kc_algorithms = ["RS256"]
kc_audience = "account"
auth_scheme = "Bearer"
class RandomAuthBackend(FastAPIKeycloakAuthBackend):
kc_host = "localhost:1234" # using a different KeyCloak host
kc_realm = "realm-2" # using a different realm
kc_algorithms = ["RS256"]
kc_audience = "account"
auth_scheme = "Random"
class AuthenticationMiddleware(BaseFastAPIKCAuthentication):
backends = [BearerAuthBackend, RandomAuthBackend]
def post_process_claims(
self,
claims: typing.Optional[dict],
request: Request,
) -> Request:
# do something with `claims` here
return request
# main.py
from fastapi import FastAPI
app = FastAPI()
app.add_middleware(AuthenticationMiddleware) # Add middleware here
@app.get("/")
def read_root():
return {"Hello": "World"}
2. Login into Django Using Keycloak SSO.
Add following settings in django app settings.py
KC_UTILS_KC_HOST = "keycloak.sso.com"
KC_UTILS_KC_REALM = "myapp.example.com"
KC_UTILS_KC_ALGORITHMS = ["RS256"]
KC_UTILS_KC_AUDIENCE = "account"
KC_UTILS_AUTH_SCHEME = "Bearer"
KC_UTILS_OIDC_RP_CLIENT_ID = "account"
KC_UTILS_OIDC_RP_CLIENT_SECRET = "client_secret"
ADMIN_URL = "admin"
AUTHENTICATION_BACKENDS = (
"django.contrib.auth.backends.ModelBackend",
"keycloak_utils.contrib.django.auth.AuthenticationBackend"
)
Add following in urls.py
from django.conf import settings
from django.contrib import admin
from django.urls import include, path
urlpatterns = [
path("", include("keycloak_utils.contrib.django.urls")),
path(f"{settings.ADMIN_URL}/", admin.site.urls),
]
Start app server and navigate to login url, It will redirect to SSO login page.
http://localhost:8000/admin/
The backend signs in the Django user whose username is the token's
preferred_username, and creates it if there is none. Keycloak always sends
usernames lowercased, so a user stored as Sara.K is matched ignoring case: the
exact spelling wins if a user has it, and tokens with the
KC_UTILS_USER_SUPERADMIN_ROLE role only match exactly. To use the same lookup
in your own authentication class, call
keycloak_utils.contrib.django.auth.stored_username(claims).
Redirect targets
oidc/login, oidc/logout and oidc/callback redirect to the next and error
targets the caller passes in. A target must be a relative path or an absolute URL
on the request's own host. Anything else (another host, //evil.com, javascript:,
or http:// on an https site) gets 400 Bad Request naming the parameter, and
the session is left as it was.
If your frontend is served from another host than the API, allow that host:
KC_UTILS_ALLOWED_REDIRECT_HOSTS = ["app.example.com", "localhost:3000"]
Each entry is compared exactly with the URL's host[:port]: give the port when the
URL has one, and no scheme. A single host may also be given as a string.
"The request's own host" is what Django's request.get_host() returns. Behind a
reverse proxy that rewrites Host, set USE_X_FORWARDED_HOST = True (and
SECURE_PROXY_SSL_HEADER for https), or list the public host here; otherwise an
absolute URL on your public host is refused. Relative paths always work.
| Setting | Default | Description |
|---|---|---|
KC_UTILS_ALLOWED_REDIRECT_HOSTS |
[] |
Hosts, besides the request's own host, that next / error may point at. |
Upgrading: before this check, any target was followed. Absolute URLs on another
host now get 400 until that host is listed above. Custom schemes such as
myapp:// are always refused; no setting allows them.
3. Permissions Endpoints
The library provides two built-in DRF endpoints for querying permissions.
All Permissions (admin only)
Returns all permissions available in the service. Requires is_staff=True.
GET /permissions/
Authorization: Bearer <token>
Response:
["app.add_model", "app.change_model", "app.delete_model", "app.view_model"]
Role Permissions (authenticated users)
Returns permissions for a specific role the authenticated user belongs to. The role is resolved from the Active-User-Role request header first, then falls back to the ?role= query parameter. Returns 400 if no role is provided.
GET /permissions/role/
Active-User-Role: editor
Authorization: Bearer <token>
or via query parameter:
GET /permissions/role/?role=editor
Authorization: Bearer <token>
Response:
["app.add_model", "app.change_model", "app.view_model"]
Configuration
| Setting | Default | Description |
|---|---|---|
KC_UTILS_PERMISSIONS_PAGINATION_CLASS |
None |
Pagination class for permissions endpoints. Set to a DRF pagination class to enable pagination. |
Example:
# settings.py
from rest_framework.pagination import PageNumberPagination
KC_UTILS_PERMISSIONS_PAGINATION_CLASS = PageNumberPagination
Role templates and seeding (keycloak_utils.rbac)
Since 0.21.0 the role-authoring mechanism the Ottu services share lives here. A project supplies three things and writes no seeder logic of its own:
- Manifest content: which permissions a role may carry, and the rules it leaves out.
- Template content: the standard roles every tenant is seeded with.
- A fingerprint model: the record of what the seeder last wrote to each group.
# myproject/rbac.py
from keycloak_utils.rbac import Manifest, ManifestEntry, RoleTemplate, TemplateRegistry
MANIFEST = Manifest(
[
ManifestEntry("refund", "payment.refund", "Refund payments", "...", "Payments"),
ManifestEntry("inquiry", "payment.inquiry", "Check status", "...", "Payments"),
],
excluded={"internal_sweep": "operator-only; never on a role"},
)
TEMPLATES = TemplateRegistry(
MANIFEST,
[RoleTemplate("support", "Support", "Look into payments", ("inquiry",))],
)
# myproject/models.py -- the library ships no models and no migrations
class SeededRole(models.Model):
group = models.OneToOneField("auth.Group", on_delete=models.CASCADE)
template_key = models.CharField(max_length=150)
fingerprint = models.CharField(max_length=64)
detached = models.BooleanField(default=False)
from keycloak_utils.rbac.django import RoleSeeder
seeder = RoleSeeder(TEMPLATES, "myproject.SeededRole")
seeder.seed_all() # {"support": SeedOutcome.CREATED, ...}
seeder.reset_to_template(group)
Each run reports one of seven outcomes per template: created, upgraded (an untouched
group gets the template's new composition), upgraded_awaiting_approval (upgraded except
for additions the project's guard holds; see below), unchanged, detached (the group was edited,
so it is never written again until reset), skipped_detached, and skipped_foreign (a
group of that name existed before the seeder did, so it is the tenant's). Seeding makes
no Keycloak call, so it works with Keycloak switched off.
The completeness gate keeps the manifest honest. Call it from the project's own test suite, against its own rule registry:
from bridgekeeper import perms
from keycloak_utils.rbac import assert_complete
def test_every_rule_has_a_manifest_decision():
assert_complete(MANIFEST, perms)
on_created runs after the seed's own transaction, so it may call an identity provider.
reset_to_template raises UnknownTemplateError for a role whose template is
no longer in the registry.
RoleSeeder takes an optional reset_guard (a ResetGuard) so a project with an approval
flow can refuse removals on a reset and route sensitive additions through that flow
instead of writing them. Both a reset and an upgrade ask it about additions: a release
that adds a gated permission to a template reaches untouched roles only through the
project's checker. Creating a role is not gated, being the platform's baseline, and an
upgrade does not ask about removals, since narrowing a template is the operator's call.
A role with such an addition outstanding stays detached; nothing in the library watches
for the approval, so the project calls seeder.reattach_if_at_parity(group) once it has
attached the permission.
A project whose roles are composed in Django sets KC_UTILS_SYNC_AUTHORIZATION = False.
Every sync_keycloak routine then writes no Authorization Services object: role sync
pushes names only, -migrate-permissions does nothing, and a new private client is
created with authorization off. Clients that already exist are not changed: one that has
Authorization Services keeps it, with its policies and resources, until it is turned off
in Keycloak.
Release notes
0.21.2
- Auth — sign in to the existing Django user whose username differs only in case.
The SSO backend now matches the token's
preferred_usernameagainst the stored username ignoring case, so a user saved asSara.Kis no longer duplicated when Keycloak sendssara.k. An exact-spelling match wins; tokens carryingKC_UTILS_USER_SUPERADMIN_ROLEmatch exactly only, so a privileged token can never land on a look-alike row. Reusable askeycloak_utils.contrib.django.auth.stored_username(claims). KC_UTILS_ALLOWED_REDIRECT_HOSTSnow also accepts a single host as a string, not only a list. A refused redirect target now names the setting in the warning log, and the README documents the behavior behind a reverse proxy (USE_X_FORWARDED_HOST/SECURE_PROXY_SSL_HEADER).
0.21.1
- Security fix — open redirect in the OIDC views.
oidc/login,oidc/logoutandoidc/callbacknow validate thenext/errorredirect targets with Django'surl_has_allowed_host_and_scheme, both where they are stored and again where they are used. A target must be a relative path or an absolute URL on the request's own host (or a host listed in the new setting below); anything else — another host,//evil.com,javascript:, orhttp://on anhttpssite — is refused with400, and the session is left untouched. - New setting
KC_UTILS_ALLOWED_REDIRECT_HOSTS(default[]): extra hosts thenext/errortargets may point at, e.g. a frontend served from another domain than the API. - Breaking for cross-host consumers: a consumer that passes an absolute
next/errorURL on a different host now gets400until that host is added toKC_UTILS_ALLOWED_REDIRECT_HOSTS. Relative paths and same-host URLs are unaffected.
0.21.0
- Dropped Python 3.9. The minimum supported version is now Python 3.10, and the test matrix runs 3.10–3.12 (Python 3.9 reached end of life in October 2025).
- New
keycloak_utils.rbacpackage: manifest, completeness gate, role templates, the pure seed decision, andRoleSeederfor Django. - Behaviour change:
KeycloakPredefinedRoleno longer replaces the permissions of an existing group on every run, which silently removed whatever an administrator had added.- Set
KC_UTILS_SEEDED_ROLE_MODEL = "app_label.Model"to get drift-aware seeding: an untouched group is upgraded, an edited one is detached and left alone. - Without that setting, a group the routine creates is still filled, but an existing group is never modified; a warning names it.
- Projects whose predefined groups were created by an earlier version should run
sync_keycloak -adopt-predefined-groupsonce (KeycloakPredefinedRoleAdoption, orKeycloakPredefinedRole(adopt_existing=True)). It records a group that still matches the provider exactly, so upgrades reach it from then on. Until then such a group is skipped with a warning. The adoption refuses to run withoutKC_UTILS_SEEDED_ROLE_MODEL. - This includes an existing group with no permissions at all, such as one a login created for a realm role before the first sync. Earlier versions filled it on the next run; it now stays empty, with the same warning, until it is given its permissions by hand.
- The Keycloak push now carries what each predefined Django group holds, not the provider's list, so an edited group and its Keycloak policies stay in step.
- Set
KeycloakRole(sync_authorization=False)and the newKeycloakRoleNamepush role names only: no authorization scope, permission or policy is written, and the role-permissions mapper is left alone.KeycloakRole's default behaviour is unchanged.KC_UTILS_SYNC_AUTHORIZATION(defaultTrue):Falsemakes every sync routine skip Authorization Services, includingsync_keycloak -migrate-groups,-migrate-permissions,-migrate-predefined-groupsand-migrate-base.- A
RoleSeederupgrade writes through itsreset_guard, so gated additions are requested rather than attached; the new outcomeupgraded_awaiting_approvalreports a role that is waiting, and it stays detached untilreattach_if_at_parity.
Test
# Install the dependencies
pip install .[test]
# Run tests
python -m pytest
Release
# do a dry-run first -
bump2version --dry-run --verbose [major|minor|patch]
# if everything looks good, run the following command to release
bump2version --verbose [major|minor|patch]
# push the changes to remote
git push origin main --tags
Keycloak Utils Configuration and Usage Guide
This document outlines the necessary configuration changes for the Keycloak utilities and provides examples for syncing and consuming data in the application. The configuration section explains why each setting is needed and its default value. The usage examples demonstrate the two primary states of using the package: sync and consume.
Configuration Settings
These environment variables are required for integrating Keycloak utilities into your application. Each variable serves a specific purpose in ensuring smooth communication between your application and the Keycloak server.
Key Configuration Variables
| Environment Variable | Default Value | Description |
|---|---|---|
KC_UTILS_KC_SERVER_URL |
`` | The base URL of the Keycloak server. Required for making API requests. |
KC_UTILS_KC_REALM |
syncertest.ottu.dev |
The realm used to manage users, groups, and roles. |
KC_UTILS_KC_CLIENT_ID |
payout |
The client ID registered in the Keycloak realm. |
KC_UTILS_KC_CLIENT_SECRET |
`` | The client secret used for authentication. |
KC_UTILS_KC_ADMIN_USER |
`` | Admin username for Keycloak. |
KC_UTILS_KC_ADMIN_PASSWORD |
`` | Admin password for authentication. |
KC_UTILS_KC_ADMIN_REALM |
master |
The admin realm where management operations are performed. |
KC_UTILS_KC_ADMIN_ID |
admin-cli |
The admin client ID used for administrative tasks. |
RABBITMQ_URL |
`` | The RabbitMQ url. |
KC_UTILS_CREATE_QUEUES |
{} |
The dictionary of queues that needs to be created keys are types, values are lists of queue names. |
KC_UTILS_CONSUMER_QUEUES |
{} |
The dictionary of queues that needs to be created and synced keys are types, values are lists of queue names. |
KC_UTILS_MESSAGE_MAX_RETRIES |
10 |
Integer defining the maximum rertries of a failed message before discpose, defaults to 10 |
KC_UTILS_PREDEFINED_ROLES_PROVIDER |
`` | String pointing to the resolver responsible of returning predefined roles to kc_lib, Should be set or else lib will raise an error if predefined roles sync class is called |
Why These Settings Are Necessary
KC_UTILS_KC_SERVER_URL: This is the entry point for all Keycloak operations, allowing the application to connect to the correct Keycloak instance.KC_UTILS_KC_REALM: Realms isolate different user bases and configurations. Using a specific realm ensures the application operates within the intended scope.KC_UTILS_KC_CLIENT_IDandKC_UTILS_KC_CLIENT_SECRET: These credentials authenticate the application to perform operations on behalf of the specified client.KC_UTILS_KC_ADMINRABBITMQ_URL_*: These settings provide administrative access to manage users, roles, and permissions in the Keycloak server.
Installed Apps Configurations
"keycloak_utils.contrib.django" should be added to the list of shared installed apps in order to be able to use the predefined commands directly.
Usage Examples
1. Syncing Keycloak Roles, Users, and Permissions
The sync command synchronizes Keycloak roles, users, and permissions with your Django application. Below is an example command and a description of its options.
example command file
import logging
from contextlib import contextmanager
from django.core.management.base import BaseCommand
from keycloak import KeycloakConnectionError, KeycloakGetError
from keycloak_utils.sync.kc_admin import kc_admin
from keycloak_utils.utils import schema_based
from ...conf import (
KC_UTILS_KC_ADMIN_ID,
KC_UTILS_KC_ADMIN_PASSWORD,
KC_UTILS_KC_ADMIN_REALM,
KC_UTILS_KC_ADMIN_USER,
KC_UTILS_KC_REALM,
KC_UTILS_KC_SERVER_URL,
)
logger = logging.getLogger(__name__)
class Command(BaseCommand):
help = "Sync Keycloak roles to Django groups and assign permissions"
desired_models_perms_map = {}
kc_admin_config = {}
clients = {}
perms = {}
realm_name = ""
sync_routines = {
"migrate_base": {
"classpath": "keycloak_utils.sync.django.core.KeycloakBase",
"extra_args": lambda self: [self.realm_name, self.clients],
"requires_await": True,
},
"migrate_groups": {
"classpath": "keycloak_utils.sync.django.core.KeycloakRole",
"extra_args": lambda self: [],
},
"migrate_users": {
"classpath": "keycloak_utils.sync.django.core.KeycloakUser",
"extra_args": lambda self: [],
},
"migrate_permissions": {
"classpath": "keycloak_utils.sync.django.core.KeycloakPermission",
"extra_args": lambda self: [self.perms],
"soft_time_limit": 1000,
},
"migrate_predefined_groups" :{
"classpath": "keycloak_utils.sync.django.core.KeycloakPredefinedRole",
"extra_args": lambda self: [],
"soft_time_limit": 1000,
}
}
def add_arguments(self, parser):
parser.add_argument(
"-migrate-groups",
action="store_true",
help="Run KeycloakRole routine",
default=False,
)
parser.add_argument(
"-migrate-users",
action="store_true",
help="Migrate users from Django to Keycloak",
default=False,
)
parser.add_argument(
"-migrate-permissions",
action="store_true",
help="Migrate permissions from Django to Keycloak",
default=False,
)
parser.add_argument(
"-migrate-base",
action="store_true",
help="Migrate base from Django to Keycloak",
default=False,
)
parser.add_argument(
"-migrate-predefined-groups",
action="store_true",
help="Migrate predefined roles from Django to Keycloak",
default=False,
)
parser.add_argument(
"-delegate-celery",
action="store_true",
help="Determines if Celery is configured in project to delegate tasks to.",
default=False,
)
parser.add_argument(
"--server-url",
type=str,
help="Keycloak server URL (overrides environment variable)",
default=KC_UTILS_KC_SERVER_URL,
)
parser.add_argument(
"--admin-username",
type=str,
help="Keycloak admin ID (overrides environment variable)",
default=KC_UTILS_KC_ADMIN_USER,
)
parser.add_argument(
"--admin-secret",
type=str,
help="Keycloak admin secret (overrides environment variable)",
default=KC_UTILS_KC_ADMIN_PASSWORD,
)
parser.add_argument(
"--realm-name",
type=str,
help="Keycloak realm name (overrides environment variable)",
default=KC_UTILS_KC_REALM,
)
parser.add_argument(
"--admin-id",
type=str,
help="Keycloak realm name (overrides environment variable)",
default=KC_UTILS_KC_ADMIN_ID,
)
parser.add_argument(
"--admin-realm",
type=str,
help="Keycloak realm name (overrides environment variable)",
default=KC_UTILS_KC_ADMIN_REALM,
)
parser.add_argument(
"--public-clients",
nargs="+",
type=str,
required=False,
help="List of clients to create in the specified realm.",
)
parser.add_argument(
"--private-clients",
nargs="+",
type=str,
required=False,
help="List of clients to create in the specified realm.",
)
def _validate_options(self, options): ...
@classmethod
@contextmanager
def update_event_listeners(cls, realm_name):
try:
attrs = kc_admin.get_realm(realm_name)
attrs |= {"eventsListeners": []}
kc_admin.update_realm(realm_name, attrs)
except KeycloakGetError:
pass
finally:
yield
attrs = kc_admin.get_realm(realm_name)
attrs |= {"eventsListeners": ["custom-event-listener", "jboss-logging"]}
kc_admin.update_realm(realm_name, attrs)
@schema_based
def handle(self, *args, **options):
self._validate_options(options)
self.perms = (
self.desired_models_perms_map if self.desired_models_perms_map else {}
)
self.clients = {
"private": options["private_clients"],
"public": options["public_clients"],
}
self.kc_admin_config = {
"server_url": options["server_url"],
"username": options["admin_username"],
"password": options["admin_secret"],
"client_id": options["admin_id"],
"user_realm_name": options["admin_realm"],
}
self.realm_name = options["realm_name"]
with self.update_event_listeners(options["realm_name"]):
handler_routine = (
self.async_handle if options["delegate_celery"] else self.sync_handle
)
handler_routine(options)
def sync_handle(self, options):
try:
kc_admin.initialize(**self.kc_admin_config)
except KeycloakConnectionError as e:
logger.error(
"unsuccessful connection attempt to server please make sure that keycloak is running on provided url and verify provided credentials",
)
return
kc_admin.connection.realm_name = options["realm_name"]
for option, config in self.sync_routines.items():
if options.get(option):
module_path, class_name = config["classpath"].rsplit(".", 1)
module = __import__(module_path, fromlist=[class_name])
sync_class = getattr(module, class_name)
extra_args = config["extra_args"](self)
sync_instance = sync_class(*extra_args)
sync_instance.run_routine()
def async_handle(self, options):
TASK = "keycloak_utils.sync.run_sync_routine_by_class_name"
from celery import current_app
self.kc_admin_config |= {"realm_name": options["realm_name"]}
for option, config in self.sync_routines.items():
if options.get(option):
task_args = [self.kc_admin_config, config["classpath"]] + config[
"extra_args"
](self)
task = current_app.send_task(
TASK,
args=tuple(task_args),
soft_time_limit=config.get("soft_time_limit"),
)
logger.info(
f"Keycloak {config['classpath'].split('.')[-1]} sync routine is delegated successfully."
)
if config.get("requires_await"):
task.get()
logger.info(
f"Keycloak {config['classpath'].split('.')[-1]} sync routine is complete."
)
DESIRED_MODELS_PERMS_MAP example
override this value in order to pass the models and their desired perms that needs to be synced, defaults to all models and default perms
CREATE = "add"
READ = "view"
UPDATE = "change"
DELETE = "delete"
CUSTOM = "custom"
CRUD_PERMISSIONS = [CREATE, READ, UPDATE, DELETE]
DESIRED_MODELS_PERMS_MAP = {
"source.payoutsource": CRUD_PERMISSIONS,
"account.merchantaccount": CRUD_PERMISSIONS,
"approvify.approvalflow": CRUD_PERMISSIONS,
"approvify.policyconfig": CRUD_PERMISSIONS,
"approvify.resourcepolicy": CRUD_PERMISSIONS,
"beneficiary.beneficiary": CRUD_PERMISSIONS,
"beneficiary.beneficiaryaccount": CRUD_PERMISSIONS,
"payout.payoutintent": [CREATE, UPDATE, DELETE],
"approvify.sanction": [READ, UPDATE],
}
key is uniformed as {appname.modelname} and value is the set of permissions to sync
example command:
python manage.py sync_keycloak \
--realm-name "synctest.ottu.dev" \
--private-clients payout estate core \
--public-clients frontend publictest \
-migrate-groups \
-migrate-users \
-migrate-base \
-migrate-permissions \
-migrate-predefined-groups \
-migrate-role-perms-mapper
Options:
-migrate-base: Creates Keycloak realm and initialize it's base data.-migrate-groups: Synchronize Keycloak roles to Django groups. Also updates the role-permissions protocol mapper on the frontend client.-migrate-users: Migrate users from Django to Keycloak.-migrate-permissions: Migrate permissions from Django to Keycloak.--migrate-predefined-groups: Migrate predefined roles from Django to Keycloak.-adopt-predefined-groups: The same, and records the existing predefined groups that still match the provider. Run once when adoptingKC_UTILS_SEEDED_ROLE_MODEL.-migrate-role-perms-mapper: Sync the role-permissions protocol mapper to the frontend client (can be run standalone).-delegate-celery: Delegates the task to a celery worker--realm-name: Specify the Keycloak realm to operate on.--clients: Specify the clients that needs to be created noting that core and frontend are created by default
celery task conf
current_app.send_task(
"keycloak_utils.sync.run_sync_routine_by_class_name",
args=(
kc_admin_config,
"{class_name}",
*args,
),
soft_time_limit=1000,
)
args are:
- kc_admin_config: the config to connect to kc instance and select realm eg:
kc_admin_config = {
"server_url": options["server_url"],
"username": options["admin_username"],
"password": options["admin_secret"],
"client_id": options["admin_id"],
"user_realm_name": options["admin_realm"],
"realm_name": options["realm_name"],
}
- class_name: the name of the class that needs to be invoked can be one of:
- KeycloakBase: to sync base
- KeycloakPermission: to sync perms
- KeycloakUser: to sync users
- KeycloakRole: to sync roles
please provide these classes as strings to dynamically retrieve from inside lib
- args: are arguments needed for class to function correctly
- for base it's the clients that needs to be created those are passed via cli argvs
- for permissions it's the permissions that need to be created these are overrides of
desired_models_perms_mapif not passed all permissions inside the microservice will be synced, including django's default ones
2. Role-Permissions Protocol Mapper
The ProtocolMapperMixin adds a hardcoded claim (role_permissions) to the frontend client's access token. The claim contains a JSON map of all roles and their permissions, keyed by microservice name.
Token claim structure:
{
"role_permissions": {
"payout": {
"admin": ["add_payment", "view_payment", "change_payment"],
"viewer": ["view_payment"]
},
"estate": {
"manager": ["add_property", "change_property"]
}
}
}
Each microservice publishes its own key (based on KC_UTILS_KC_CLIENT_ID) when it runs the sync. Other services' entries are preserved.
How it runs:
| Trigger | What happens |
|---|---|
manage.py sync_keycloak -migrate-role-perms-mapper |
Standalone sync of the mapper to the frontend client |
manage.py sync_keycloak -migrate-groups |
Mapper auto-updates after all roles and permissions are synced |
| Consumer receives a permission event (create/update) | Mapper auto-updates after group permissions are modified |
| Consumer receives a role delete event | Mapper auto-updates after the group is deleted |
Example standalone command:
python manage.py sync_keycloak \
--realm-name "myapp.example.com" \
--private-clients payout \
-migrate-role-perms-mapper
How the frontend uses it:
The access token already contains the user's roles in realm_access.roles or resource_access.{client}.roles. The frontend cross-references these with the role_permissions claim to determine the user's effective permissions per microservice.
3. Consumer
The consumer command starts a consumer that receives keycloak events and handles them accordingly
example command:
python manage.py run_consumer
this command needs to register each queue to the consumer and will init the queue registery with the settings queue is KC_UTILS_KC_REALM_NAME env var is set
example command file
import signal
import sys
import logging
from django.core.management.base import BaseCommand
from keycloak_utils.consumer.core import EventConsumer
logger = logging.getLogger(__name__)
class Command(BaseCommand):
help = "Run the Keycloak event consumer"
def add_arguments(self, parser):
parser.add_argument(
"--users-queues",
nargs="*",
default=[],
help="Space-separated list of user queues (e.g., user_queue1 user_queue2).",
)
parser.add_argument(
"--payment-queues",
nargs="*",
default=[],
help="Space-separated list of payment queues (e.g., payment_queue1 payment_queue2).",
)
parser.add_argument(
"--general-queues",
nargs="*",
default=[],
help="Space-separated list of general queues (e.g., general_queue1 general_queue2).",
)
parser.add_argument(
"--users-consumer-queues",
nargs="*",
default=[],
help="Space-separated list of user queues (e.g., user_queue1 user_queue2).",
)
parser.add_argument(
"--payment-consumer-queues",
nargs="*",
default=[],
help="Space-separated list of payment queues (e.g., payment_queue1 payment_queue2).",
)
parser.add_argument(
"--general-consumer-queues",
nargs="*",
default=[],
help="Space-separated list of general queues (e.g., general_queue1 general_queue2).",
)
queues_reg = []
def handle(self, *args, **options):
create_queues = {
"users": options["users_queues"],
"payment": options["payment_queues"],
"general": options["general_queues"],
}
consumer_queues = {
"users": options["users_consumer_queues"],
"payment": options["payment_consumer_queues"],
"general": options["general_consumer_queues"],
}
consumer = EventConsumer()
consumer.register_queue(create_queues, queue_status="create")
consumer.register_queue(consumer_queues, queue_status="sync")
for queue in self.queues_reg:
consumer.register_queue(*queue)
consumer.establish_connection()
def signal_handler(signum, frame):
self.stdout.write(
self.style.WARNING("Received shutdown signal. Stopping consumers...")
)
consumer.stop()
sys.exit(0)
signal.signal(signal.SIGTERM, signal_handler)
signal.signal(signal.SIGINT, signal_handler)
self.stdout.write(self.style.SUCCESS("Starting Keycloak event consumer"))
queue registration examples
a. override queue_reg in consumer class
first val is name second is routing key third is create or consume
queues_reg = [
("users.queuereg_ottu_dev", "eventbus.users.queuereg_ottu_dev", "create"),
("users.queuereg2_ottu_dev", "eventbus.users.queuereg2_ottu_dev", "sync"),
]
b. define env vars in microservice settings
create queues
KC_UTILS_CREATE_QUEUES = env.dict(
"KC_UTILS_CREATE_QUEUES",
default={
"users": ["synctestenvar_ottu_dev"],
"payment": ["payenvar_ottu_dev"],
},
)
consumer sync queues
KC_UTILS_CONSUMER_QUEUES = env.dict(
"KC_UTILS_CONSUMER_QUEUES",
default={
"general": ["users"],
},
)
c. override queue_reg in consumer class
for create queues
python manage.py run_consumer --general-queues testdemo --payment-queues paymenttestdemo --users-queues userstestdemo testdemo
for consumer queues add consumer to the option eg:
python manage.py run_consumer --users-consumer-queues userstestdemo testdemo
example command:
python manage.py run_consumer
this needs to be run in each microservice and make sure to pass the KC_UTILS_KC_CLIENT_ID env var that specifies which microservice it is run on to pickup only according events override the queues_reg to define custom values where first arg is queue name second is routing key and third if sync or create
adding your custom handler for custom events
class EventTypeStrategyClassFactory(BaseEventStrategyFactory):
event_map = {
"payment": PaymentEventStrategyFactory,
"kc": KCEventStrategyFactory,
}
this class's event_map needs to be updatesd with the key of the event and the value the class that shouldbe defined to handle such event
**4. APIVIEW EventHandler **
example view file
import logging
from drf_spectacular.types import OpenApiTypes
from drf_spectacular.utils import OpenApiExample, extend_schema
from rest_framework import status
from rest_framework.response import Response
from keycloak_utils.consumer.core import EventHandler
from rest_framework.views import APIView
logger = logging.getLogger(__name__)
class ConsumerAPIView(APIView):
@extend_schema(
summary="Post JSON data to ConsumerAPI",
description="This endpoint accepts a JSON payload and processes it.",
request={
"application/json": {
"type": "object",
"properties": {},
}
},
responses={
200: OpenApiTypes.OBJECT,
400: OpenApiTypes.OBJECT,
},
examples=[
OpenApiExample(
name="Valid Request Example",
description="A sam ple payload for the API",
value={},
),
],
)
def post(self, request, *args, **kwargs):
event_data = request.data
try:
processed = EventHandler.process_message(event_data)
if processed:
return Response(
f"processed event {event_data} successfully!",
status=status.HTTP_200_OK,
)
return Response(
f"processing event {event_data} failed please check logs!",
status=status.HTTP_400_BAD_REQUEST,
)
except Exception as e:
return Response(
{"status": "error", "message": f"Failed to connect {e}"},
status=status.HTTP_500_INTERNAL_SERVER_ERROR,
)
this creates an apiview that accepts the event data as decoded json format for the app to handle in case of client having a low spec machine that doesnt support consumers
Metadata
Release files for keycloak-utils 0.21.2
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| keycloak_utils-0.21.2.tar.gz | 95.9 kB | Without provenance | Details for keycloak_utils-0.21.2.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| keycloak_utils-0.21.2-py3-none-any.whl | Python 3 | none | any | Details for keycloak_utils-0.21.2-py3-none-any.whl |
Total release size: 180.7 kB
Release files / keycloak_utils-0.21.2.tar.gz
| Download URL | keycloak_utils-0.21.2.tar.gz |
|---|---|
| Size | 95.9 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
57570303856e0e66fac6d526e7e9a528fc2b9375ffcf1984bf489c1e24f83d68
|
|
BLAKE2b-256 checksum How to use checksums |
fbe1fd557cfca7a0e7d48d811c787ebdae2c3530fdacff5b597b18f7ca4e0c95
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Release files / keycloak_utils-0.21.2-py3-none-any.whl
| Download URL | keycloak_utils-0.21.2-py3-none-any.whl |
|---|---|
| Size | 84.7 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
b3ae0cc4d17192add12a1810290ec05bc1cd7b6223fdef77b9893a068e0e9fea
|
|
BLAKE2b-256 checksum How to use checksums |
23078a12424e97b18885b157d32de279da3d3bf364c7e8bc2bf907a07a201b15
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Security for keycloak-utils 0.21.2
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.