Configuring RBAC with CasC for the operations center

Configure global Role-Based Access Control (RBAC) by adding the rbac.yaml file to the configuration bundle. Additionally, the authorizationStrategy attribute must be added to the jenkins.yaml file.

If the operations center items.yaml file is used to create controller items, the controller RBAC configuration is defined in the operations center items.yaml file.

Prerequisites

The following software and plugins must be installed to use RBAC with CasC:

If using CloudBees CI 2.289.3.2 - 2.303.3.3: CloudBees CasC API (Deprecated) plugin version, 1.14 - 1.41
If using CloudBees CI 2.319.1.5 or later: CloudBees CasC Client plugin, version 1.44 or later
Configuration as Code plugin
Operations Center Server Role Based Access Control plugin
CloudBees CasC Items API plugin

Required setup

Variable resolution: To use variables within the RBAC configuration file (rbac.yaml), configure variable resolution for items within a CasC bundle. For more information, see Configuring variable resolution for the RBAC configurations in a CasC bundle
User management: You must create users in your CloudBees CI system, either using an identity provider (like LDAP) or manually creating them. The examples below assume the users exist.
Item management: You must include an items.yaml file in the controller CasC bundle to apply RBAC groups and/or roles to items.

For more information, refer to Creating items with CasC for the operations center.

Configuring variable resolution for the RBAC configurations in a CasC bundle

CasC variable resolution refers to the ability to use variables within configuration files (such as rbac.yaml) to insert and substitute values during the creation of roles and groups in CloudBees CI. This feature allows administrators or non-administrators to manage configurations by using placeholders that can be replaced with actual values at runtime.

Variable resolution can be enabled or disabled for administrators and non-administrators, with the non-administrator setting being dependent on the administrator setting.

To configure variable resolution for items in a bundle by doing one of the following:

Configure the cascItemsConfiguration value in the jenkins.yaml file.
Enable the Enable or disable variable resolution for CasC administrator on the System Configuration page in the UI.

Variable resolution can also be configured for items imported from the items.yaml file. For more information, refer to Configure variable resolution for items in a CasC bundle.

Configure the `jenkins.yaml` file to handle variable resolution in the `rbac.yaml` file

Set variable resolutions for items in a bundle by configuring the cascItemsConfiguration value in the jenkins.yaml file.

unclassified:
  cascItemsConfiguration:
    variableInterpolationEnabledForAdmin: true (1)
    variableInterpolationEnabledForNonAdmin: true (2)▼

1	Set the `variableInterpolationEnabledForAdmin` value to `true` to allow administrators to use the variable resolution for items in the `rbac.yaml` file. The value is set to `false` by default.
2	Set the `variableInterpolationEnabledForNonAdmin` value to `true` to allow non-administrators to use the variable resolution for items in the `rbac.yaml` file. The value is set to `false` by default.

The variableInterpolationEnabledForNonAdmin setting is ignored if the variable resolution is not allowed (false) for administrators. For example:

If variableInterpolationEnabledForAdmin is false for administrators, then the variable resolution is also not allowed for non-administrators even if variableInterpolationEnabledForNonAdmin is set to true.
If variableInterpolationEnabledForAdmin is true for administrators, then variable resolution is allowed for non-administrators if variableInterpolationEnabledForNonAdmin is also set to true.

Configure the variable resolution in the controller

To enable variable resolution in controllers, configure the CasC Variable Resolution Configuration setting on the System configuration page.

To configure the variable resolution in the controller:

Navigate to CasC Variable Resolution Configuration.

Figure 1. Enable variable resolution

Select one of the following:

Enable or disable variable resolution for CasC administrator: This allows administrators to use the variable resolution for RBAC configurations imported from the rbac.yaml files. This setting is disabled by default.

Enable or disable variable resolution for non-administrator: This allows non-administrators to use the variable resolution for RBAC configuations imported from the rbac.yaml files. This setting is disabled by default.

The Enable or disable variable resolution for non-administrator setting is ignored if the variable resolution is not allowed (disabled) for administrators. For example:

