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

LDAP Group	Keycloak Group	Assigned Client Role	Token Group Seen in Jenkins
engineering	engineering	jenkins-developer	jenkins-developer
project-managers	project-managers	jenkins-admin	jenkins-admin