Skip to main content

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.

Was this article helpful?