How do I use RBAC REST API?

Issue

  • How do I use RBAC REST API

Environment

  • CloudBees Jenkins Enterprise
  • CloudBees Jenkins Operations Center

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 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>
  • Grant/Add Role for a given group
curl -X POST '${JENKINS_URL}/groups/developers/grantRole/api/json?role=developer&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>

NOTE:

  • If you have the CSRF enabled, you will have to add in the API call the parameter -H "${CRUB_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?
1 out of 1 found this helpful
Have more questions? Submit a request

3 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.

Please sign in to leave a comment.