If Enable or disable variable resolution for CasC administrator is disabled, then the variable resolution is also not allowed for non-administrators even if Enable or disable variable resolution for non-administrator is selected.
If Enable or disable variable resolution for CasC administrator is enabled, then variable resolution is allowed for non-administrators if Enable or disable variable resolution for non-administrator is also selected.

Select Save.

Escapte variable expressions

To prevent exposure of variable resolution values and potentially leaking secrets, the rbac.yaml file in a CasC bundle can escape variable expressions.

In the example below, the rbac.yaml contains a group with a display name ${ADMINISTRATORS_GROUP_NAME} and a role permission with the display name ${ADMINISTER_PERMISSION}.

removeStrategy:
  rbac: "sync"

groups:
  - name: "${ADMINISTRATORS_GROUP_NAME}"
    members:
      users:
        - "me@myorg.com"
    roles:
      - name: "administer"
        grantedAt: "current"
        propagates: "false"
roles:
  - name: "administer"
    filterable: "false"
    permissions:
      - "${ADMINISTER_PERMISSION}"▼

The varibles.yaml contains variables names variables ADMINISTRATORS_GROUP_NAME: Administrators and ADMINISTER_PERMISSION: hudson.model.Hudson.Administer.

variables:
  - ADMINISTRATORS_GROUP_NAME: Administrators
  - ADMINISTER_PERMISSION: hudson.model.Hudson.Administer▼

When the variable resolution setting is enabled in the UI or the jenkins.yaml file, CasC removes the circumflex (^) character and treats the following $ as plain text. In the UI, the first folder name is displayed without ^ character. For the second folder’s display name, the variable is substituted with its value.

Figure 2. Folder name without the ^ character when the variable resolution is enabled

When the variable resolution setting is disabled, CasC treats the displayName values as plain text in both cases. In the UI, the folder names displays all the characters of the configured strings including the circumflex (^).

Figure 3. Folder name with all characters displayed when the variable resolution is disabled

Exporting RBAC configurations

You can export Role-Based Access Control (RBAC) configurations from an existing operations center instance. For more information, refer to Exporting a CasC configuration.

The exported file should be used as a starting point, as it may require modifications and adjustments to make it production-ready.

Example CasC configuration bundle with RBAC

Example bundle.yaml file

id: "bundle-1"
version: "1"
apiVersion: "2"
description: "My CloudBees Configuration as Code (CasC) bundle"
jcasc:
  - "jenkins.yaml"
jcascMergeStrategy: "errorOnConflict"
plugins:
  - "plugins.yaml"
items:
  - "items.yaml"
rbac:
  - "rbac.yaml"
variables:
  - "variables.yaml"▼

Example jenkins.yaml file

jenkins:
  systemMessage: "Operations center configured using CloudBees CasC"
  numExecutors: 0
    securityRealm:
    ldap:
      configurations:
      - displayNameAttributeName: "cn"
        groupMembershipStrategy:
          fromGroupSearch:
            filter: "member={0}"
        groupSearchBase: "ou=Groups"
        inhibitInferRootDN: false
        managerDN: "cn=admin,dc=example,dc=org"
        managerPasswordSecret: ${LDAP_MANAGER_PASSWORD}
        rootDN: "dc=example,dc=org"
        server: "ldap://ldap-openldap:389"
        userSearchBase: "ou=People"
      disableMailAddressResolver: false
      groupIdStrategy: "caseInsensitive"
      userIdStrategy: "caseInsensitive"
  authorizationStrategy: "cloudBeesRoleBasedAccessControl"(1)
security:
  securitySettingsEnforcement:
    global:
      realmAndAuthorization:
        canCustomMapping: false
        canOverride: true
        defaultMappingFactory: "restrictedEquivalentRAMF"
  controllerExecutorCount:
    enforce:
      canOverride: false
      count: 0
cloudBeesCasCServer:
  visibility: true(2)
