Role-Based Access Control API reference

7 minute readReference

The CloudBees Role-Based Access Control (RBAC) plugin provides endpoints, which allow managing groups and roles using POST requests. It is also possible to retrieve the data in various formats using CloudBees CI standard REST API functionality.

Authentication

To access the RBAC management API, you need an API authentication token. Refer to API authentication for more information.

Authorization depends on the endpoints and/or methods. Refer to the required permissions in Endpoints and methods.

Endpoints and methods

Managing RBAC group containers

This set of commands allows managing groups in various group containers: root, folders, jobs and nodes. Endpoint URL examples:

  • ${JENKINS_URL}/groups

  • ${JENKINS_URL}/job/folder1/job/folder2/groups

  • ${JENKINS_URL}/job/folder1/job/myJob/groups

  • ${JENKINS_URL}/computer/node1/groups

Table 1. Group containers endpoints and methods
Endpoint Required permissions Description Parameters

GET ${JENKINS_URL}/groups/api/json

Group.VIEW

Lists groups in the container.

  • Name: tree

    • Parameter type: Query string parameter

    • Data type: string

    • Description: The tree parameter allows you to explicitly specify and retrieve only the information you are looking for, by using an XPath-ish path expression. The value should be a list of property names to include, with sub-properties inside square braces.

POST ${JENKINS_URL}/groups/createGroup

Group.CREATE

Creates a new group.

  • Name: name

    • Parameter type: Query string parameter

    • Data type: string

    • Description: The name parameter is the name of the group to be created.

POST ${JENKINS_URL}/groups/deleteGroup

Group.DELETE

Deletes a group.

  • Name: name

    • Parameter type: Query string parameter

    • Data type: string

    • Description: The name parameter is the name of the group to be deleted.

POST ${JENKINS_URL}/groups/addRoleFilter

Roles.FILTER

Adds a role filter. A role filter allows roles to be filtered in the container if these roles are filterable.

  • Name: name

    • Parameter type: Query string parameter

    • Data type: string

    • Description: The name parameter is the name of the role, which should be filtered.

POST ${JENKINS_URL}/groups/deleteRoleFilter

Roles.FILTER

Deletes a role filter.

  • Name: name

    • Parameter type: Query string parameter

    • Data type: string

    • Description: The name parameter is the name of the role, which should not be filtered anymore.

Managing RBAC groups individually

After creating groups using the commands above, you may need to configure the groups. For each group, the API endpoint can be accessed by its group URL. Endpoint examples:

  • ${JENKINS_URL}/groups/myGroupName

  • ${JENKINS_URL}/job/folder1/job/myJob/groups/myGroupName

  • ${JENKINS_URL}/computer/node1/groups/myGroupName

Table 2. Groups endpoints and methods
Endpoint Required permissions Description Parameters

POST ${JENKINS_URL}/groups/myGroupName/setDescription

Group.MANAGE

Sets the group description.

  • Name: description

    • Parameter type: Query string parameter

    • Data type: string

    • Description: The description parameter is a raw string with the group description.

POST ${JENKINS_URL}/groups/myGroupName/addUser

Group.MANAGE

Adds a new user to the group.

  • Name: name

    • Parameter type: Query string parameter

    • Data type: string

    • Description: The name parameter is the User id of the user to be added.

POST ${JENKINS_URL}/groups/myGroupName/removeUser

Group.MANAGE

Removes a user from a group.

  • Name: name

    • Parameter type: Query string parameter

    • Data type: string

    • Description: The name parameter is the User id of the user to be removed.

POST ${JENKINS_URL}/groups/myGroupName/addGroup

Group.MANAGE

Adds a new internal RBAC group or external (from the security realm) group to the myGroupName group.

  • Name: name

    • Parameter type: Query string parameter

    • Data type: string

    • Description: The name parameter is the name of the group to be added.

POST ${JENKINS_URL}/groups/myGroupName/removeGroup

Group.MANAGE

Removes internal or external groups.

  • Name: name

    • Parameter type: Query string parameter

    • Data type: string

    • Description: The name parameter is the id of the internal or external group to be removed.

POST ${JENKINS_URL}/groups/myGroupName/grantRole

Group.MANAGE

