Map Keycloak Client Roles to Jenkins Groups

In a previous post, we integrated Jenkins with Keycloak using OpenID Connect (OIDC).

Now let’s go one step further: map Keycloak client roles to Jenkins groups, using LDAP-backed Keycloak groups to drive role assignment. This setup enables centralized permission control without managing users manually in Jenkins.

Scenario

Assume you have the following LDAP groups synced into Keycloak:

• engineering
• project-managers

You want:

• Members of engineering → assigned jenkins-developer client role
• Members of project-managers → assigned jenkins-admin client role

These client roles will be included in the OIDC access token and used by Jenkins as group names for permission mapping.

1. Verify LDAP Group Sync in Keycloak

In the Keycloak Admin UI:

• Navigate to Groups
• Confirm that engineering and project-managers exist and contain users
• These groups should be mapped from LDAP using a Group Mapper

2. Create Jenkins Client Roles in Keycloak

• Go to Clients → jenkins → Roles
• Create the following roles:
  • jenkins-developer
  • jenkins-admin

3. Assign Client Roles to Groups

• Go to Groups → engineering → Role mappings
  Assign: jenkins-developer
• Go to Groups → project-managers → Role mappings
  Assign: jenkins-admin

Any user in these groups will now inherit the associated client role.

4. Ensure Client Roles Are in the Access Token

• Add the roles Scope to the Jenkins Client
  • Navigate to Clients → jenkins → Client Scopes
  • Under Assigned Default Client Scopes, ensure roles is listed
    If not:
    1. Go to Client Scopes
    2. Locate the built-in scope roles
    3. Add it to Default Client Scopes for the jenkins client
• Confirm the “client roles” Mapper in the Scope
  • Go to Client Scopes → roles → Mappers
  • Look for a mapper with:
    • Mapper Type: User Client Role
    • Token Claim Name: resource_access.${client_id}.roles
  • Ensure these settings are enabled:
    • Add to access token
    • Add to ID token
    • Multivalued

5. Configure Jenkins OIDC Security Realm

In Jenkins:

• Go to Manage Jenkins → Security
• Under Security Realm → Login with OpenID Connect, configure:
  • In Advanced → Override scopes, set:
    openid profile email roles
  • In User fields → Group field name, set:
    resource_access.jenkins.roles

This tells Jenkins to extract group roles from the token and apply them as Jenkins group names.

Summary Mapping