unclassified:
  cascAutoControllerProvisioning:
    provisionControllerOnCreation: true(3)
    fireAndForget: true(4)
    initialDelay: 15 (5)
    timeout: 600(6)
    duration: 60(7)
  location:
    url: https://operations-center:8888/(8)
  bundleStorageService:(9)
    activated: true
    activeBundle:
      name: "local-folder"
      retriever:
        SCM:
          scmSource:
            git:
              id: "acf88621-05a0-4d50-9166-d7767868dc43"
              remote: "https://github.com/my-company/repo.git"
              traits:
              - "gitBranchDiscovery"
    pollingPeriod: 0
    purgeOnDeactivation: false▼

1	Required to use CloudBees RBAC configured using CasC.
2	Optional if using the `items.yaml` file to create a controller item. When `visibility` is set to `true`, all CasC bundles that do not have an availability pattern defined can be used by any controller. This option provides more flexibility, but is less secure.
3	When `provisionControllerOnCreation` is set to `true`, all managed controller items are provisioned automatically after they are created using CasC.
4	When `fireAndForget` is set to `true`, the automatic provisioning process starts immediately, and does not wait for the controller to be connected.
5	The amount of time, in seconds, to wait before starting the automatic provisioning process.
6	The amount of time, in seconds, to complete the automatic provisioning process. If `fireAndForget` is set to `false`, this timeout may prevent queued provisioning requests from being blocked.
7	The provisioning duration, in seconds. After the initial delay, controllers are provisioned at random in batches of 20 controllers, for this time period. Increase this value to increase the amount of time between controller provisioning requests. If provisioning more than 20 controllers, the provisioning process will exceed the specified duration.
8	Required to create client controller items. The `url` is the operations center URL.
9	Required if using a local folder on the operations center server or an SCM tool as the Configuration as Code bundle location.

Example plugins.yaml file

plugins:
  # In CAP
  - id: "cloudbees-casc-client"
  - id: "cloudbees-casc-items-api"
  - id: "cloudbees-casc-items-commons"
  - id: "cloudbees-casc-items-server"
  - id: "configuration-as-code"
  - id: "operations-center-rbac"▼

Example items.yaml file

If creating a new controller item, refer to Creating a new controller item using CasC for the operations center.
By default, shared agent and shared cloud agent items are configured to be taken online. To configure the shared agent or shared cloud agent item to be taken offline, add the takeOnline property to the items.yaml and set it to false. For example: takeOnline: false.

removeStrategy:
  items: "none"
  rbac: "sync"

items:
  - kind: "folder"
    name: project-${team_group}
    displayName: "Project Alpha"
    description: "Project Alpha is going to change the world!"
    properties:
      - folderCredentialsProperty:
          folderCredentials:
            - credentials:
                - usernamePassword:
                    password: ${secret_location}
                    scope: GLOBAL
                    description: description
                    id: test-id
                    usernameSecret: false
                    username: test-user
              domain: {}
    groups:
      - name: "Project Alpha Developers"
        members:
          external_groups:
            - ldap-project-${team_group}
        roles:
          - name: "developer"
    items:(1)
      - kind: "folder"
        name: "project-alpha-tests"
        displayName: "Project Alpha Tests"
        items:
          - kind: "folder"
            name: "test-1"
          - kind: "folder"
            name: "test-2"
  - kind: "folder"
    name: "project-beta"
    displayName: "Project Beta"
    description: "Secret project! Only Admins can see this!"
    filteredRoles:(2)
      - "developer"
      - "browser"▼

1	Items can be nested within other items, enabling users to create a folder structure.
2	Roles can be filtered, for example to allow only administrators to view certain projects.

removeStrategy:
  items: "none"
  rbac: "sync"

