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:

  1. offset, int - Propagation level. 0 - current (e.g. folder), 1 - child, 2 - grand-child, other - error
  2. 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.

Was this article helpful?
2 out of 2 found this helpful

Have more questions?

8 Comments

Date Votes
  • 0
    Avatar
    Allan Selvan

    There is no documentation for creating a role but it works. Is it intentionally not there?

    "${jenkinsUrl}/roles/createRole/api/json?name=user"

  • 0
    Avatar
    Denys Digtiar

    Here are just a few example of how to use the API endpoints which are documented in

    https://go.cloudbees.com/docs/cloudbees-documentation/cje-user-guide/index.html#rbac-sect-rest-api-roles-management

    which includes the Role endpoints.

  • 0
    Avatar
    Allan Selvan

    @Denys Thanks much. Really good documentation indeed of the RBAC roles. 

    Is there also documentation of other Jenkins API's for example : for creating a folder in Jenkins. Also I need a API by which I can add global as well as folder domain credentials in Jenkins.

  • 0
    Avatar
    Venkatareddy Sathi

    What is the syntax to delete a member from group? if i try below syntax API returns a confirmation page to delete member.

    https://jenkins/job/folder/groups/group/deleteMember?member=abc

  • 0
    Avatar
    Zulfiqar Khoja

    What is the syntax to check if a group exists?

  • 0
    Avatar
    Allan Selvan

    @Venkatareddy

    Add member: {{JenkinsUrl}}/groups/{{groupName}}/addMember/api/json?name={{memberId}}

    Remove member: {{JenkinsUrl}}/groups/{{groupName}}/removeMember/api/json?name={{memberId}}

    @Zulfiqar
    if you do a get request on https://{{JENKIN_URL}}/groups/{{GROUP_NAME}} you should get a 302 Found status if it exists and a 404 Not Found if it is not found.

    I had also created a CLI long ago which could do most of the RBAC requests - might be interesting to see.

  • 0
    Avatar
    Zulfiqar Khoja

    @Allan

    I found a better solution, https://{{JENKIN_URL}}/groups/{{GROUP_NAME}} /api/json?pretty=true

    The URL https://{{JENKIN_URL}}/groups/{{GROUP_NAME}}  is not a RBAC API. It hung our production system when I mistakenly used it as a Rest API. 

     

     

  • 0
    Avatar
    Allan Selvan

    Awesome! Thats for the update :D 

Please sign in to leave a comment.