Uh oh!
There was an error while loading.Please reload this page.
- Notifications
You must be signed in to change notification settings - Fork2
Authorization Mapping Provider for Keycloak's Docker Registry v2 token protocol based on client roles and realm groups with configuration options.
License
alexanderwolz/keycloak-docker-group-role-mapper
Folders and files
Name | Name | Last commit message | Last commit date | |
---|---|---|---|---|
Repository files navigation
This repository provides a MappingProvider for Keycloak's Docker-v2 protocol. It manages registry access for users with client roleadmin
oreditor
and who are assigned to realm groups named likeregistry-${namespace}
. Clients without any roles are treated asuser
and will be granted read-only access to the namespace by default. This behavior can be overwritten by environment variables (see configuration)
- Create jar resource using
./gradlew clean build
- Copy
/build/libs/*.jar
into Keycloak´s/opt/keycloak/providers/
folder - Build keycloak instance using
/opt/keycloak/bin/kc.sh build
See also KeycloakDockerfile for reference inexamples section.
- Users can be grouped to the same repository namespace by assigning them to one or several groups starting with
registry-
. - Without any client roles assigned, users will be granted read-only access to their namespaces.
- Default namespaces (repositories without prefix/) can only be accessed by admins.
- Assigning the client role
editor
will allow users to also push and delete images in their namespaces. - Assigning the client role
admin
will allow access to any resource in the whole registry and give full access. - Users could be grouped to domain-namespaces according to their email-addresses (can be configured via environment variables, default off)
- Without having any roles and groups assigned, users will have full access to the namespace if it matches their username (can be configured via environment variables, default off)
This mapper supports following environment variables (either set on server or in docker container):
Variable Name | Values | Description |
---|---|---|
REGISTRY_CATALOG_AUDIENCE | editor ,user | Will allow editors or users to accessregistry:catalog:* scope. That would be of interest to users who want to access UI frontends. No scope is set by default, so only admins are allowed to access registry scope. |
REGISTRY_NAMESPACE_SCOPE | group ,domain ,sld ,username | Ifgroup is set, users are checked for group membership and will be granted access to the repository according to their roles.If domain is set, users are checked against their email domain and will be granted access to the repository (e.g.company.com/image) according to their roles.If sld is set, users are checked against their email second level domain (sld) and will be granted access to the repository (e.g.company/image) according to their roles.If username is set, users will be granted full access to the namespace if it matches their username (lowercase check).Namespace scope group is set by default or if value is empty or no value matchesgroup ,domain ,sld orusername (all values can be concatenated with, ). |
REGISTRY_GROUP_PREFIX | any String | Custom group prefix. Will default toregistry- . Comparisons will be checked with lowercase String representation. |
Keycloak must be setup to have a docker-v2 registry client, roles and optional groups. The registry then must be configured to use OIDC configuration provided by Keycloak
- In order to use the Docker v2 protocol, the feature
docker
must be enabled during Keycloak server startup. - This can be done by setting the environment variable
KC_FEATURES=docker,token-exchange
.
- Go to realm and choose "Clients" section
- Create new client by clicking "Create client"
- Choose Client Typedocker-v2 and insert client id e.g. "myregistry"
- Set valid redirect URL
- In Client Page, choose "Roles"-tab
- Click "Create role" and set role name to
admin
- Go back to "Roles"-tab
- Click "Create role" and set role name to
editor
- in Client Page, choose "Client scopes"-tab
- Go to "myregistry-dedicated" scope
- Delete "docker-v2-allow-all-mapper" configuration
- Click "Configure a new mapper" button
- Choose "Allow by Groups and Roles" mapper (this mapper)
- Give it a name e.g. "Allow by Groups and Roles Mapper"
- Go to realm and choose "Groups" section
- Click "Create group"
- Name it "registry-mycompany"
- Go to realm and choose "Users" section
- Choose your user and select "Role mapping"
- Click "Assign role"
- Filter by "clients" and search for 'myregistry'
- Choose either
admin
oreditor
- Click "Assign"
- Go to realm and choose "Users" section
- Choose your user and select "Groups"
- Click "Join Group"
- Select "registry-mycompany"
- Click "Join"
- Now the user will have access to registry namespacemyregistry.com/mycompany/
Made with ❤️ in Bavaria
© 2025, Alexander Wolz
About
Authorization Mapping Provider for Keycloak's Docker Registry v2 token protocol based on client roles and realm groups with configuration options.
Topics
Resources
License
Code of conduct
Uh oh!
There was an error while loading.Please reload this page.
Stars
Watchers
Forks
Sponsor this project
Uh oh!
There was an error while loading.Please reload this page.