Skip to main content

Service Accounts

In Defakto, non-human actors are authenticated using service accounts. Just like users, they are assigned a role. Service accounts support two authentication methods:

  • Key-based — an Ed25519 public/private key pair. The private key is stored by the caller and used to sign authentication challenges.
  • Workload Identity Federation (WIF) — the service account is bound to an external OIDC identity by presenting a short-lived platform-issued OIDC token (from Terraform Cloud, GitHub Actions, etc.) and receiving a session in exchange. No long-lived secret is stored.

Any Defakto user can create a service account with a role no greater than their own. For example, a user with the Operator role can create a service account with the same role, but cannot create a service account with escalated privileges (e.g. Administrator).

The user who created a service account is considered the service account "owner". Service account owners have the ability to update or delete the service account. See the Roles documentation for more information.

Service accounts cannot create new service accounts.

Key-based authentication​

Each service account can have one or more Ed25519 key pairs. The private key should be stored securely.

Multiple keys per service account are supported to enable zero-downtime rotation: Once a new key is deployed and verified, the previous key can be disabled and deleted.

For full key management commands — creating, disabling, enabling, and deleting keys — see Service Account Operations.

Workload Identity Federation (WIF)​

WIF eliminates the need to store and rotate long-lived private keys. A WIF Configuration binds a service account to an external OIDC identity provider (IdP) and specifies which JWT claims from that IdP must match for authentication to succeed. When a pipeline presents a valid OIDC token whose claims match, it receives a standard service account session with the role and realm assignments for that service account.

Each WIF Configuration must reference a WIF Issuer, an organization-wide record that registers the external OIDC provider and holds its key material. WIF issuers are managed by organization administrators or owners, but any organization member can create a WIF Configuration on a service account they own and reference an existing issuer.

For the full spirlctl iam service-account wif-config command reference — set, get, and delete — see Service Account Operations.

Auditing​

Sessions created via WIF are recorded in audit logs with the OIDC issuer, the matched claims, and the session ID. Subsequent API calls within the session carry the same session ID, making it possible to trace all activity back to the originating token exchange.