Service Account and Federation Reference

This reference lists a service account’s attributes, its two credential modes, the roles and group memberships it can hold, the realm prerequisites federated mode needs, the federation-options response, and its token lifetime.

Type

Reference

Goal

Look up service-account fields, credential modes, roles, and federation requirements.

Audience

Tenant admins and engineers who create, configure, or authenticate a service account.

When to use

Use this while filling the create or edit form, or while setting up a federated credential.

Contents

The sections below cover each area in this reference:

Attributes

A service account is a user of type service account. These are its fields.

Field Type Set by Description

Name

string

Admin, on create

The human label for the account. Immutable after creation, because the client id derives from it.

Client id

string

System

The machine identity, of the form sa-<name>-<random>. Read-only. Copy this into your workload configuration.

Email

string

System

Generated address of the form <clientId>@sa.axual.io. Read-only, never delivered to.

Credential mode

enum

Admin, on create

secret or federated. Immutable after creation. Defaults to secret.

Secret

string

System

The client secret. Secret mode only, returned once on create and rotate, never stored or shown again.

Federated subject

string

Admin, editable

Federated mode only. The external workload identity’s object id that the account is bound to.

Roles

list

Admin, editable

The tenant-scoped roles the account holds. See Roles.

Group memberships

list

Admin, editable

The groups the account belongs to. See Group membership.

Credential modes

The credential mode, labelled Authentication method in the portal, is chosen on creation and cannot be changed afterwards. It decides how the account proves its identity.

Mode Secret returned Rotation Identity proof

secret

Once, on create and rotate

In Self-Service, supersedes the old secret immediately

Client id and client secret

federated

Never (no secret exists)

Not applicable; owned by the external identity provider

An assertion signed by the bound identity provider, for the bound subject

Roles

A service account can hold the same tenant-scoped roles as a human user, administrative roles included, up to and including the permission to manage other service accounts. There is no separate role set for service accounts.

A service account’s authority is always scoped to its own tenant. A role a tenant admin may not assign to a human user cannot be assigned to a service account either. For the definition of each role, see Users and Roles.

Group membership

A service account’s group membership is authored in Self-Service and stored by Axual, never read from an identity provider. The rules below govern it.

  • A service account can be a member of any group of its tenant, both Axual-managed groups and identity-provider-managed (IAM) groups.

  • Adding a service account to a group is a tenant-admin action, whichever path is used.

  • Removing a service account, or promoting one that is already a member to group manager or resource manager, is available to a group manager.

  • A group manager or resource manager must also be a member of that group; this holds for every group type and both human and service-account principals.

  • For an IAM group, the stored members are its service-account members plus any humans recorded for management; this is a subset of the identity provider’s roster, which Axual cannot enumerate.

For the group operations themselves, see Groups.

Federated realm prerequisites

Federated mode depends on per-realm configuration that Axual does not create. An operator sets these up once per realm before a federated service account can be created; creation fails fast with a clear error when one is missing. For the procedure, see How to Prepare a Keycloak Realm for Federated Service Accounts.

Prerequisite Purpose

federated-jwt execution in the bound client-authentication flow

Lets the realm accept a signed JWT as client authentication. Realms upgraded from Keycloak older than 26.6 do not have it.

Identity provider enabled for client assertions

Designates the provider Axual trusts for federated authentication.

Identity provider audience set to its login client id

Fixes the aud value an assertion must carry.

Client-assertion reuse allowed

Entra tokens carry uti rather than jti, so reuse checks reject them otherwise.

A raised client-assertion maximum age

Azure caches managed-identity tokens for around 24 hours; the default age check rejects them.

Signature validation on, with issuer and JWKS URL set

Lets the realm validate the assertion offline against the provider.

Federation options response

The federation-options endpoint reports, for the caller’s tenant realm, whether federated mode is available and the values a workload needs to mint an acceptable assertion. These are its fields.

Field Type Description

federationSupported

boolean

Whether the realm meets the prerequisites. false when there is no suitable provider, more than one, or a missing prerequisite.

kind

enum

ENTRA when the backing provider is Microsoft Entra, else GENERIC. Drives which subject label the form shows.

issuer

string

The backing provider’s issuer.

audience

string

The value an assertion’s aud claim must equal. For Entra this is the bare application GUID.

entra.tenantId

string

Entra only. The Entra directory (tenant) GUID.

entra.resource

string

Entra only. The resource a workload requests from Entra, of the form api://<audience>, so Azure mints a token whose audience matches.

When federationSupported is false, no other field is present. For a generic provider, the entra block is absent.

Token lifetime and audit attribution

A service account’s access token is issued with a short lifetime of five minutes. A deleted account’s already-issued token keeps working until it expires, and the short lifetime bounds that window.

Every lifecycle action and every API call a service account makes is recorded in the audit trail against its client id, not its generated email. The audit history can be filtered by that client id. Because a service account can hold the permission to manage other service accounts, the acting administrator in an audit record may itself be a service account.