How do I use RBAC REST API?

Issue

How do I use RBAC REST API?

Environment

Resolution

Jenkins provides a rich set of REST based APIs for most of the functionality, many times these can be used to write scripts or use them from Command line as a quicker way of getting things done and also by bypassing the UI.

Jenkins always provides a link to the REST API at the bottom right of the browser for the objects where the API is provided, this helps as a starting point to explore the API also get the API endpoint to work with. Jenkins has support for XML, JSON and Python API, this article explores the JSON API.

To get started please get the API token. Visit ${JENKINS_URL}/user/<user_id>/configure or ${JENKINS_URL}/me/configure to get the API Token (click Show API Token...)

Reference: This article covers the CloudBees RBAC REST API, complete list of Methods are listed in the CloudBees documentation

Format of the REST API Call, this is applicable for most of the Jenkins APIs

From the above diagram, CloudBees documentation calls API as REST API Commands and Method as Command Name

Examples

Below is a simple example which creates a new Group (developers), adds Member(s) to the group, creates a new role (developersRole) and grants appropriate Role(s).

Create a new Group, developers

curl -X POST '${JENKINS_URL}/groups/createGroup/api/json?name=developers' --user <user>:<API_TOKEN>

Add Member dev1 to the Group developers

curl -X POST '${JENKINS_URL}/groups/developers/addMember/api/json?name=dev1' --user <user>:<API_TOKEN>

Create a new Role, developersRole

curl -X POST '${JENKINS_URL}/roles/createRole/api/json?name=developersRole' --user <user>:<API_TOKEN>

Grant/Add Role for a given group

curl -X POST '${JENKINS_URL}/groups/developers/grantRole/api/json?role=developersRole&offset=0&inherited=true' --user <User>: <API_TOKEN>

In the above call the parameters offset & inherited are important and the documentation says:

offset, int - Propagation level. 0 - current (e.g. folder), 1 - child, 2 - grand-child, other - error
inherited, boolean - true if the role should be granted to child items

More examples :

Revoke/Remove Permission for a role

curl -X POST '${JENKINS_URL}/roles/authenticated/revokePermissions/api/json?permissions=hudson.model.Hudson.Administer' --user <User>: <API_TOKEN>

Role name in the above call is authenticated

Grant Permissions, grant specific permission for develop_prod Role

curl -X POST '${JENKINS_URL}/roles/develop_prod/grantPermissions/api/json?permissions=hudson.model.Item.Configure,hudson.model.Item.Read,hudson.scm.SCM.Tag,hudson.model.Item.Discover,hudson.model.Hudson.Read,hudson.model.Item.Workspace,hudson.model.View.Read,hudson.model.Item.Delete,hudson.model.Item.Request' --user <User>: <API_TOKEN>

Add an existing role to the list of filterable ones

curl -X POST '${JENKINS_URL}/roles/createFilterableRole/api/json?name=developersRole' --user <user>:<API_TOKEN>

The role developersRole used above must exist. createFilterableRole does not create any role.

List Group details using tree

curl -g -X GET '${JENKINS_URL}/groups/api/json?tree=groups[name,description,roles,roleAssignments,members,url]' --user <user>:<API_TOKEN>

NOTE:

If you have the CSRF enabled, you will have to add in the API call the parameter -H "${CRUB_TOKEN}". From Jenkins 2.96 onward, you can use an API token and avoid using a crumb / CSRF token.
Full list of permissions can be found in ${JENKINS_HOME}/nectar-rbac.xml file.
Make sure to use a privileged user to try these APIs, check the Column Required permissions from the API Documentation

Acknowledgements to Raghu Reddy at Assurity Consulting, most of the content of this article was provided by him.