Grants a role to this group. Overrides the current settings if they exist.

  • Name: role

    • Parameter type: Query string parameter

    • Data type: string

    • Description: The role parameter is the ID of the role.

  • Name: offset

    • Parameter type: Query string parameter

    • Data type: integer

    • Description: The offset parameter is the propagation level. 0 = current (for example, folder); 1 = child; 2 = grandchild; other = error.

  • Name: inherited

    • Parameter type: Query string parameter

    • Data type: boolean

    • Description: The inherited parameter is true if the role should be granted to child items.

POST ${JENKINS_URL}/groups/deleteRoleFilter

Roles.FILTER

Deletes a role filter.

  • Name: name

    • Parameter type: Query string parameter

    • Data type: string

    • Description: The name parameter is the name of the role, which should not be filtered anymore.

Managing RBAC global roles

On the top level of Jenkins you can create and manage roles. Endpoint URL for overall group management: ${JENKINS_URL}/roles.

Table 3. Global roles endpoints and methods
Endpoint Required permissions Description Parameters

GET ${JENKINS_URL}/roles/api/json

Jenkins.ADMINISTER

Lists all global roles.

  • Name: tree

    • Parameter type: Query string parameter

    • Data type: string

    • Description: The tree parameter allows you to explicitly specify and retrieve only the information you are looking for, by using an XPath-ish path expression. The value should be a list of property names to include, with sub-properties inside square braces.

POST ${JENKINS_URL}/roles/createRole

Jenkins.ADMINISTER

Creates a new role.

  • Name: name

    • Parameter type: Query string parameter

    • Data type: string

    • Description: The name parameter is the name of the role to be added.

POST ${JENKINS_URL}/roles/deleteRole

Jenkins.ADMINISTER

Removes a role.

  • Name: name

    • Parameter type: Query string parameter

    • Data type: string

    • Description: The name parameter is the name of the role to be removed.

POST ${JENKINS_URL}/roles/createFilterableRole

Jenkins.ADMINISTER

Adds a role to the list of filterable roles.

  • Name: name

    • Parameter type: Query string parameter

    • Data type: string

    • Description: The name parameter is the name of the role to be added to the list of filterable roles.

POST ${JENKINS_URL}/roles/deleteFilterableRole

Jenkins.ADMINISTER

Remove role from the list of filterable roles.

  • Name: name

    • Parameter type: Query string parameter

    • Data type: string

    • Description: The name parameter is the name of the role, which should be removed from the list of filterable roles.

Managing RBAC roles individually

After creating roles it is possible to manage them individually. Endpoint URL for individual group management: ${JENKINS_URL}/roles/{ROLE_NAME}.

Table 4. Group containers endpoints and methods
Endpoint Required permissions Description Parameters

POST ${JENKINS_URL}/roles/{ROLE_NAME}/grantPermissions

Jenkins.ADMINISTER

Grants permissions to the role.

  • Name: permissions

    • Parameter type: Query string parameter

    • Data type: string

    • Description: Comma-separated list of permissions to be granted.

POST ${JENKINS_URL}/role/{ROLE_NAME}/revokePermissions

Jenkins.ADMINISTER

Revokes permissions from the role.

  • Name: permissions

    • Parameter type: Query string parameter

    • Data type: string

    • Description: Comma-separated list of permissions to be granted.

Request examples

In the request examples, admin is the name of the user attempting to send the request and https://my-operations-center.com/cjoc/ is the URL for the operations center.
The -g option switches off the "URL globbing parser" for curl. When you set this option, you can specify URLs that contain the letters {}[] without having them being interpreted by curl itself. Note that these letters are not normal legal URL contents, but they should be encoded according to the URI standard.

Group containers

Table 5. Group containers request examples
Endpoint Request example

GET ${JENKINS_URL}/groups/api/json

 
curl -g --user "admin:rG57xFa2eFrCeWjG4NKU5QMJeW9TzfSkym" -XGET "https://my-operations-center.com/cjoc/groups/api/json?tree=groups[name,description,roles,roleAssignments,users,groups,url]"
▼

POST ${JENKINS_URL}/groups/createGroup

 
curl --user "admin:rG57xFa2eFrCeWjG4NKU5QMJeW9TzfSkym" -XPOST "https://my-operations-center.com/cjoc/groups/createGroup?name=sample-group"
▼

