Skip to main content

Service Accounts

A service account is the identity a pipeline uses when it runs on its own — not on behalf of a person. It is a non-human account with its own client credentials and its own set of roles. Those roles decide what the pipeline may read and write.

Every adapter has a pipeline service account​

Every adapter has a mandatory pipeline service account. It is provisioned automatically when the adapter is set up, and it consists of two things that are created for you:

  • an identity client in the Identity Service (the actual credentials the pipeline authenticates with), and
  • a ServiceAccountConfiguration — a small, portable record that tells the adapter which client to use, which roles it carries, and whether it may act on behalf of a user.

By default this one service account is the identity for all of the adapter's pipelines.

A missing service account is refused at deploy time​

Because the service account is mandatory, a pipeline whose identity cannot be resolved is refused when you deploy it — it does not fall back to unrestricted access, and it does not run "as system". This is deliberate: a pipeline should never run with more authority than intended just because its identity was forgotten.

If this happens, the deployment fails with a clear message that points at the two ways to fix it:

  • Link a configuration on the adapter — this becomes the default identity for every pipeline on that adapter, or
  • Override it on the single pipeline — link a service account to just that one pipeline (see Default vs. override below).
note

An adapter must also be online for a deploy to succeed. If the adapter is offline you will see a connectivity error first; the service-account check runs once the adapter is reachable.

Default vs. override​

A pipeline resolves its identity in a simple order of precedence:

  • Adapter default — the service account linked on the adapter is used by all of its pipelines unless a pipeline says otherwise.
  • Per-pipeline override — link a different service account to a single pipeline and that pipeline uses it instead. This is how you give one pipeline broader (or narrower) access than its siblings.

The override is expressed as a Uses link from the pipeline to the service-account configuration. You do not need to edit YAML by hand for this — Refinery Studio manages the link for you (see Managing Pipeline Identity in Refinery Studio).

The ServiceAccountConfiguration​

The ServiceAccountConfiguration is a portable declaration of an identity. It describes intent, not secrets, so it can be exported, imported, and moved between tenants safely. It carries:

It declaresMeaning
Client idWhich identity client the pipeline authenticates as
Assigned rolesThe roles the account carries — these decide what data it can access
Delegation allowedWhether this account may act on behalf of a calling user (see Delegation)
IssuerWhich OctoMesh installation the identity lives in
TenantWhich tenant the identity belongs to

"This installation" and "the current tenant" are the defaults​

You normally leave issuer and tenant empty:

  • empty issuer means "this installation" — the OctoMesh instance the adapter itself runs in, and
  • empty tenant means "the current tenant" — the tenant the pipeline runs in.

You only fill in concrete values when you deliberately want the pipeline to authenticate against a foreign tenant or another OctoMesh instance. For the overwhelmingly common case — a pipeline acting inside its own tenant — leaving both empty is correct and keeps the declaration portable.

The secret is optional​

A ServiceAccountConfiguration can carry a client secret, but it does not have to. When no secret is present, the account works by impersonation: the adapter's own identity is allowed to act as the service account. There is then no plaintext secret to store, rotate, or leak — the adapter authenticates with its own credentials and simply acts as the service account it was told to use.

tip

Impersonation is the simpler and safer default for pipelines that stay inside their own installation: nothing sensitive is stored in the configuration, and there is no secret to keep in sync. Use an explicit secret when the account must authenticate somewhere the adapter's own identity is not trusted to act — for example against another OctoMesh instance.

Roles decide what a pipeline can access​

What a pipeline can read and write is decided entirely by the roles on its service account, through the platform's data permissions. This includes owner-scoped data (data that "belongs to" a particular user).

  • For broad access — give the service account the roles that carry the permissions the pipeline needs. For owner-scoped data specifically, the account needs a data permission that grants access across owners for each type it must see; otherwise it only sees rows it owns itself (which, for a service account, is usually none).
  • For least privilege — link a dedicated override service account to the one pipeline and give it only the roles it needs, nothing more.
warning

An account with no effective roles is not an error — it is simply an identity that can see nothing. A pipeline that "runs fine but returns no data" is often a service account that is missing the role carrying the permission it needs. Check the account's roles first.