Service identities
The Service identities screen lets you register the SPIFFE identities that the workloads use for mTLS
authentication, give them roles and delete them. Portal path: /admin/service-identities. It is used by the tenant
administrators (tenant_admin) and the security officers (security_officer); every member of the tenant reads the
list.
What the screen shows
A Service identities table with Refresh and New identity:
| Column | Content |
|---|---|
| Name | Name of the identity. |
| SPIFFE id | SPIFFE identifier of the workload, for example spiffe://eai.local/ns/agents/sa/worker. |
| Roles | Roles granted to the workload. |
| Created | Creation date. |
The list is read in one call and sorted by name. Empty state: No service identity, "Register a SPIFFE id for a workload."
Actions
| Button or action | What it does | API call | Roles |
|---|---|---|---|
| Opening the screen, Refresh | Reads the service identities. | GET /v1/service-identities | Member of the tenant |
| New identity then Create | Form Name (required), SPIFFE id (required, spiffe://<trust-domain>/<path>), Roles (list; suggestions platform_admin, tenant_admin, security_officer, finops, developer, auditor, agent, viewer). Clearance internal. | POST /v1/service-identities | tenant_admin, security_officer |
| Delete | Destructive confirmation with the impact, then deletion. | DELETE /v1/service-identities/{id} (impact: GET /v1/lineage/graph) | tenant_admin, security_officer |
Roles
From services/control-plane/src/eai/domains/identity/__init__.py: reading needs a principal inside a tenant;
creation and deletion require tenant_admin or security_officer (platform_admin always passes). A
security_officer without an administrator role cannot give a role they do not hold, and only a platform_admin gives
platform_admin.
Typical tasks
Register a worker workload
- Open the form. Button New identity. Expected result: the side form. If it fails:
forbiddenat submit time when you are neithertenant_adminnorsecurity_officer. - Fill the SPIFFE id and the roles. Name:
agents-worker; SPIFFE id:spiffe://eai.local/ns/agents/sa/worker(the identity issued to the workload); Roles:agent. Then Create. The mTLS certificate of the workload is then mapped to these roles. Expected result: the toast Created and the new line. If it fails: a validation error when the identifier does not start withspiffe://;conflict(HTTP 409) when the SPIFFE id is already registered.
Remove a workload that no longer exists
- Delete the identity. Row menu > Delete, read the impact, confirm. Expected result: the line disappears and
the workload can no longer authenticate with this identity. If it fails:
not_foundwhen it was already deleted.
Troubleshooting
| Symptom | Cause | Fix |
|---|---|---|
| Validation error on SPIFFE id | The value does not match spiffe://<trust-domain>/<path>. | Type the full SPIFFE identifier. |
conflict (HTTP 409) | This SPIFFE id is already registered in the tenant. | Reuse the existing identity or delete it first. |
forbidden (HTTP 403) with required_roles | Your role cannot manage service identities, or you give a role you do not hold. | Ask a tenant_admin. |
not_found (HTTP 404) on Delete | The identity no longer exists. | Click Refresh. |
tenant_required (HTTP 403) | The session does not act inside a tenant. | Sign in with an account of the tenant. |