items:(1)
  - kind: "folder"
    name: project-${team_group}
    displayName: "Project Alpha"
    description: "Project Alpha is going to change the world!"
    groups:
      - name: "Project Alpha Developers"
        members:
          external_groups:
            - ldap-project-${team_group}
        roles:
          - name: "developer"
    items:
      - kind: "folder"
        name: "project-alpha-tests"
        displayName: "Project Alpha Tests"
        items:
          - kind: "folder"
            name: "test-1"
          - kind: "folder"
            name: "test-2"
    properties:
      - envVars:
          vars:
            FOO: "BAR"
            BAR: "BAZ"
      - folderLibraries:
          libraries:
            - libraryConfiguration:
                implicit: false
                allowVersionOverride: true
                retriever:
                  modernSCM:
                    scm:
                      github:
                        traits:
                          - gitHubBranchDiscovery:
                              strategyId: 1
                          - gitHubPullRequestDiscovery:
                              strategyId: 1
                          - gitHubForkDiscovery:
                              trust:
                                gitHubTrustEveryone: {}
                              strategyId: 1
                        repoOwner: "company"
                        id: "library-id"
                        repository: "project-alpha"
                        configuredByUrl: true
                        repositoryUrl: "https://github.com/company/project-alpha"
                name: "my-library"
                includeInChangesets: true
      - folderCredentialsProperty:
          folderCredentials:
            - credentials:
                - usernamePassword:
                    password: ${secret_location}
                    scope: GLOBAL
                    description: description
                    id: test-id
                    usernameSecret: false
                    username: test-user
              domain: {}
      - itemRestrictions:
          allowedTypes:
            - "org.jenkinsci.plugins.workflow.job.WorkflowJob"
            - "hudson.matrix.MatrixProject"
            - "hudson.model.FreeStyleProject"
            - "com.cloudbees.hudson.plugins.modeling.impl.jobTemplate.JobTemplate"
            - "com.cloudbees.hudson.plugins.folder.Folder"
            - "com.cloudbees.hudson.plugins.modeling.impl.builder.BuilderTemplate"
            - "com.cloudbees.hudson.plugins.modeling.impl.auxiliary.AuxModel"
            - "org.jenkinsci.plugins.workflow.multibranch.WorkflowMultiBranchProject"
            - "com.cloudbees.hudson.plugins.modeling.impl.publisher.PublisherTemplate"
            - "com.cloudbees.hudson.plugins.modeling.impl.folder.FolderTemplate"
            - "com.infradna.hudson.plugins.backup.BackupProject"
          filter: true
    items:
      - kind: "freeStyle"
        name: "project-alpha-freestyle"
        displayName: "Freestyle job in the Project Alpha folder"
  - kind: "folder"
    name: "project-beta"
    displayName: "Project Beta"
    description: "Secret project! Only Admins can see this!"
    filteredRoles:(2)
      - "developer"
      - "browser"▼

1	Items can be nested within other items, enabling users to create a folder structure.
2	Roles can be filtered, for example to allow only administrators to view certain projects.

removeStrategy:
  items: "none"
  rbac: "sync"

items:
  - kind: "freeStyle"
    name: "project-alpha-freestyle"
    displayName: "Project Alpha Freestyle"
    description: "This is Project Alpha's Freestyle job!"
    disabled: false
    scm:
      gitSCM:
        extensions:
          - checkoutOption:
              timeout: 4
        gitTool: git
        userRemoteConfigs:
          - userRemoteConfig:
              name: "developer-a"
              credentialsId: "credentials-id"
              url: "git@github.com:company/project-alpha.git"
        browser:
          githubWeb:
            repoUrl: "https://github.com/company/project-alpha"
        doGenerateSubmoduleConfigurations: false
        branches:
          - branchSpec:
              name: "*/main"
    buildDiscarder:
      logRotator:
        artifactDaysToKeep: 3
        daysToKeep: 1
        numToKeep: 2
        artifactNumToKeep: 4
    scmCheckoutStrategy:
      standard: { }
    builders:
      - shell:
          command: "pwd"▼

removeStrategy:
  items: "none"
  rbac: "sync"

items:
  - kind: clusterOpProject
    name: "project-alpha-cluster-operations"
    displayName: "Project Alpha - Cluster operations"
    description: "These are Project Alpha's cluster operations!"
	disabled: false
    concurrentBuild: true
	operations:
      - masterClusterOperation:
          failureMode: IMMEDIATELY
          clusterOpSteps:
            - backupClusterOpStep:
                subjects:
                  - buildRecordSubject: {}
                  - jobConfigurationSubject: {}
                format:
                  zipFormat: {}
                retentionPolicy:
                  exponentialDecayRetentionPolicy: {}
                safeDelaySeconds: 10
                store:
                    s3Store:
                        bucketName: ' mybucket'
                        sse: true
                        bucketFolder: somefolder
                        credentialsId: 'my-aws-credentials-id'
                        region: us-east-1
          timeoutSeconds: 0
          itemSource:
              jenkinsRootItemSource: {}
          filters:
            - isMasterOnlineFilter: {}
          inParallel: 0
          noRetries: 0▼

removeStrategy:
  items: "none"
  rbac: "sync"

items:
  - kind: managedController
    displayName: "managed-controller-alpha"
    name: "managed-controller-alpha"
    description: "This is Project Alpha's managed controller!"
    groups:
      - name: "Project Alpha Developers"
        members:
          users:
            - developer-1
        roles:
          - name: developer
    properties:
      - configurationAsCode:
          bundle: bundle-1
      - healthReporting:
          enabled: false
      - owner:
          delay: 5
          owners: ''
      - envelopeExtension:
          allowExceptions: false
      - sharedConfigurationOptOut:
          optOut: false
      - licensing:
          strategy:
            perUserLicensingStrategy: {}
    configuration:
      kubernetes:
        allowExternalAgents: false
        replication:(1)
          config:
            maxReplicas: 5
            replicas: 3
            targetCPUUtilizationPercentage: 80
        terminationGracePeriodSeconds: 1200
        #image: cloudbees/mc-foo-image # uncomment to use a non-default image
        memory: 3072(2)
        fsGroup: '1000'
        cpus: 1.0
        readinessTimeoutSeconds: 5
        livenessInitialDelaySeconds: 300
        readinessInitialDelaySeconds: 30
        clusterEndpointId: default
        disk: 50
        readinessFailureThreshold: 100
        livenessTimeoutSeconds: 10
        domain: managed-controller-alpha
        livenessPeriodSeconds: 10
        javaOptions: -DfooSystemProperty="foo" -Dbar="bar"
        yaml: |-
          ---
          apiVersion: apps/v1
          kind: StatefulSet
          metadata:
            labels:
              my-label: my-value▼

1	Settings for a managed controller with CloudBees High Availability (HA), with 3 replicas, autoscaling enabled allowing up to 5 replicas, and a CPU threshold of 80% to trigger upscaling. `maxReplicas` and `targetCPUUtilizationPercentage` are not required if autoscaling is disabled. Then `maxReplicas` is set to `0` by default.
2	Some settings, such as controller memory, require the controller to be reprovisioned for the setting to take effect. If the managed controller is running in High Availability (HA) mode, these changes trigger a rolling restart without reprovisioning.

removeStrategy:
  items: "none"
  rbac: "sync"

items:
  - kind: clientController
    displayName: "client-controller-beta"
    name: "client-controller-beta"
    description: "This is Project Beta's client controller!"
    groups:
      - name: "Project Beta Developers"
        members:
          users:
            - developer-1
        roles:
          - name: developer
    properties:
    - configurationAsCode:
        bundle: bundle-2
    - healthReporting:
        enabled: false
    - owner:
        delay: 5
        owners: ''
    - envelopeExtension:
          allowExceptions: false
    - sharedConfigurationOptOut:
          optOut: false
    - licensing:
        strategy:
          perUserLicensingStrategy: {}
    - webSocket:
        enabled: true▼

removeStrategy:
  items: "none"
  rbac: "sync"

items:
  - kind: "sharedAgent"
    displayName: "Shared Agent for this cluster"
    name: "shared-agent-1"
    description: "Shared Agent for this cluster"
    remoteFS: "/tmp/remote"
    properties:
      - sharedAgent:
          customizers:
            - envVars:
                value:
                  SKIP_RELEASE: "TRUE"
                  JENKINS_VERSION: "2.303"
            - toolLocation:
                value:
                  - name: "git"
                    type: "git"
                    home: "/usr/local/git"
                  - name: "maven3"
                    type: "mvn"
                    home: "/usr/local/mvn"
    labels: "ubuntu"
    launcher:
      inboundAgent:
        webSocket: true
        workDirSettings:
          remotingWorkDirSettings:
            internalDir: "/path/to/directory"
            disabled: false
            failIfWorkDirIsMissing: true
            workDirPath: "/path/to/directory"
        agentStartupOptions: "-noCertificateCheck"
        vmargs: "-Xms2G -Xmx2G"
        tunnel: "192.1.1.45:22"
    mode: EXCLUSIVE
    numExecutors: 10
    retentionStrategy:
      sharedNodeRetentionStrategy: {}▼

