Troubleshooting Pipelines

Authentication mapping

5 minute readSecurity

operations center acts as a gateway between each of the client controllers. Any request from one client controller to another client controller will be routed through operations center. Each request will be tagged with the authentication that originated the request. Because different client controllers can have different levels of trust or indeed could use completely different authentication or authorization strategies it is necessary for the operations center administrator to define the default authentication mapping strategy and optionally define specific mapping strategies for individual client controllers.

In general, requests from a client controller have one of two origins:

  • User requests driven via the UI. These requests will be tagged with the authentication of the user making the request. An example of one of these requests would be using the path browser to select a job to trigger.

  • Build driven requests. For a default installation of Jenkins or CloudBees CI these requests will be tagged with the SYSTEM authentication. The authentication of a build can be modified. For example the Authorize Project plugin allows jobs to be configured to run as: ANONYMOUS, a specific user, or the user who triggered the build.

Requests from a client controller to another client controller will be mapped twice. The first mapping will be to convert the source client controller’s authentication into the authentication for operations center. The second mapping will be to convert operations center’s authentication into the authentication for the target controller.

Cluster-wide Triggers and Authentication Mapping

To be able to trigger a job on a target controller, the user and the mapped authentication must have the required permissions:

  • The user triggering the source job must have Job/Build on source job

  • The authentication the source job run as must have Slave/Build on at least one Node that the source job can run on

  • The mapped authentication that triggers the target job must have Job/Build on the target job

  • The authentication the target job run as must have Slave/Build on at least one Node that the target job can run on

Authentication mapping also takes place for requests originating from operations center to client controllers, such requests will be mapped once.

Cluster Operations and Authentication Mapping

When running a cluster operation that has been configured as a job on operations center, on a default installation of operations center the defined cluster operation will run using the SYSTEM authentication. It is expected that the operations center administrator will either: * restrict the BUILD permission on the cluster operation to those users that are permitted to perform the operation; or * install the Authorize Project plugin on operations center and configure the job to run with the appropriate authentication

Because ad-hoc cluster operations do not have a ‘job’ against which to either configure the project authorization or control the permissions operations center provides a built-in authorization for ad-hoc cluster operations. When running an ad-hoc cluster operations from operations center the authentication of that ad-hoc cluster operation will always be tagged with the authentication of the user triggering the ad-hoc operation.

Authorize Project plugin and Credentials

When using the Authorize Project plugin the credentials available to the job may be different from when the job runs as SYSTEM.

By default, if the authentication that the build is running as has the Job/Build permission then the credentials should include all those credentials within the scope of the build job and also include any credentials defined in that user’s personal credential store.

There are two system properties that enable additional permissions to control the credentials available:

  • -Dcom.cloudbees.plugins.credentials.UseOwnPermission=true enables the configuration of the Credentials/UseOwn permission. A user must have this permission on a job (or Jenkins/Administer which implies this permission) in order for their personal credential store to be available to the job when running as that user.

    Credentials/UseOwn permission is normally implied by the Job/Build permission. When you enable configuration of this permission using the -Dcom.cloudbees.plugins.credentials.UseOwnPermission=true system property the permission changes to being implied by the Jenkins/Administer permission in order to allow the configuration to be effectively useful and enable the ability to let a user trigger a build but not use their own credentials.
  • -Dcom.cloudbees.plugins.credentials.UseItemPermission=true enables the configuration of the Credentials/UseItem permission. A user must have this permission on a job (or Job/Configure which implies this permission) in order for the credential stores within scope of the job to be available when the job is running as that user.

If you enable either of these system properties on a client controller and you have configured operations center to push RBAC to all client controllers, it is recommended that you enable the system properties on operations center and all client controllers so that the role definitions will be consistent.

Enabling the Credentials/UseOwn and Credentials/UseItem permissions should (assuming that the plugins using the credentials are using the credentials API correctly) allow fine grained control over what credentials a job has access to when using the Authorize Project plugin (or any other plugin that provides authorization for jobs)

The available authentication mapping strategies depends on how you have configured the Client controller security on operations center:

  • With Do not enforce security settings on controllers there is no guarantee that the client controller is even using the same security realm. As such a username john may refer to different users. In some cases it may be possible to map, for example, an user-id to/from an email address. Alternatively there may be a few specific users that the operations center administrator is prepared to define static mappings for.

  • With either Single Sign-On (security realm only) or Single Sign-On (security realm and authorization strategy) we have a guarantee that the client controller is using the same security realm and thus the usernames can be mapped.

The strategies are then broken down in terms of the level of trust the operations center administrator is prepared to forward to the client controller.

  • The highest level of trust assumes that the SYSTEM authentication of the client controller can act as SYSTEM on operations center.

  • An intermediate level of trust would be where the administration of a client controller has been delegated to some of that client controller’s users. Those users would thus have Jenkins/Administer on the client controller but not on operations center. As such they could use their super-user permissions as a route to gain additional permissions on operations center. By selecting an authentication mapping that maps SYSTEM when coming from the client controller into ANONYMOUS the operations center administrator can effectively remove the risk. Typically with this mapping the user authentication can be trusted and thus an idempotent mapping of usernames (if the security realms are equivalent) would be appropriate.

  • The lowest level of trust is to map all authentication coming from the client controller to the ANONYMOUS authentication. This level of trust is appropriate when the client controller integrity is unknown to the operations center administrator. For example, where a skunkworks project team wants their client controller connected to operations center and the operations center administrator does not know what plugins that team will be installing.

When selecting any strategy other than the highest level of trust, it is almost guaranteed that you will need to install the Authorize Project plugin or an equivalent plugin on all client controllers as well as on operations center if any inter-client controller operations will be required.

This is because the build jobs will be running as SYSTEM and when their authentication is mapped through operations center that will be converted to ANONYMOUS which more than likely does not have the required permissions on the target client controller.

Changing the authentication mapping strategy

The authentication mapping is installed into the remoting channel as the very first step of establishing the remoting connection between the client and operations center.

For security reasons the authentication mapping of a connection cannot be updated while the connection is active.

If you reconfigure the authentication mapping, the new authentication mapping will only be picked up once the client controller has been disconnected from and reconnected to operations center.