> For AI agents: [llms.txt](https://docs.trustedauth.com/llms.txt) provides a Markdown index of this documentation.

# Manage workload identities

A workload identity is a non-human identity associated with a service, application, or automated process. When you create a workload identity, IDaaS automatically provisions an associated OpenID Connect (OIDC) and OAuth server application for it. The workload uses this application's client credentials to obtain access tokens through the OAuth client credentials flow. You manage the workload identity and its OIDC application together from a single set of pages.

This section explains how to create, view, edit, enable, disable, and delete workload identities, and how to configure the OIDC settings, SPIFFE JWT-SVID authentication, claims, and resource servers that control the tokens a workload receives.

## Prerequisites

Before you manage workload identities, ensure you meet the following requirements:

- Your role includes the **Workload Identity Management** permission. The view, add, edit, and remove actions each control a specific operation.
- To assign groups to a workload identity, your role can manage those groups. If your role can manage all groups, you can assign any group. Groups are optional.
- To view the audit history for a workload identity, your role also includes the **Reports** view permission.

## Create a workload identity

When you create a workload identity, IDaaS generates its OIDC application and client credentials automatically.

1. Click Menu icon **>** **Members > Workload Identity**. The **Workload Identities** page appears.
2. Click Circle Plus icon. The **Add Workload Identity** page appears.
3. Enter a **Name** for the workload identity. The name is required and must be unique.
4. Optional: Enter a **Description** that explains the purpose of the workload identity.
5. Optional: Enter an **Owner** to identify the person or team responsible for the workload identity.
6. Optional: In the **Groups** section, select a group from the list to assign it to the workload identity. Repeat to assign more groups. To remove an assigned group, click Trash icon next to the group.
7. Click **Save**. IDaaS creates the workload identity and its associated OIDC application, then opens the workload identity details page.

info

If the default OIDC signing certificate is unavailable, IDaaS uses another available certificate for the workload's OIDC application and displays a message that identifies the certificate it used.

## View workload identities

The **Workload Identities** page lists the workload identities you can manage based on your role and group assignments.

1. Click Menu icon **>** **Members > Workload Identity**. The **Workload Identities** page appears.
2. Review the following information for each workload identity:
   - **State** - Indicates whether the workload identity is active or disabled.
   - **Name** - The name of the workload identity. Click the name to open its details.
   - **Last Authentication Time** - The most recent time the workload authenticated. Displays as not available if the workload has never authenticated.
   - **Created** - The date and time the workload identity was created.

### Sort and filter workload identities

You can sort and filter the list to find a specific workload identity.

1. Click Menu icon **>** **Members > Workload Identity**. The **Workload Identities** page appears.
2. You can do the following actions:
   - Click the arrow next to the **Name** column heading to sort the list alphabetically.
   - Click Search icon to enable filtering, then filter by name, state, or group. Select your filter options and click **Apply**.
   - To select multiple workload identities, select the checkbox next to each one.

## Edit a workload identity

You can update a workload identity's name, description, owner, and group assignments from the **Profile** tab.

1. Click Menu icon **>** **Members > Workload Identity**. The **Workload Identities** page appears.
2. Click the name of the workload identity you want to edit. The details page appears with the **Profile** tab selected.
3. Update the **Name**, **Description**, or **Owner** as required.
4. In the **Groups** section, add or remove group assignments as required.
5. Click **Save**.

## Enable or disable a workload identity

Disabling a workload identity prevents it from authenticating without deleting it. You can enable it again later.

1. Click Menu icon **>** **Members > Workload Identity**. The **Workload Identities** page appears.
2. Do one of the following:
   - To disable an active workload identity, click Square icon for that workload identity.
   - To enable a disabled workload identity, click Play icon for that workload identity.
3. Confirm the action on the prompt.

tip

To change the state of several workload identities at once, select their checkboxes and use the enable or disable action in the toolbar. You can also change the state from the **Profile** tab by using the active toggle.

## Delete a workload identity

Deleting a workload identity also removes its associated OIDC application. You cannot delete the OIDC application on its own.

1. Click Menu icon **>** **Members > Workload Identity**. The **Workload Identities** page appears.
2. Click Trash icon for the workload identity you want to delete.
3. Click **Delete** on the confirmation prompt.

warning

Deleting a workload identity is permanent. Any service that relies on the workload's client credentials can no longer authenticate.

## Configure OIDC settings

The **OIDC** tab exposes the settings of the OIDC and OAuth server application that IDaaS created for the workload identity. Use this tab to view the client ID, manage the client secret, and configure the signing certificate and other application settings.

1. Open the workload identity details page and select the **OIDC** tab.
2. Update the application settings as required.
3. Click **Save**.

For details about the available OIDC and OAuth server application settings, see [Integrate a generic OIDC and OAuth server application](/docs/applications-and-sso/manage-applications/integrate-oidc-and-oauth-cloud-applications/integrate-a-generic-oidc-and-oauth-server-application.md).

## Configure SPIFFE JWT-SVID authentication

SPIFFE (Secure Production Identity Framework for Everyone) gives each workload a platform-neutral identity called a SPIFFE ID, such as `spiffe://trust.domain/svc/payments`. A SPIFFE JWT-SVID (SPIFFE Verifiable Identity Document) is a signed JWT that carries this SPIFFE ID. Instead of authenticating with a client secret, a workload can present a JWT-SVID that IDaaS validates against a trust domain, a trust bundle, and a set of allowed SPIFFE IDs.

You configure SPIFFE authentication on the workload identity's **OIDC** tab by changing the client authentication method.

1. Open the workload identity details page and select the **OIDC** tab.
2. Set **Client Authentication Method** to **SPIFFE JWT-SVID**. The SPIFFE configuration fields appear.
3. In the **SPIFFE Trust Domain** field, enter the trust domain that issues the workload's JWT-SVIDs, for example `trust.domain`. This field is required.
4. Provide the trust bundle that IDaaS uses to verify the JWT-SVID signature by selecting one of the following:
   - **SPIFFE Bundle JWKS URL** - Enter an HTTPS URL where IDaaS retrieves the JSON Web Key Set (JWKS) for the trust domain.
   - **SPIFFE Bundle JWKS JSON** - Paste the JWKS JSON directly. Click **Pretty Print** to format the JSON for readability.
5. In the **Allowed SPIFFE IDs** field, add the SPIFFE ID patterns that are allowed to authenticate as this workload identity. See [Match allowed SPIFFE IDs](#match-allowed-spiffe-ids).
6. Optional: Under **Supported Client Authentication Signing Algorithms**, select the algorithms IDaaS accepts for the JWT-SVID signature.
7. Click **Save**.

When a workload presents a JWT-SVID to the token endpoint, IDaaS verifies the signature with the trust bundle, confirms the token was issued by the configured trust domain, and checks that the SPIFFE ID in the token matches one of the allowed SPIFFE ID patterns. If any check fails, IDaaS rejects the request.

### Match allowed SPIFFE IDs

The **Allowed SPIFFE IDs** list controls which SPIFFE IDs can authenticate as the workload identity. A JWT-SVID is accepted only if its SPIFFE ID matches at least one pattern in the list. You can add up to 20 patterns, and each pattern must belong to the configured trust domain.

Add patterns of the following types:

- **Exact match** - A full SPIFFE ID that matches a single workload, for example `spiffe://trust.domain/svc/payments`. Only that exact SPIFFE ID is allowed.
- **Prefix match** - A pattern that ends with `/*`, for example `spiffe://trust.domain/worker/*`. Any SPIFFE ID that begins with the prefix before the `/*` is allowed, which lets a group of related workloads share one workload identity.

To add a pattern, enter it in the **Allowed SPIFFE IDs** field and press **Enter** or type a comma, or click **Add**. To remove a pattern, click the delete icon on its chip.

Keep the following requirements in mind when you add patterns:

- Each pattern must start with `spiffe://` followed by the value in the **SPIFFE Trust Domain** field, for example `spiffe://trust.domain/`. IDaaS rejects a pattern whose trust domain does not match.
- You can add a maximum of 20 patterns per workload identity.
- A SPIFFE ID pattern can be assigned to only one application. If another application already uses the pattern, IDaaS reports that the SPIFFE ID is already in use.

tip

Use a prefix pattern such as `spiffe://trust.domain/worker/*` when several instances of the same service must authenticate as one workload identity. Use an exact SPIFFE ID when only a single, specific workload should be allowed.

To expose the authenticated SPIFFE ID in the tokens IDaaS issues, add the **[SPIFFE ID]** attribute as a claim on the **Claims** tab. See [Configure claims](#configure-claims).

## Configure claims

The **Claims** tab controls the claims that IDaaS includes in the tokens issued to the workload identity. In addition to standard claims, you can map the following workload-specific attributes:

- **[Workload Identity Name]** - The name of the workload identity.
- **[Workload Identity Owner]** - The owner assigned to the workload identity.
- **[SPIFFE ID]** - The SPIFFE identifier associated with the workload identity.
- **[Groups]**, **[Unique Group IDs]**, and **[Group Attributes]** - The groups assigned to the workload identity and their attributes.

To add or edit a claim:

1. Open the workload identity details page and select the **Claims** tab.
2. Click Circle Plus icon to add a claim, or click Pencil icon next to an existing claim to edit it. To remove a claim, click Trash icon.
3. Configure the claim name, value, and whether to always return the claim with the access token.
4. Click **Save**.

## Configure resource servers

The **Resource Servers** tab lists the resource servers (protected APIs) defined in your account and lets you grant the workload identity access to their scopes. Because a workload identity authenticates with the OAuth client credentials flow, you grant access by defining a _client credentials grant_ that maps the workload identity's OIDC and OAuth server application to the scopes you want it to request.

The client credentials grant page is shared with every OIDC and OAuth server application and is not specific to workload identities. When you assign scopes, you select the workload identity's application by name, so make sure you choose the application that matches your workload identity.

1. Open the workload identity details page and select the **Resource Servers** tab. The tab lists the resource servers you can grant access to.
2. Find the resource server whose scopes you want to grant, and in its **Actions** column, click the client credentials grant icon (Circle Plus icon). The **Client Credentials Grant** page appears.
3. Click **Add**. The **Add Client Credentials Grant** dialog appears.
4. From the **OIDC/OAuth Application** list, select the OIDC and OAuth server application that IDaaS created for this workload identity. The application uses the same name as the workload identity.
5. Under **Scopes**, select each scope you want to grant. You must select at least one scope.
6. Click **Add**.
7. Click **Save**.

To change the scopes later, open the same resource server's client credentials grant, select the workload identity's application in the list, update the selected scopes, and click **Save**. To remove the workload identity's access to a resource server, delete its client credentials grant on that resource server.

note

The **Client Credentials Grant** page lists every OIDC and OAuth server application, not only workload identities. Confirm that the application you select matches your workload identity's name so you grant scopes to the correct workload.

## View the audit history

The **Audit** tab shows the authentication events recorded for the workload identity's OIDC and OAuth server application, so you can track when and how the workload authenticates. The tab records an event each time the workload requests a token, regardless of the client authentication method it uses (client secret, SPIFFE JWT-SVID, or private key JWT). This tab appears only if your role includes the **Reports** view permission.

Each event row shows the following information:

- **Outcome** - Whether the authentication succeeded or failed.
- **Date** - The date and time of the event.
- **Category** - The event category, such as **Authentication**.
- **Resource Name** - The resource involved in the event.
- **IP** - The source IP address the request came from.
- **Subject Name** - The subject that authenticated, which identifies the workload identity's application.
- **Action** - The action recorded for the event.
- **Event** - The specific event type.

By default, the tab shows events from the last day. To review the audit history:

1. Open the workload identity details page and select the **Audit** tab.
2. Filter the events by date range (day, week, month, three months, or a custom range) or by attribute such as outcome or source IP.
3. Click an event to open its details. The details show the event's attributes, which can include the requested scopes and resource server, and for SPIFFE authentication, the SPIFFE ID that was presented and matched.
4. Optional: Click the export action to export the events, if your role includes the **Export Reports** permission.

For more information about audit data, see [View and export audit logs](/docs/reports-and-audits/view-and-export-audit-logs.md).

## Next steps

- Assign roles that grant the **Workload Identity Management** permission to the administrators who manage workload identities. See [Create, assign, and manage roles](/docs/people-and-access/manage-members/create-assign-and-manage-roles.md).
- Organize workload identities with groups. See [Create and manage groups](/docs/people-and-access/manage-members/create-and-manage-groups.md).