Service accounts

A service account is a non-human identity in evroc IAM that you grant access to so that automated work, such as CI pipelines and applications, can call evroc APIs without using a person's login. Instead of a password or an interactive sign-in, a service account authenticates with a credential it holds.

Use a service account whenever something that isn't a person needs to act in evroc: a build pipeline that pushes to a bucket, a backend service that reads compute metadata, or a scheduled job that needs to run on its own.

Why use a service account

Service accounts separate machine access from human access. A few reasons to prefer them over a user's credentials:

  • Automation - CI/CD pipelines, schedulers, and applications can authenticate on their own, without a person typing in a password.
  • Clear ownership - A service account can be named for the workload it serves (for example ci-deploy or storage-ingest), so you can tell which automated system is doing what.
  • Rotatable access - Credentials have a finite life and can be revoked, so you can rotate a service account's access without affecting a person's login.
  • Auditability - Requests made by a service account are attributed to that service account, not to a person, which keeps human and machine activity distinct.

Don't use a service account for interactive access. When a person needs to sign in and act in evroc, use a user instead.

How a service account works

A service account is a principal (an identity that can receive access), scoped to a single project. It has:

  • An ID - A name you choose for the service account, unique within the project.
  • An optional description - A note that records what the service account is for.
  • An enabled state - Whether the service account can authenticate. A disabled service account cannot be used for authentication, even if it has credentials and role bindings.

Service accounts are addressed by fully qualified identifiers (FQIDs) that include the project they belong to:

/iam/projects/<project-id>/serviceAccounts/<service-account-id>

Service accounts and access

Access works the same way it does for users: you grant a role to a principal on a scope using a role binding.

A service account has no access of its own until you grant it a role. To give a service account the ability to, say, operate compute resources in a project, create a role binding that grants the relevant role to the service account on that project. See fine-grained access and manage role bindings for how roles, permissions, and scopes fit together.

Service account credentials

A service account only becomes useful once you create a credential for it. A credential is what the service account uses to authenticate: when a workload presents the credential, evroc identifies the request as coming from the service account.

  • The private key is shown only once. When you create a credential, its private key (a JSON Web Key) is returned only at creation time and can't be viewed again later.
  • Credentials expire. Every credential has a mandatory expiration time that you set at creation. The minimum is 24 hours and the maximum is 2 years. You can't change the expiration after the credential is created.
  • Credentials are revocable. You can revoke a credential at any time, for example when you suspect it's been exposed. A revoked credential stops working immediately.

Credential types

A service account can hold two types of credentials. Each type works with a specific set of APIs, and the two aren't interchangeable.

TypeKey mechanismCompatible with
rs256-jwt (default)Asymmetric (RSA + SHA256). Signs a JWT with the private key and exchanges it for a short-lived access token via the OAuth 2.0 private key JWT flow.evroc public API
hmac-sigv4Symmetric (HMAC + SHA256). Signs requests with an S3 compatible signature.S3 compatible API

Use rs256-jwt when the workload calls the evroc public API, for example to manage compute resources, storage buckets, or IAM configuration. Use hmac-sigv4 when the workload reads or writes objects through the S3 compatible API, for example uploading data to a bucket with s3cmd or rclone.

If a service account needs to do both, for example a pipeline that manages buckets through the evroc public API and also uploads objects to them through the S3 compatible API, create one credential of each type.

Credential and access token lifetimes

A service account credential involves two independent expiration times:

  • Credential expiration controls how long the credential resource itself remains valid. It's a mandatory field set at creation time, with a minimum of 24 hours and a maximum of 2 years. Once the credential expires, the service account can't authenticate with it and you must create a new credential.

  • Access token lifetime controls how long each short-lived access token remains valid before the workload must request a new one. This applies only to rs256-jwt credentials. The default is 300 seconds (5 minutes), with a minimum of 60 seconds and a maximum of 28800 seconds (8 hours). This is set at credential creation.

For the CLI commands that create, list, and revoke service account credentials, see create a service account.

Next steps