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)

1. Create jar resource using./gradlew clean build
2. Copy/build/libs/*.jar into Keycloak´s/opt/keycloak/providers/ folder
3. 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 withregistry-.
• 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 roleeditor will allow users to also push and delete images in their namespaces.
• Assigning the client roleadmin 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):

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

1. In order to use the Docker v2 protocol, the featuredocker must be enabled during Keycloak server startup.
2. This can be done by setting the environment variableKC_FEATURES=docker,token-exchange.

1. Go to realm and choose "Clients" section
2. Create new client by clicking "Create client"
3. Choose Client Typedocker-v2 and insert client id e.g. "myregistry"
4. Set valid redirect URL

1. In Client Page, choose "Roles"-tab
2. Click "Create role" and set role name toadmin
3. Go back to "Roles"-tab
4. Click "Create role" and set role name toeditor

1. in Client Page, choose "Client scopes"-tab
2. Go to "myregistry-dedicated" scope
3. Delete "docker-v2-allow-all-mapper" configuration
4. Click "Configure a new mapper" button
5. Choose "Allow by Groups and Roles" mapper (this mapper)
6. Give it a name e.g. "Allow by Groups and Roles Mapper"

1. Go to realm and choose "Groups" section
2. Click "Create group"
3. Name it "registry-mycompany"

1. Go to realm and choose "Users" section
2. Choose your user and select "Role mapping"
3. Click "Assign role"
4. Filter by "clients" and search for 'myregistry'
5. Choose eitheradmin oreditor
6. Click "Assign"

1. Go to realm and choose "Users" section
2. Choose your user and select "Groups"
3. Click "Join Group"
4. Select "registry-mycompany"
5. Click "Join"
6. Now the user will have access to registry namespacemyregistry.com/mycompany/

Made with ❤️ in Bavaria
© 2025, Alexander Wolz