Managing Users and Permissions
1. Creating and Managing Users
| Property | Description | Default Value |
|---|---|---|
| user.id | Unique identifier for the user | Auto-generated |
| user.fullname | Full name of the user | Empty |
| user.email | Email address of the user | Empty |
| user.password | Password for user authentication | None |
Example: Creating a New User via REST API
curl -X POST "http://jenkins.example.com/securityRealm/createAccount" \
-d "username=john_doe" \
-d "password1=securePassword123" \
-d "password2=securePassword123" \
-d "full_name=John Doe" \
-d "email=john.doe@example.com"
Example: Assigning Roles to a User
import jenkins.model.Jenkins
import hudson.security.*
def jenkins = Jenkins.getInstance()
def user = jenkins.getUser("john_doe")
def roleMap = new RoleMap()
// Assign global role
roleMap.assignRole(new GlobalMatrixAuthorizationStrategy(), "admin", "john_doe")
// Save changes
jenkins.save()
Note: User permissions can be managed via the Jenkins UI under
Manage Jenkins > Manage Users.
Warning: Ensure that passwords meet complexity requirements to maintain system security.
2. Assigning User Roles
| Role | Description | Permissions | Assignment Method |
|---|---|---|---|
| Admin | Full system access and control | All actions, including managing users, plugins, and system configuration | Managed via Jenkins UI or API |
| Read-only User | Can view jobs and build results but not make changes | View jobs, builds, logs, and system status | Assigned via user management interface |
| Job Creator | Can create and configure jobs but not manage system settings | Create, configure, and run jobs; view builds | Configured in job-level security settings |
| Build Executor | Can trigger and execute builds | Run builds, view build results | Assigned via job or project permissions |
Example: Assigning Role via UI
1. Go to Jenkins Dashboard
2. Navigate to "Manage Jenkins" > "Manage Users"
3. Select a user and click "Assign Roles"
4. Choose roles from the list (e.g., Admin, Read-only User)
5. Save changes
Note: Role-based access control (RBAC) can be extended using plugins like
Role Strategy Plugin.
Warning: Admin role grants full system access. Ensure only trusted users have this role.
3. Configuring User Permissions
| Permission | Description | Scope | Assigned To |
|---|---|---|---|
| hudson.model.Hudson.Administer | Full administrative access to Jenkins | Global | System administrators |
| hudson.model.Item.Create | Ability to create new jobs or views | Global | Users with job creation rights |
| hudson.model.Item.Read | Read access to jobs and views | Job/View level | All users with read access |
| hudson.model.Item.Build | Trigger builds for jobs | Job level | Users who can build jobs |
| hudson.model.Item.Configure | Edit job configuration and settings | Job level | Job maintainers |
| hudson.model.Item.Delete | Delete jobs or views | Job/View level | Users with delete rights |
| hudson.model.Item.Workspace | Access to workspace files and directories | Job level | Users with workspace access |
| hudson.model.Run.Delete | Delete build history and artifacts | Job level | Users with run delete rights |
| hudson.model.Run.Update | Update or modify build results | Job level | Users with run update rights |
| hudson.model.Run.Artifact | Manage and download artifacts from builds | Job level | Users with artifact access |
Example: Assigning Permissions via Jenkins UI
# Navigate to Jenkins Dashboard
# Go to Manage Jenkins > Manage Users
# Select a user or group
# Click on "Assign Roles"
# Assign roles like "Admin", "Build User", etc.
Example: Using Jenkins Script Console to Set Permissions
import jenkins.model.*
import hudson.security.*
def jenkins = Jenkins.getInstance()
def acl = jenkins.getAuthorizationStrategy()
// Example: Granting 'hudson.model.Item.Read' to a user
def user = jenkins.getUser("john_doe")
def permission = hudson.model.Item.READ
// Apply the permission to the user
acl.add(permission, user)
Note: Permissions can be managed at both global and job levels. Ensure that permissions align with the principle of least privilege.
Warning: Administer permission grants full control over Jenkins. Use carefully and limit to trusted users only.
4. Setting Up User Groups
| Property | Description | Default Value | Notes |
|---|---|---|---|
| group.name | Name of the user group | None | Required field when creating a new group |
| group.description | Description of the group's purpose or role | Empty string | Optional but recommended for clarity |
| group.members | List of users assigned to the group | Empty list | Can include both direct and inherited members |
Example: Creating a User Group via Jenkins UI
1. Navigate to "Manage Jenkins" > "Manage Users"
2. Click on "Create Group"
3. Enter group name (e.g., "Developers")
4. Add members to the group
5. Save changes
Note: User groups in Jenkins can be managed through the web UI or via the REST API. Groups help simplify permission management by allowing you to assign roles and permissions to multiple users at once.
Comparison: User vs Group Permissions
- User Permissions: Applied directly to individual users, useful for unique access requirements.
- Group Permissions: Applied to a collection of users, ideal for standard roles like "Developers" or "QA Engineers".
5. Managing User API Tokens
| Property | Value | Description |
|---|---|---|
| jenkins.apiToken | string |
API token used for authentication with Jenkins |
Example: Generate API Token via CLI
curl -u "username:password" "http://jenkins-url/user/username/apiToken" --data "newToken=Generate+New+Token"
Example: Using API Token in Jenkinsfile
withCredentials([string(credentialsId: 'jenkins-api-token', variable: 'API_TOKEN')]) {
sh "curl -H 'Authorization: Bearer $API_TOKEN' http://jenkins-url/api/json"
}
Note: API tokens should be treated as secrets and never committed to version control.
Warning: Revoke API tokens if they are compromised or no longer needed.
6. Configuring User Build Permissions
| Permission | Description | Scope | Notes |
|---|---|---|---|
| Build | Allows triggering builds | Job-level | Can be restricted to specific jobs or folders |
| Read | Allows reading job configurations and build results | Job-level | Required for viewing builds and logs |
| Workspace | Allows access to the workspace directory | Job-level | Use with caution as it grants file system access |
| Configure | Allows modifying job configurations | Job-level | Can be used to grant admin-like access to specific jobs |
| Delete | Allows deleting jobs | Job-level | Highly sensitive permission, use carefully |
Example: Assigning Build Permissions to a User
curl -X POST "http://jenkins.example.com/job/my-job/permission/build" \
-u "admin:password" \
--data-urlencode "user=alice" \
--data-urlencode "permission=BUILD"
Note: Permissions can be assigned at the job level or globally. Job-level permissions take precedence over global ones.
Warning: Be cautious when granting
Delete permissions as it can lead to accidental job removal.
7. Setting Job-Level Permissions
| Permission | Description | Default Granted To | Notes |
|---|---|---|---|
| Job/Build | Allows building a job | Authenticated Users | Can be restricted to specific users or groups |
| Job/Configure | Allows configuring a job | Job owners and administrators | Can be restricted to specific users or groups |
| Job/Delete | Allows deleting a job | Administrators | Can be restricted to specific users or groups |
| Job/Discover | Allows discovering a job | Authenticated Users | Can be restricted to specific users or groups |
| Job/Move | Allows moving a job to another location | Administrators | Can be restricted to specific users or groups |
| Job/Workspace | Allows access to the workspace of a job | Job owners and administrators | Can be restricted to specific users or groups |
Example: Configure Job-Level Permissions via Jenkins UI
1. Go to the job configuration page.
2. Navigate to "Security" section.
3. Select "Enable project-based matrix authorization strategy".
4. Add users or groups and assign appropriate permissions.
Note: Permissions can be managed through the Jenkins UI or via configuration files using the
jenkins.model.JenkinsLocationConfiguration class.
Warning: Be cautious when granting
Job/Delete permission as it allows deletion of jobs.
8. Using Matrix Authorization
| Permission | Scope | Description |
|---|---|---|
| Overall Read | Global | Allows reading of Jenkins configuration and jobs |
| Overall Admin | Global | Full administrative access to Jenkins |
| Job Build | Job-specific | Allows triggering builds for a specific job |
| Job Configure | Job-specific | Allows modifying job configuration |
| Job Delete | Job-specific | Allows deleting jobs |
| Job Discover | Job-specific | Allows discovering jobs in a view |
| Job Workspace | Job-specific | Allows access to job workspace files |
| Run Delete | Job-specific | Allows deleting build runs |
| Run Update | Job-specific | Allows updating build runs |
| View Configure | View-specific | Allows configuring views |
| View Create | Global | Allows creating new views |
| View Delete | View-specific | Allows deleting views |
| View Read | View-specific | Allows reading view contents |
Example: Matrix Authorization Configuration
// Groovy script to configure matrix authorization
import jenkins.model.Jenkins
import hudson.security.*
def jenkins = Jenkins.getInstance()
def securityRealm = new HudsonPrivateSecurityRealm(false)
def authorizationStrategy = new GlobalMatrixAuthorizationStrategy()
// Add user permissions
authorizationStrategy.add(Jenkins.READ, "user1")
authorizationStrategy.add(Job.BUILD, "user2")
authorizationStrategy.add(Job.CONFIGURE, "user3")
// Apply the strategy
jenkins.setAuthorizationStrategy(authorizationStrategy)
jenkins.save()
Note: Matrix Authorization allows fine-grained control over permissions by assigning roles to users or groups.
Warning: Be cautious when granting Overall Admin rights as it provides complete control over Jenkins.
9. Configuring Anonymous Access
| Option | Values | Notes |
|---|---|---|
| hudson.security.AuthorizationStrategy$Unsecured | anonymous |
Allows unauthenticated access to Jenkins |
| jenkins.model.Jenkins.ANONYMOUS_READ | true |
Enables read access for anonymous users |
| jenkins.model.Jenkins.ANONYMOUS_WRITE | false |
Disables write access for anonymous users |
Example: Enable Anonymous Read Access
import jenkins.model.Jenkins
def jenkins = Jenkins.getInstance()
jenkins.setSecurityRealm(new hudson.security.HudsonPrivateSecurityRealm(false))
jenkins.setAuthorizationStrategy(new hudson.security.AuthorizationStrategy.Unsecured())
jenkins.save()
Note: Enabling anonymous access should be done with caution as it can expose sensitive data and operations.
10. Auditing User Activities
| Activity | Description | Logged By | Details |
|---|---|---|---|
| User Login | Successful login to Jenkins | Jenkins Core | Username, IP address, timestamp |
| User Logout | Explicit logout from Jenkins | Jenkins Core | Username, timestamp |
| Job Execution | Triggering or running a job | Jenkins Core | Job name, user, start time, duration |
| Configuration Changes | Modifying Jenkins or job configurations | Jenkins Core | User, config type, field changed, before/after values |
| Plugin Installation | Installing or updating plugins via UI or API | Jenkins Core | User, plugin name, version, timestamp |
| Role Assignment | Assigning or modifying user roles in the system | Jenkins Core | User, role name, timestamp |
Example: Configuring Audit Logging
// Jenkins Script Console or Groovy Post-Build Step
import jenkins.model.Jenkins
import hudson.security.AuthorizationStrategy
import org.acegisecurity.providers.dao.DaoAuthenticationProvider
def jenkins = Jenkins.instance
def auditLog = new File("/var/log/jenkins/audit.log")
// Enable audit logging
jenkins.setAuditLogEnabled(true)
jenkins.setAuditLogFile(auditLog)
// Configure log format (example)
jenkins.setAuditLogFormat("{user} performed {action} on {resource}")
Note: Audit logs can be configured via Jenkins configuration files or through the UI under
Manage Jenkins > Configure Global Security.
Warning: Ensure that audit logs are stored securely and rotated to prevent disk space exhaustion.