How to Use Matrix Authorization in Jenkins for Access Control

To use Matrix Authorization in Jenkins, enable it under Manage Jenkins > Configure Global Security by selecting Matrix-based security. Then, add users or groups and assign specific permissions by checking boxes in the matrix grid to control their access.

Syntax

The matrix authorization in Jenkins is configured through a permission grid where you assign permissions to users or groups. The main parts are:

• Users/Groups: Add the user or group name to assign permissions.
• Permissions: Checkboxes for each permission like Overall Read, Job Build, View Read, etc.
• Save: Apply the changes to enforce the permissions.

This setup is done in the Jenkins UI under Manage Jenkins > Configure Global Security.

text

Manage Jenkins > Configure Global Security > Authorization > Matrix-based security

Add user/group:
  - Enter username or group name
  - Click 'Add'

Assign permissions:
  - Check boxes for desired permissions per user/group

Save changes

Example

This example shows how to give user alice permission to build jobs and read views, but not administer Jenkins.

text

1. Go to Jenkins dashboard.
2. Click 'Manage Jenkins' > 'Configure Global Security'.
3. Under 'Authorization', select 'Matrix-based security'.
4. In 'User/group to add', type 'alice' and click 'Add'.
5. For 'alice', check the boxes:
   - Overall Read
   - Job Build
   - View Read
6. Leave 'Administer' unchecked.
7. Click 'Save'.

Output

User 'alice' can now build jobs and view content but cannot change Jenkins settings.

Common Pitfalls

Common mistakes when using matrix authorization include:

• Not granting Overall Read permission, which can lock users out completely.
• Forgetting to add the Anonymous user if you want public access.
• Assigning too many permissions accidentally, giving users admin rights unintentionally.
• Not saving changes after editing the matrix.

Always double-check permissions and test with a non-admin user.

text

Wrong:
- Forgetting to check 'Overall Read' for a user.

Right:
- Always check 'Overall Read' to allow basic access.

Wrong:
- Giving 'Administer' permission to all users.

Right:
- Restrict 'Administer' to trusted admins only.

Quick Reference

Permission	Description
Overall Read	Allows basic access to Jenkins UI
Administer	Full control over Jenkins configuration
Job Build	Permission to start builds
Job Configure	Permission to change job settings
View Read	Permission to see views
Credentials Create	Permission to add credentials

Key Takeaways

Enable matrix authorization under Manage Jenkins > Configure Global Security.

Add users or groups and assign only needed permissions using the matrix grid.

Always grant Overall Read to users to avoid lockout.

Restrict Administer permission to trusted users only.

Save changes and test permissions with non-admin accounts.