Service Accounts

The sections below build up the concept, then link the tasks:

Automation needs to call the Platform Manager API: Terraform, CI/CD pipelines, and scripts all create topics, applications, and other resources without a person present. Before service accounts, the only way to do this was to log in as a human user with that user’s password, using the OAuth2 Resource Owner Password Credentials (ROPC) grant.

That approach has three problems. A human password ends up copied into pipelines and secret stores. The automation stops working when that person leaves or rotates their password. And every action the automation takes is recorded against a person, so machine activity cannot be told apart from human activity in the audit trail.

A service account removes all three. It is a machine identity with its own credential, no human password, and its own entry in the audit trail. It replaces the older CI/CD user approach, which is now deprecated (see Create a Keycloak user for CI/CD operations).

A service account is a non-human user. It is a distinct type of user in your tenant, and it reuses the same model as a human user: it can be a member of groups, and it can hold roles. Authorisation works the same way for both, so a service account sees exactly what a human user with the same groups and roles would see.

What a service account does not have is an interactive login. There is no browser, no password prompt, and no redirect to your identity provider. It proves who it is with a machine credential and then calls the API directly.

Its identity is generated and reserved so it cannot collide with a human user. The account is addressed by a client id of the form sa-<name>-<random>, and its generated email follows the pattern <clientId>@sa.axual.io. These are illustrative of the shape, not values you set: Axual generates them. In the audit trail the actor is named by the client id, so a service account’s actions are always recognisable as machine activity.

Every service account uses exactly one credential mode, chosen when it is created and fixed for its lifetime. The mode decides how the account proves its identity.

In client secret mode, Axual generates a secret string. The workload presents its client id and that secret to obtain a token. In federated mode, no secret exists at all. The workload instead presents an assertion signed by your own external identity provider, and Axual trusts that signature. Federated mode suits customers who will not hold a secret anywhere, and it is the safer choice for a high-privilege account because there is no secret to leak.

The credential mode cannot be changed after creation, because switching it means rebuilding the account’s credential from scratch. To move an account between modes, delete it and create a new one.

A service account authenticates with the OAuth2 Client Credentials grant against its tenant’s own identity realm. This grant is made for machine-to-machine calls: it needs no user and no browser. The token it produces is a normal realm token, so everything downstream, from the API Gateway to authorisation, treats a service account’s request exactly as it treats a human user’s.

Federated mode uses the same grant and produces the same kind of token. The only difference is at the moment of proving identity: instead of a secret, the workload presents an assertion its identity provider signed, and the realm validates that signature against the provider. Because the resulting token is identical, a federated account is indistinguishable from a client-secret account once the request reaches the Platform Manager.

Tokens are issued with a short lifetime. This bounds how long an already-issued token keeps working after an account is deleted or its secret rotated, because a token cannot be withdrawn before it expires. A short life keeps that window small.

Creating, changing, rotating, and deleting a service account is restricted to tenant admins. This is the main control on the feature: a service account can hold real authority, so handing one out is a tenant-level decision. Reading a service account, by contrast, is open to any user of the tenant, because a group already shows its service-account members to everyone in that group. A read never includes the secret.

For a client-secret account, the secret is returned exactly once, in the response to creation or rotation, and never again. Axual does not store it. Storing it would create a second place it could leak from, so the design keeps only the one copy you hold. If you lose it, you rotate to get a new one; rotation supersedes the old secret immediately, with no overlap period during which both work.

Every lifecycle action and every API call a service account makes is audited against its client id. Because a service account can itself hold the permission to manage other service accounts, the actor in an audit record may be a service account rather than a person, and the trail records which.

A service account can be granted the same tenant-scoped roles as a human user, administrative roles included. Real automation often needs to do administrative work, so there is no separate, weaker role set for machines. A service account’s authority is always scoped to its own tenant.

Group membership for a service account is authored in Self-Service, not read from an identity provider. A service account is never a subject in your identity provider, so it carries no group claim, and the membership recorded in Axual is the only source. This is why a service account can belong to an identity-provider-managed (IAM) group even though human membership of that group is resolved externally.

Admitting a service account to a group is a tenant-admin action, whichever way it is done, because an admitted account inherits everything the group owns and then acts with it unattended. Removing an account from a group, or promoting one that is already a member, stays available to a group manager, since neither can grant authority a tenant admin has not already granted. See Groups for the rules on managers and members.

These pages cover the tasks, in the order you usually meet them: