Get started with CloudBees CI service accounts

You can manage service accounts and their authentication methods, including tokens and OpenID Connect (OIDC) configurations, using the CloudBees CI UI. The UI provides an interface to create service accounts, generate tokens and OIDC configurations, manage group memberships, and view authentication details.

Create a service account

Create a service account to allow automated systems to authenticate and perform actions on CloudBees CI without requiring a human user account.

To create a service account:

Navigate to where you want to create the service account:
- For a root-scoped service account: From the operations center or controller dashboard, select in the upper-right corner, and then select Service Accounts.
- For an item-scoped service account: Navigate to the desired item (for example, a folder), and then select Service Accounts from the left pane.
Select + New Service Account.
Enter a Name for the service account, and then select OK to create the service account.

Do not use spaces or special characters in the service account name.

Add a token to a service account

Add a token to a service account to allow automated systems to authenticate using HTTP Basic authentication.

To add a token to the service account:

Navigate to the service account:
- For a root-scoped service account: From the operations center or controller dashboard, select in the upper-right corner, and then select Service Accounts.
- For an item-scoped service account: Navigate to the desired item (for example, a folder), and then select Service Accounts from the left pane.
Select New token.
(Optional) Enter a Description to document the token’s purpose and storage location (for example, production deployment script).
Enter an Expiration date (default is 30 days). Use d for days, h for hours, or leave blank for permanent tokens.

Once the token expires, it is still listed, but can no longer be used to authenticate. You must create a new token, and the current token cannot be renewed.

Select OK to create the token.

The token is created and displayed in HTTP Basic authentication format as:

<service-account-name>:cloudbees_ci_sa_<token-value>

The password (secret) portion is always prefixed with cloudbees_ci_sa_. The remainder is a random hexadecimal string.

Service account tokens use standard HTTP Basic authentication and are compatible with any tool, plugin, or library that supports this mechanism, such as Parameterized Remote Trigger plugin. For usage examples, refer to Service accounts CLI and Service account API endpoints.

Copy the token and store it in a secure location for later use.

Once you leave the page, you cannot view or copy the token again.

You can create multiple tokens for a single service account, for example with different expiration dates. The primary use case is token rotation without downtime, since all tokens authenticate interchangeably as the same service account.

Add an OIDC configuration to a service account

OIDC authentication uses a temporary JSON Web Token (JWT) from an OIDC identity provider (IdP) to authenticate a service account without requiring a long-lived token.

A service account supports multiple OIDC configurations, but CloudBees recommends defining a separate service account for each IdP or system if you want to manage permissions for each independently.

Prerequisites for OIDC authentication

OIDC authentication eliminates the need to manage long-lived tokens and the associated risks. It requires the following:

The system or script using the service account must be able to receive a temporary JWT identity token from an OIDC identity provider (IdP).
The service account must be configured to expect JWTs from the OIDC IdP, including specific claim values such as issuer, subject, and audience.
The IdP must:
- Be accessible from the CloudBees CI network, so the operations center or controller receiving the authenticated request can contact the IdP to verify the JWT.
- Support OpenID Connect Discovery. For a JWT with "iss":"https://idp.example.com", the IdP must serve a JSON document at https://idp.example.com/.well-known/openid-configuration containing a jwks_uri field pointing to the public key used to verify the JWT’s signature.

If these conditions are met, OIDC authentication is simpler to manage than tokens, because there are no secrets to store or rotate, and no special lifecycle considerations when applying bundle updates.

Supported systems for OIDC authentication

CloudBees CI supports OIDC authentication from any IdP that meets the prerequisites. The following systems are common, tested examples:

One or more controllers with the OpenID Connect Provider plugin installed. These can be CloudBees CI or Jenkins controllers in an unrelated CloudBees CI installation. For usage details, refer to the Jenkins OpenID Connect Provider plugin documentation.

A controller can also authenticate to itself using OIDC, for example, to modify its own CasC configuration through the REST API from a Pipeline build.
GitHub Actions workflows.
A Kubernetes Pod using service account token projection.

OIDC authentication for service accounts is machine-to-machine authentication and is distinct from interactive user authentication through a web browser, which is the original use case for OIDC.

Configure the OIDC configuration

Use the CloudBees CI UI to configure the issuer, subject, and audience claim values for the OIDC configuration.

To add an OIDC configuration to a service account:

