You can manage service accounts and their tokens using the CloudBees CI UI. The UI provides an interface to create service accounts, generate tokens, manage group memberships, and view token details.
To create a service account in the UI:
-
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. -
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
dfor days,hfor hours, or leave blank for permanent tokens.Once the token expires, it will still be listed, but may no longer be used to authenticate. You must create a fresh 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. -
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 can perform any operations that a human user in that group can perform. 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 an 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
whoamicommand 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
whoAmIendpoint 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-accountauthority, 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-jobin themy-team/devfolder 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-jobin themy-team/devfolder 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"
-
|
Manage service accounts and tokens in the UI
You can create multiple tokens for a single service account (for example, with different expiration dates). The main reason to create multiple tokens temporarily is to allow token rotation without downtime. All tokens authenticate interchangeably as the same service account.
To view all tokens 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.
All tokens for the service account are listed 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. -
To delete a token, select next to the token.
-
To delete a service account and all its tokens, select Delete service account in the left pane.
-