Authentication mapping

The operations center acts as a gateway between controllers, with requests from one controller to another controller routed through the operations center. Each request is tagged with the authentication that originated the request. Since different controllers can have different levels of trust, or use completely different authentication or authorization strategies, the operations center administrator must define the default authentication mapping strategy. Optionally, the operations center administrator can also define specific mapping strategies for individual controllers.

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

User requests driven via the UI: These requests are tagged with the authentication of the user making the request. An example is using the path browser to select a job to trigger.
Build driven requests: For a default installation of Jenkins or CloudBees CI, these requests are 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 between controllers are mapped twice. The first mapping converts the source controller’s authentication into the authentication for the operations center. The second mapping converts the operations center’s authentication into the authentication for the target controller.

Authentication mapping also takes place for requests originating from the operations center to controllers; such requests are mapped once.

Cluster-wide triggers and authentication mapping

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 permissions on the source job.
The authentication that the source job runs as must have Agent/Build permissions on at least one node that the source job can run on.
The mapped authentication that triggers the target job must have Job/Build permissions on the target job.
The authentication that the target job runs as must have Agent/Build permissions on at least one node that the target job can run on.

Cluster operations and authentication mapping

When running a cluster operation that has been configured as a job on the operations center, on a default installation of the operations center, the defined cluster operation runs 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.
Install the Authorize Project plugin on the operations center, and configure the job to run with the appropriate authentication.

Because ad-hoc cluster operations do not have a job where project authorization or control permissions can be configured, the operations center provides a built-in authorization for them. When running an ad-hoc cluster operation from the operations center, the authentication of the operation is always tagged with the authentication of the user that triggered it.

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 build authentication has the Job/Build permission, the credentials should include all credentials within the scope of the build job. Additionally, any credentials defined in that user’s personal credential store should also be included.

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.

Users must have this permission on a job (or Jenkins/Administer, which implies this permission) for their personal credential store to be available to the job when running as that user.

The Credentials/UseOwn permission is normally implied by the Job/Build permission. When you enable the -Dcom.cloudbees.plugins.credentials UseOwnPermission=true system property, the permission changes to being implied by the Jenkins/Administer permission. This allows the configuration to be effectively useful and enables users to trigger builds, but not use their own credentials.

-Dcom.cloudbees.plugins.credentials.UseItemPermission=true: Enables the configuration of the Credentials/UseItem permission.

Users must have this permission on a job (or Job/Configure, which implies this permission) for their personal credential store to be available to the job when running as that user.

If you enable either of these system properties on a controller, and you have configured the operations center to push RBAC to all controllers, CloudBees recommends enabling the system properties on the operations center and all controllers, to ensure role definitions are consistent.

Assuming the plugins using the credentials are using the credentials API correctly, enabling the Credentials/UseOwn and Credentials/UseItem permissions should 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).

Available authentication mapping strategies

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

With Do not enforce security settings on controllers, there is no guarantee that controllers are using the same security realm. As such, the username john may refer to different users. In some cases, it may be possible to map, for example, a user ID to/from an email address. Alternatively, there may be specific users the operations center administrator defines static mappings for.
With either Single Sign-On (security realm only) or Single Sign-On (security realm and authorization strategy), controllers are guaranteed to use the same security realm, and 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 controller.

The highest level of trust assumes that the SYSTEM authentication of the controller can act as SYSTEM on operations center.
An intermediate level of trust would be where the administration of a controller has been delegated to some of that controller’s users. Those users would thus have Jenkins/Administer on the 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 controller into ANONYMOUS, the operations center administrator can effectively remove the risk. Typically, with this mapping, the user authentication can be trusted, and idempotent mapping of usernames (if the security realms are equivalent) is appropriate.
The lowest level of trust is to map all authentication coming from the controller to the ANONYMOUS authentication. This level of trust is appropriate when the controller integrity is unknown to the operations center administrator. For example, where ad-hoc or experimental project teams wants their controller connected to operations center, and the operations center administrator does not know what plugins the team is installing.

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

This is because when build jobs running as SYSTEM have their authentication mapped through the operations center, it is converted to ANONYMOUS, and most likely not have the required permissions on the target controller.

Change the authentication mapping strategy

Authentication mapping is installed into the remoting channel as the very first step of establishing the remoting connection between the client and the 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 is only updated once the controller has been disconnected from and reconnected to the operations center.