From the operations center dashboard, select in the upper-right corner, select Service Accounts, enter a space-separated list of allowed domains in the OIDC issuer domains field, and then select Save.
Navigate to the service account:
- For a root-scoped service account: From the operations center or controller dashboard, select in the upper-right corner, and then select Service Accounts.
- For an item-scoped service account: Navigate to the desired item (for example, a folder), and then select Service Accounts from the left pane.
Select New OpenID Connect.
Enter the following information for the OIDC configuration:
- Issuer: The iss claim value expected in the JWT, which must match the IdP’s issuer URL. The issuer URL must use the https scheme (for example, https://idp.example.com).
- Subject: The sub claim value expected in the JWT, as defined by the IdP (for example, my-system:my-workflow).
- Audience (Optional): The aud claim value expected in the JWT. Defaults to the URL of the service account itself (for example, https://cloudbees-ci.example.com/cjoc/serviceAccounts/bot/). Specify a different value only if your IdP does not allow you to control the aud claim.
Select OK to save the OIDC configuration.

Unlike tokens, OIDC configurations do not contain secrets. After saving, the issuer, subject, and audience are displayed on the service account details page under OpenID Connect configurations.

Add a service account to a group

Add a service account to a group to grant it permissions to perform actions on CloudBees CI.

To add a service account to a group:

Navigate to where you want to add the service account to a group:
- For a root-scoped group: From the operations center or controller dashboard, select in the upper-right corner, and then select Groups.
- For an item-scoped group: Navigate to the desired item (for example, a folder), and then select Groups from the left pane.

Select a group to add the service account to.

An item-scoped service account can only be added to groups defined on that folder or its descendant jobs and folders. It cannot be added to groups defined at root scope or on ancestor or sibling folders.

Select Add service account, and then select the service account.

If all available service accounts are already members of the group, or if no service accounts have been created, the Add service account option is not visible.

Select OK to add the service account to the group.

A service account added to a group has the same permissions as a human user in that group. Like a human user, it requires the Overall/Read permission. To operate on jobs or other items, it requires the Job/Read permission on the relevant jobs.

Without adding the service account to a Role-Based Access Control (RBAC) group, it can authenticate but cannot perform any actions. The service account’s effective permissions are the union of permissions from all roles in all groups it belongs to.
Item-scoped service accounts are automatically granted Overall/Read and Job/Read permissions on their containing item and parent folders. For more information, refer to Configure item-scoped permissions.

Verify the service account can authenticate using the Jenkins CLI or REST API.
- Use the Jenkins CLI whoami command to verify authentication:
  java -jar jenkins-cli.jar -auth my-team/dev/bot:cloudbees_ci_sa_abc123def456789012345678901234ef -s https://my-operations-center.com/cjoc/ who-am-i
  ▼
- Use the REST API whoAmI endpoint to verify authentication:
  curl -u "my-team/dev/bot:cloudbees_ci_sa_abc123def456789012345678901234ef" "https://my-operations-center.com/cjoc/whoAmI/api/json?tree=name,authorities"
  ▼
  This displays the service account name and the cloudbees-ci-service-account authority, confirming it is a service account, rather than a human user.

Once authenticated, you can use the service account to trigger builds using the Jenkins CLI or REST API.

For example, to trigger a build of my-job in the my-team/dev folder using the CLI:

java -jar jenkins-cli.jar -auth my-team/dev/bot:cloudbees_ci_sa_abc123def456789012345678901234ef -s https://my-operations-center.com/cjoc/ build my-team/dev/my-job▼

For example, to trigger a build of my-job in the my-team/dev folder using the REST API:

curl -X POST -u "my-team/dev/bot:cloudbees_ci_sa_abc123def456789012345678901234ef" "https://my-operations-center.com/cjoc/job/my-team/job/dev/job/my-job/build?delay=0sec"▼

POST requests to REST API endpoints do not require a CSRF crumb when authenticated with service account tokens.
For programmatic CLI workflows and automation, refer to Service accounts CLI.
For programmatic REST API workflows and automation, refer to Service account API endpoints.

Manage service accounts

From the service account details page, you can view and manage tokens and OIDC configurations.

To view all tokens and OIDC configurations for a service account:

Navigate to the service account:
- For a root-scoped service account: From the operations center or controller dashboard, select in the upper-right corner, and then select Service Accounts.
- For an item-scoped service account: Navigate to the desired item (for example, a folder), and then select Service Accounts from the left pane.
Select the service account name to open its details page.
- Tokens are listed under Tokens with their metadata, including description, created date, creator, expiration date, and the last time the token was used.
  
  Dates are shown relative to the current time. Hover over the date to display the absolute date in your local time zone.
- OIDC configurations are listed under OpenID Connect configurations with their issuer, subject, audience, and the last time the configuration was used.
To delete tokens, OIDC configurations, or the service account:
- To delete a token, select next to the token.
- To delete an OIDC configuration, select next to the configuration.
- To delete a service account and all its tokens and OIDC configurations, select Delete service account in the left pane.