alexanderwolz / keycloak-docker-group-role-mapper Goto Github PK

5.0 1.0 1.0 1.8 MB

Authorization Mapping Provider for Keycloak's Docker Registry v2 token protocol based on client roles and realm groups with configuration options.

License: Apache License 2.0

Kotlin 100.00%

docker registry groups keycloak roles authorization docker-registry mapping kotlin authentication plugin scope token auth jwt user email domain sld

keycloak-docker-group-role-mapper's Introduction

Docker v2 - Groups and Role Mapper for Keycloak 23.x

🧑‍💻 About

This repository provides a MappingProvider for Keycloak's Docker-v2 protocol. It manages registry access for users with client role admin or editor and who are assigned to realm groups named like registry-${namespace}. Clients without any roles are treated as user and will be granted read-only access to the namespace by default. This behavior can be overwritten by environment variables (see configuration)

🛠️ Build

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 Keycloak Dockerfile for reference in examples section.

🔬 Basic Concept

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)

⚙️ Configuration

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 access registry: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`	If `group` 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 matches `group`, `domain`, `sld` or `username` (all values can be concatenated with `,`).
`REGISTRY_GROUP_PREFIX`	any String	Custom group prefix. Will default to `registry-`. Comparisons will be checked with lowercase String representation.

🔒 Keycloak Setup

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

Enable Docker v2 Protocol Feature

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.

Create Registry Client Configuration

Go to realm and choose "Clients" section
Create new client by clicking "Create client"
Choose Client Type docker-v2 and insert client id e.g. "myregistry"
Set valid redirect URL

Create Client Roles

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

Set the Mapper

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"

Create Roles

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

Assign Roles to users

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 or editor
Click "Assign"

Assign Groups to users

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 namespace myregistry.com/mycompany/

Made with ❤️ in Bavaria
© 2024, Alexander Wolz

keycloak-docker-group-role-mapper's People

Contributors

Stargazers

Watchers

Forkers

rayshoo

keycloak-docker-group-role-mapper's Issues

Client Type "docker-v2" doesn't exist

I have put the .jar file into the /opt/keycloak/providers/ directory. However, I can't find any "docker-v2" option there. How am I able to find that "docker-v2" option?

Thank you

Mapper should interpret root namespace only if there are segments (sub-namespaces)

Unable to gain access to objects inside top-level repositories

Dear Alexander, hello

My setup inside Docker

Docker Registry 2
Keycloak as SSO server ( a custom image with your Provider )
Traefik as HTTPS reverse proxy

Both are exposed on internet using:

Keycloak exported adapter config is:

auth:
  token:
    realm: https://sso.mydomain.com/realms/registry/protocol/docker-v2/auth
    service: registry
    issuer: https://sso.mydomain.com/realms/registry

Keycloak certificate is in the Docker Registry Compose configuration.

My problem

My registry dont have a lot of groups, a lot of images are on the top-level. ( myregistry.mydomain.com/v2/<repository>/ ) without groups or usernames in the path.
When i setup Keycloak like you recommend, i can list "catalog:*" as admin but i cant find images inside a top-level repository.

My script authentication flow is made of 3 steps:

Phase 1: Basic Auth ( failing with Token Auth, moving to P2 )
Phase 2: SSO Auth with P1 Headers ( realm, service, scope )
Phase 3: Bearer Auth with Registry ( OK )

In the below example, the commands are:

version
catalog

INFO:registry:Phase 1: Testing Registry Basic Auth
{'method': 'Bearer', 'realm': 'https://sso.mydomain.com/realms/registry/protocol/docker-v2/auth', 'service': 'registry'}
INFO:registry:Phase 2: Basic Auth failed, fetching IDP with realm, service and scope
INFO:registry:Phase 3: Connecting to Registry with Credentials
{'method': 'Bearer', 'realm': 'https://sso.mydomain.com/realms/registry/protocol/docker-v2/auth', 'service': 'registry', 'scope': 'registry:catalog:*'}
{}

( Docker Registry dont send version on /v2/ )

INFO:registry:Phase 1: Testing Registry Basic Auth
{'method': 'Bearer', 'realm': 'https://sso.mydomain.com/realms/registry/protocol/docker-v2/auth', 'service': 'registry', 'scope': 'registry:catalog:*'}
INFO:registry:Phase 2: Basic Auth failed, fetching IDP with realm, service and scope
INFO:registry:Phase 3: Connecting to Registry with Credentials
{'method': 'Bearer', 'realm': 'https://sso.mydomain.com/realms/registry/protocol/docker-v2/auth', 'service': 'registry', 'scope': 'registry:catalog:*'}
{'repositories': ['REDACTED']}

The problem is that the Keycloak server is always sending 'scope': 'registry:catalog:*' for both Version and Catalog

Things i dont understand

I need to access: https://myregistry.mydomain.com/v2/<repository>/tags/list but Keycloak always sending me 'scope': 'registry:catalog:* and a 401 UNAUTHORIZED
How are groups used ? ( path format ? )
How are users used ? ( path format ? )

what i did wrong ???

If you need full configuration/output with debug you can message me.
Regards.

ldap subgroup members not recognized

I am able to successfully configure this as follows: I create a group in keycloak called "registry-path-1" , I add users "directly" to that group, then those users (and only those users) can pull packages from repository.com/path-1/...

This works great!

Now a little bit harder setup... I have a group (Group_A) that is an LDAP Federated group. My initial thought was to still create a new group called registry-path-1 and then add Group_A as a "child group" /"subgroup" to registry-path-1 group . Keycloak has an option to "Include sub-group users" so when I select that, all my users in Group_A show up in registry-path-1 via the UI.

However, when a user tries to pull a package from "repository.com/path-1/..." it says requested access to the resource is denied.

If I keep all things the same and then add in a single user directly to "registr-path-1" group, that user can pull packages, but the other users still can not, even though they are listed there in registry-path-1 (inherited from the subgroup).

I also made sure this wasn't an LDAP thing... so I did the same test with two groups created directly in keycloak (parent being registery-) and the same behavior occurred

So it would seem this mapper can read users that are "directly" in the registry- group, however, it won't look at users that are in registry- via subgroup.

Is this intentional and/or do you have any recommendations on how it can include subgroups when it checks for group access? Alternatively, is there a way I can configure this to use "Group_A" directly instead of the "registry-" prefix? I don't have control over the name of "Group_A". I do have control over the registry-path-1 though. Was hoping this mapper could be configured such that I wouldn't need "registry-" group at al.