removeStrategy:
  items: "none"
  rbac: "sync"

items:
  - kind: "sharedCloud"
    displayName: "Shared Cloud Agent for this cluster"
    name: "shared-cloud-1"
    description: "Shared Cloud Agent for this cluster"
    properties:
      - sharedCloud:
          customizers:
            - envVars:
                value:
                  SKIP_RELEASE: "TRUE"
                  JENKINS_VERSION: "2.303"
            - toolLocation:
                value:
                  - name: "git"
                    type: "git"
                    home: "/usr/local/git"
                  - name: "maven3"
                    type: "mvn"
                    home: "/usr/local/mvn"
    cloud:
      inboundAgents:
        mode: EXCLUSIVE
        numExecutors: 10
        remoteFS: "/path/to/directory"
        labels: "ubuntu"
        launcher:
          inboundAgent:
            webSocket: true
            workDirSettings:
              remotingWorkDirSettings:
                internalDir: "/path/to/directory"
                disabled: false
                failIfWorkDirIsMissing: true
                workDirPath: "/path/to/directory"
            agentStartupOptions: "-noCertificateCheck"
            vmargs: "-Xms2G -Xmx2G"
            tunnel: "192.1.1.45:22"▼

removeStrategy:
  items: "none"
  rbac: "sync"

items:
  - kind: backupAndRestore
    name: project-alpha-backup
    displayName: "Project Alpha backup"
    description: "This is Project Alpha's backup job!"
    buildersList:
      - backupBuilder:
          subjects:
            - buildRecordSubject:
                excludes: foo
            - jobConfigurationSubject:
                excludes: bar
            - systemConfigurationSubject:
                excludes: baz
                omitMasterKey: true
          format:
            zipFormat: {}
          exclusive: false
          store:
            s3Store:
              bucketName: bucket
              sse: true
              bucketFolder: bucketFolder
              credentialsId: testCredential
              region: us-east-1
          retentionPolicy:
            exponentialDecayRetentionPolicy: {}
          safeDelaySeconds: 42
    label: agent-for-backup
    triggers:
      - cron:
          spec: 0 0 * * *
    buildDiscarder:
      logRotator:
        numToKeep: 5▼

Example rbac.yaml file

removeStrategy:
  rbac: "SYNC"(1)

roles:
  - name: administer
    permissions:
      - hudson.model.Hudson.Administer
  - name: developer
    permissions:
      - hudson.model.Hudson.Read
      - hudson.model.Item.Read
      - hudson.model.Item.Create
      - hudson.model.Item.Configure
    filterable: "true"(2)
  - name: browser
    permissions:
    - hudson.model.Hudson.Read
    - hudson.model.Item.Read
    filterable: "true"
  - name: authenticated
    filterable: "true"
    permissions:
    - hudson.model.Hudson.Read

groups:
  - name: Administrators
    roles:
      - name: administer
        grantedAt: current(3)
    members:
      users:
        - admin
      external_groups:
        - ${external_admin_group}
  - name: Developers
    roles:(4) (5)
      - name: developer
    members:
      users:
        - developer
      internal_groups:
        - "some-other-group"
      external_groups:
        - "ldap-cb-developers"
  - name: Browsers
    roles:
      - name: browser
    members:
      users:
        - read▼

1	For security reasons, SYNC is here to remove groups/roles from CloudBees Continuous Integration when they are removed from this file.
2	If filterable is not included, the default value is “false”.
3	Other options that could be used here include: "child" or "grandchild".
4	If propagates is not included, the default value is "true".
5	If grantedAt is not included, the default value is "current".

Example variables.yaml file

  variables:
    - key: value
    - long_text: |-
        multiline string without
        quotes
    - another: text
    - team_name: Team Alpha
    - team_group: alpha
    - external_admin_group: ldap-cb-admins▼