Bind an OAuth client credential to a user

A Jenkins OAuth client credential represents an OAuth client registered with the CloudBees OAuth Authorization Server plugin's authorization server. When a client uses this credential with the client_credentials grant, no person signs in, so the credential must name the identity that the resulting token acts as, and anyone holding the credential can act as that identity.

Enabling client_credentials grants the credential’s holder the right to act as the bound Jenkins user with no sign-in and no consent. Bind a dedicated account, never a human administrator, and protect the credential’s secret or signing key as you would a password.

Prerequisites

Before you begin, ensure you have:

The CloudBees OAuth Authorization Server plugin, installed on the operations center and the instance restarted after installation.
The CloudBees OAuth Resource Server plugin, installed on the operations center and on every controller that should accept this credential’s tokens, and each instance restarted after installation.

The target Jenkins user must already exist in CloudBees CI.

Bind the credential

Choose one of the following configuration methods:

Bind the credential using the UI
Bind the credential using Configuration as Code

Bind the credential using the UI

To create a new Jenkins OAuth client credential and bind it to a Jenkins user:

In the operations center, select in the upper-right corner to navigate to the Manage Jenkins page, and then select Credentials.
Select +Add Credentials to open the Add Credentials form.
Select Jenkins OAuth client, and then select Next.

Specify the following fields:

Scope: Select System (Jenkins and nodes only).
ID: Optionally, enter a unique ID for this credential (for example, ci-automation-client).
Description: Enter a name that identifies this credential in the credentials list (for example, Automation client for CI scripts).
Token endpoint auth method: Select the method your client uses to authenticate with the token endpoint.
Client secret: If you selected client_secret_basic or client_secret_post for Token endpoint auth method, enter the client secret.
JWKS or JWKS URL: If you selected private_key_jwt for Token endpoint auth method, enter the client’s public keys in JWKS, or enter a URL in JWKS URL that the server can fetch them from. Specify either JWKS or JWKS URL, but not both; a client carrying both is rejected.

Grant types: Select client_credentials to bind this credential to a Jenkins user.

A credential cannot enable both the authorization_code and client_credentials grants at the same time. If you need both an interactive sign-in flow and a machine-to-machine flow, use two separate credentials.

Bound Jenkins user: Enter the Jenkins user that this credential should act as when using the client_credentials grant.

Select Create.

If the bound user is later deleted or disabled, every token request for this credential fails with invalid_grant. Re-bind the credential by editing it, updating Bound Jenkins user, and then selecting Save.

Bind the credential using Configuration as Code

In the Configuration as Code (CasC) bundle’s jenkins.yaml file, the Jenkins OAuth client credential is configured under credentials.system.domainCredentials using the jenkinsOAuthClientCredentials key.

Set boundUserId to the Jenkins user that the credential acts as:

credentials:
  system:
    domainCredentials:
      - credentials:
          - jenkinsOAuthClientCredentials:
              scope: SYSTEM
              id: "ci-automation-client"
              description: "Automation client for CI scripts"
              clientSecret: "${AUTOMATION_CLIENT_SECRET}"
              tokenEndpointAuthMethod: "CLIENT_SECRET_POST"
              grantClientCredentials: true(1)
              boundUserId: "bot"(2)▼

1	Enables the `client_credentials` grant for this credential.
2	Binds the credential to the `bot` Jenkins user.

Verify the binding

After requesting a token for the credential with the client_credentials grant, decode the access token’s payload (the middle, base64url-encoded segment of the JWT) and confirm that its sub claim matches the identity you bound:

echo '<token-payload-segment>' | base64 --decode▼

The sub claim is the Jenkins user ID.

Enable OAuth authentication for the CloudBees CI MCP Router describes one consumer of this credential type, the CloudBees CI MCP Router’s own OAuth setup.