Skip to content

ServiceAccount

A ServiceAccount is an identity for something that is not a person: a CI job, a script, a bot, a GitOps operator pulling a Release, any client that talks to ConfigHub without someone signing in. It has credentials of its own and permissions of its own, and what it does is attributed to it.

A ServiceAccount belongs to an Organization, not to a Space. Any member of the Organization can create one. Creating one also creates the User it acts as, which is what other entities' Permissions and Groups name when they grant it access, and what revisions and the event log record when it changes something.

Role and permissions

A ServiceAccount has an organization role like any member, set with --org-role when it is created or updated and never higher than the role of whoever sets it. It defaults to none: no access at all until something is granted. That is the right default for automation, because its access is then exactly the list of grants, and nothing more.

Grants name it as serviceaccount:<name> in the --permission flag of any create or update command, on a Space for everything in it or on a single entity:

cub space update --permission UseChildren:serviceaccount:deploy-bot payments-prod
cub target update --space platform cluster --permission ViewChildren:serviceaccount:argo

It can also be added to a Group, and is then granted whatever the Group is granted. Authorization describes the roles and the permission categories.

Permissions on the ServiceAccount entity are about who may change and use the account, not about what the account may do. The creator is granted Manage, and the account is granted View on itself. One category exists only here: Impersonate, which is required to register the keys and issue the tokens that authenticate as the account. Manage does not include it, and only someone who holds it can grant it, so administering a ServiceAccount does not by itself let anyone act as it.

Credentials

ConfigHub never generates or stores a secret for a ServiceAccount. There are two kinds of credential, both registered under Impersonate:

  • Keys. A public key registered for the account, with the private half wherever the authentication happens. A short-lived assertion signed with it is exchanged for a normal ConfigHub token; cub auth login --private-key does this. This is the credential for anything that can run code: CI jobs, bots, event consumers, cub in a script.
  • Long-lived tokens. A ConfigHub token with no expiry, issued once and shown once, for a consumer with only a username field and a password field: a repository credential in Argo CD or Flux, for instance. It is accepted at the OCI registry endpoint only, as the password with the username token, and nowhere else in the API. Each token has a record, so it can be revoked on its own and its last use can be seen.

Both kinds show when they were last used, which is what makes rotation safe: add the new credential, move the consumer, watch the new one's last-used time move, then retire the old one. Service accounts walks through it.

Relationship to Workers

A Worker used to be the only non-human identity in ConfigHub, with a secret that ConfigHub generated and stored. Workers are deprecated: a ServiceAccount is the identity for automation, and a Channel is what a process connects to for events and commands. Existing Workers keep working, and a Worker is still required to serve external functions until functions move to Channels; nothing else should be created as one.

Deleting

Deleting a ServiceAccount deletes its keys and revokes its tokens, so nothing can authenticate as it again. The User it acted as is kept, disabled, so revisions and events it produced still show who made them. Grants that name it stay in place until removed.