POST ${JENKINS_URL}/groups/addRoleFilter

 
curl --user "admin:rG57xFa2eFrCeWjG4NKU5QMJeW9TzfSkym" -XPOST "https://my-operations-center.com/cjoc/groups/addRoleFilter?name=browse"
▼

POST ${JENKINS_URL}/groups/deleteRoleFilter

 
curl --user "admin:rG57xFa2eFrCeWjG4NKU5QMJeW9TzfSkym" -XPOST "https://my-operations-center.com/cjoc/groups/deleteRoleFilter?name=browse"
▼

Groups individually

Table 6. Group request examples
Endpoint Request example

POST ${JENKINS_URL}/groups/myGroupName/setDescription

 
curl --user "admin:rG57xFa2eFrCeWjG4NKU5QMJeW9TzfSkym" -XPOST "https://my-operations-center.com/cjoc/groups/sample-group/setDescription?description=This%20is%20a%20sample%20description%20for%20my%20sample%20group."
▼

POST ${JENKINS_URL}/groups/myGroupName/addMember

 
curl --user "admin:rG57xFa2eFrCeWjG4NKU5QMJeW9TzfSkym" -XPOST "https://my-operations-center.com/cjoc/groups/sample-group/addMember?name=jane"
▼
The addMember endpoint has been deprecated. Use either the addUser or addGroup endpoint instead.

POST ${JENKINS_URL}/groups/myGroupName/removeMember

 
curl --user "admin:rG57xFa2eFrCeWjG4NKU5QMJeW9TzfSkym" -XPOST "https://my-operations-center.com/cjoc/groups/sample-group/removeMember?name=jane"
▼
The removeMember endpoint has been deprecated. Use either the removeUser or removeGroup endpoint instead.

POST ${JENKINS_URL}/groups/myGroupName/grantRole

 
curl --user "admin:rG57xFa2eFrCeWjG4NKU5QMJeW9TzfSkym" -XPOST "https://my-operations-center.com/cjoc/groups/sample-group/grantRole?role=browse&offset=0&inherited=false"
▼

POST ${JENKINS_URL}/groups/myGroupName/revokeRole

 
curl --user "admin:rG57xFa2eFrCeWjG4NKU5QMJeW9TzfSkym" -XPOST "https://my-operations-center.com/cjoc/groups/sample-group/revokeRole?role=browse"
▼

Global roles

Table 7. Global roles request examples
Endpoint Request example

GET ${JENKINS_URL}/roles/api/json

 
curl -g --user "admin:rG57xFa2eFrCeWjG4NKU5QMJeW9TzfSkym" -XGET "https://my-operations-center.com/cjoc/roles/api/json?tree=roles[id,filterable,grantedPermissions]"
▼

POST ${JENKINS_URL}/roles/createRole

 
curl --user "admin:rG57xFa2eFrCeWjG4NKU5QMJeW9TzfSkym" -XPOST "https://my-operations-center.com/cjoc/roles/createRole?name=new-role"
▼

POST ${JENKINS_URL}/roles/deleteRole

 
curl --user "admin:rG57xFa2eFrCeWjG4NKU5QMJeW9TzfSkym" -XPOST "https://my-operations-center.com/cjoc/roles/deleteRole?name=new-role"
▼

POST ${JENKINS_URL}/roles/createFilterableRole

 
curl --user "admin:rG57xFa2eFrCeWjG4NKU5QMJeW9TzfSkym" -XPOST "https://my-operations-center.com/cjoc/roles/createFilterableRole?name=new-filterable-role"
▼

POST ${JENKINS_URL}/roles/deleteFilterableRole

 
curl --user "admin:rG57xFa2eFrCeWjG4NKU5QMJeW9TzfSkym" -XPOST "https://my-operations-center.com/cjoc/roles/deleteFilterableRole?name=new-filterable-role"
▼

Individual roles

Table 8. Individual roles request examples
Endpoint Request example

POST ${JENKINS_URL}/roles/{ROLE_NAME}/grantPermissions

 
curl --user "admin:rG57xFa2eFrCeWjG4NKU5QMJeW9TzfSkym" -XPOST "https://my-operations-center.com/cjoc/roles/sample-role/grantPermissions?permissions=hudson.model.Item.Discover,hudson.model.Hudson.Administer"
▼

