Authentication mapping

The operations center acts as a gateway between controllers, with requests sent from one controller to another controller and are 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.

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 you run 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 restrict the BUILD permission on the cluster operation to those users that are permitted to perform the operation.

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 who triggered it.

Credentials

By default, if the build authentication has the Job/Build permission, the credentials should include all of the 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 that 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 that 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.

If the plugins that use the credentials and use 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 any 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 that 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 the 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 the operations center. As such, they could use their super-user permissions as a route to gain additional permissions on the operations center. If you select an authentication mapping that maps SYSTEM when coming from the controller into ANONYMOUS, the operations center administrator can remove the risk. 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 of the authentications that come 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, when the ad-hoc or experimental project teams want their controller connected to the operations center, and the operations center administrator does not know what plugins the team is installing.

When you select any strategy other than the highest level of trust, you may need to install a plugin that provides authorization for jobs on all of the controllers, and 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 may 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.