Roles & Matrix Authorization
Role-based and matrix authorization control exactly which users can view, build, or configure jobs.
By default a Jenkins admin can do everything. In a team you want finer control — that is what authorization strategies provide.
Matrix authorization
The Matrix Authorization plugin shows a grid of users/groups against permissions (Read, Build, Configure, Delete, Administer). You tick the boxes to grant exactly what each user needs.
Role-based strategy
The Role-based Authorization Strategy plugin lets you define named roles (like developer or viewer) with a set of permissions, then assign users to roles. This scales better than per-user grids.
Principle of least privilege
Give each person the minimum access they need. Most developers only need Read and Build, not Administer.
Example
# Manage Jenkins > Security > Authorization
#
# Matrix-based security example:
#
# Read Build Configure Administer
# admin X X X X
# developer X X X
# viewer X
#
# Or use Role-Based Strategy for reusable roles.When to use it
- A Jenkins admin assigns a 'developer' role that allows viewing and triggering builds but blocks access to Manage Jenkins.
- A contractor is given read-only access to a single folder using Matrix Authorization so they can monitor builds without modifying them.
- An auditor account is created with Job/Read permission only so it can view build history but not trigger or configure any jobs.
More examples
Matrix authorization config snippet
Configures Project Matrix Authorization via JCasC to grant different permissions to developer and admin groups.
# JCasC (Jenkins Configuration as Code) snippet
security:
authorizationStrategy:
projectMatrix:
permissions:
- 'Overall/Read:authenticated'
- 'Job/Build:developers'
- 'Job/Read:developers'
- 'Job/Configure:admins'
- 'Overall/Administer:admins'Role-based strategy via JCasC
Defines developer and admin roles with specific permissions and assigns users to them via JCasC.
# Requires Role Strategy Plugin
security:
authorizationStrategy:
roleBased:
roles:
global:
- name: developer
permissions:
- 'Job/Build'
- 'Job/Read'
assignments:
- 'alice'
- 'bob'
- name: admin
permissions:
- 'Overall/Administer'
assignments:
- 'jenkins-admin'Check current user permissions via REST
Calls the whoAmI REST endpoint to verify what permissions a specific user token has on the Jenkins instance.
# Check which permissions the current token has
curl -s \
'http://localhost:8080/whoAmI/api/json?pretty=true' \
--user alice:$TOKEN
Discussion