POST ${JENKINS_URL}/roles/{ROLE_NAME}/revokePermissions

 
curl --user "admin:rG57xFa2eFrCeWjG4NKU5QMJeW9TzfSkym" -XPOST "https://my-operations-center.com/cjoc/roles/sample-role/revokePermissions?permissions=hudson.model.Item.Discover,hudson.model.Hudson.Administer"
▼

Response examples

The members attribute has been deprecated. Use either the users or groups attribute instead.
Response examples are formatted for better readability.
GET ${JENKINS_URL}/groups/api/json
GET ${JENKINS_URL}/roles/api/json
{
    "_class": "nectar.plugins.rbac.groups.RootProxyGroupContainer",
    "groups": [
        {
            "description": null,
            "users": [
                "ada",
                "john"
            ],
            "groups": [
                "dev-group"
            ],
            "members": [
                "ada",
                "john",
                "dev-group"
            ],
            "name": "Developers",
            "roleAssignments": [
                {}
            ],
            "roles": [
                "develop"
            ],
            "url": "groups/Developers/"
        },
        {
            "description": null,
            "users": [
                "jane",
                "tom"
            ],
            "groups": [],
            "members": [
                "jane",
                "tom"
            ],
            "name": "Browsers",
            "roleAssignments": [
                {}
            ],
            "roles": [
                "browse"
            ],
            "url": "groups/Browsers/"
        },
        {
            "description": null,
            "users": [
                "admin"
            ],
            "groups": [],
            "members": [
                "admin"
            ],
            "name": "Administrators",
            "roleAssignments": [
                {}
            ],
            "roles": [
                "administer"
            ],
            "url": "groups/Administrators/"
        }
    ]
}
▼
{
    "_class": "nectar.plugins.rbac.groups.RootProxyGroupContainer$RootRolesAction",
    "roles": [
        {
            "filterable": false,
            "grantedPermissions": [
                "com.cloudbees.pipeline.governance.templates.catalog.TemplateCatalogAction.ViewCatalogs"
            ],
            "id": "authenticated",
            "id": "authenticated"
        },
        {
            "filterable": false,
            "grantedPermissions": [
                "com.cloudbees.jenkins.plugin.metrics.views.Alerter.Mute",
                "com.cloudbees.jenkins.plugin.metrics.views.Alerter.View",
                "com.cloudbees.jenkins.support.SupportPlugin.DownloadBundle",
                "com.cloudbees.opscenter.server.model.ClientMaster.Configure",
                "com.cloudbees.opscenter.server.model.ClientMaster.Lifecycle",
                "com.cloudbees.opscenter.server.model.SharedCloud.Configure",
                "com.cloudbees.opscenter.server.model.SharedCloud.Connect",
                "com.cloudbees.opscenter.server.model.SharedCloud.Disconnect",
                "com.cloudbees.opscenter.server.model.SharedCloud.ForceRelease",
                "com.cloudbees.pipeline.governance.templates.catalog.TemplateCatalogAction.ManageCatalogs",
                "com.cloudbees.pipeline.governance.templates.catalog.TemplateCatalogAction.ViewCatalogs",
                "com.cloudbees.plugins.credentials.CredentialsProvider.Create",
                "com.cloudbees.plugins.credentials.CredentialsProvider.Delete",
                "com.cloudbees.plugins.credentials.CredentialsProvider.ManageDomains",
                "com.cloudbees.plugins.credentials.CredentialsProvider.Update",
                "com.cloudbees.plugins.credentials.CredentialsProvider.View",
                "com.cloudbees.plugins.updatecenter.UpdateCenter.Configure",
                "com.cloudbees.plugins.updatecenter.UpdateCenter.Promote",
                "com.cloudbees.plugins.updatecenter.UpdateCenter.Store",
                "com.cloudbees.plugins.updatecenter.UpdateCenter.Upload",
                "hudson.model.Computer.Build",
                "hudson.model.Computer.Configure",
                "hudson.model.Computer.Connect",
                "hudson.model.Computer.Create",
                "hudson.model.Computer.Delete",
                "hudson.model.Computer.Disconnect",
                "hudson.model.Computer.Provision",
                "hudson.model.Computer.Secure",
                "hudson.model.Computer.ViewOwners",
                "hudson.model.Hudson.Administer",
                "hudson.model.Hudson.ConfigureUpdateCenter",
                "hudson.model.Hudson.Manage",
                "hudson.model.Hudson.Read",
                "hudson.model.Hudson.RunScripts",
                "hudson.model.Hudson.UploadPlugins",
                "hudson.model.Item.Build",
                "hudson.model.Item.Cancel",
                "hudson.model.Item.Configure",
                "hudson.model.Item.Create",
                "hudson.model.Item.Delete",
                "hudson.model.Item.Discover",
                "hudson.model.Item.Move",
                "hudson.model.Item.Promote",
                "hudson.model.Item.Read",
                "hudson.model.Item.Request",
                "hudson.model.Item.Workspace",
                "hudson.model.Run.Delete",
                "hudson.model.Run.Replay",
                "hudson.model.Run.Update",
                "hudson.model.View.Configure",
                "hudson.model.View.Create",
                "hudson.model.View.Delete",
                "hudson.model.View.Read",
                "hudson.scm.SCM.Tag",
                "jenkins.metrics.api.Metrics.HealthCheck",
                "jenkins.metrics.api.Metrics.ThreadDump",
                "jenkins.metrics.api.Metrics.View",
                "nectar.plugins.rbac.groups.Group.Configure",
                "nectar.plugins.rbac.groups.Group.Create",
                "nectar.plugins.rbac.groups.Group.Delete",
                "nectar.plugins.rbac.groups.Group.Manage",
                "nectar.plugins.rbac.groups.Group.View",
                "nectar.plugins.rbac.roles.Role.Filter",
                "nectar.plugins.rbac.roles.Role.View"
            ],
            "id": "administer",
            "id": "administer"
        },
        {
            "filterable": false,
            "grantedPermissions": [],
            "id": "anonymous",
            "id": "anonymous"
        },
        {
            "filterable": true,
            "grantedPermissions": [
                "com.cloudbees.opscenter.server.model.ClientMaster.Configure",
                "com.cloudbees.opscenter.server.model.ClientMaster.Lifecycle",
                "com.cloudbees.opscenter.server.model.SharedCloud.Configure",
                "hudson.model.Hudson.Read",
                "hudson.model.Item.Build",
                "hudson.model.Item.Cancel",
                "hudson.model.Item.Configure",
                "hudson.model.Item.Create",
                "hudson.model.Item.Delete",
                "hudson.model.Item.Discover",
                "hudson.model.Item.Move",
                "hudson.model.Item.Promote",
                "hudson.model.Item.Read",
                "hudson.model.Item.Request",
                "hudson.model.Item.Workspace",
                "hudson.model.Run.Delete",
                "hudson.model.Run.Replay",
                "hudson.model.Run.Update",
                "hudson.model.View.Configure",
                "hudson.model.View.Create",
                "hudson.model.View.Delete",
                "hudson.model.View.Read",
                "hudson.scm.SCM.Tag"
            ],
            "id": "develop",
            "id": "develop"
        },
        {
            "filterable": true,
            "grantedPermissions": [
                "hudson.model.Hudson.Read",
                "hudson.model.Item.Discover",
                "hudson.model.Item.Read",
                "hudson.model.View.Read"
            ],
            "id": "browse",
            "id": "browse"
        }
    ]
}
▼

Response model

Table 9. Groups response model
Element Type Description

groups

array of objects

List of all groups in the container.

name

string

Group name.

description

string

Description of the group (raw string - no spaces).

roles

array

List of roles assigned to this group.

roleAssignments

array

List of all group assignments including inherited ones. Each role assignment has a role field with role IDs.

users

array

List of users in a group.

members

The members attribute has been deprecated. Use either the users or groups attribute instead.

array

List of group members (user IDs, inner groups, etc).
Table 10. Roles response model
Element Type Description

roles

array of objects

List of available roles.

id

string

Description of the group (raw string - no spaces).

roles

array

Role identifier.

description

string

Role description.

url

string

URL of the role’s page.

grantedPermissions

array

Assigned permissions (including local and provisioned ones). All items contain the id field with the permission unique identifier and enabled field, which indicates that the permission can be assigned.

filterable

boolean

Indicates that the role is filterable.

Status and error codes

Table 11. Status and error codes
Code Description

200

Success

403

Not authorized. Missing required permissions.

404

The provided group, role, endpoint, or method cannot be found.

500

Server error.
Configuration as Code
Metrics