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

# Configure workload identity authentication

Use this page to configure authentication, claims, and resource server access for a workload identity. For steps to create and manage workload identities, see [Create and manage workload identities](/docs/authentication-and-security/workload-identities/create-workload-identities.md).

## Authenticate the workload

A workload authenticates by requesting access tokens from its OIDC application's token endpoint. You choose how it authenticates by setting the **Client Authentication Method** on the **OIDC** tab. For an overview of the available methods, see [How workloads authenticate](/docs/authentication-and-security/workload-identities.md#how-workloads-authenticate).

To set the authentication method and manage the OIDC application:

1. Click Menu icon **>** **Members > Workload Identity**. The **Workload Identities** page appears.
2. Select the Workload Identity. The **Workload Identities Details** page appears.
3. Click the **OIDC** tab.
4. Set the **Client Authentication Method**, then configure the client secret, keys, or certificates that the method requires.
5. Click **Save**.

The **OIDC** tab reuses the standard OIDC and OAuth server application settings. For full details about each setting, including client secrets, signing certificates, and the client authentication methods, 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 JWT-SVID authentication lets a workload authenticate with a SPIFFE-issued token instead of a client secret. IDaaS validates the token against a trust domain, a trust bundle, and a set of allowed SPIFFE IDs. For background on SPIFFE and SVIDs, see [What SPIFFE is and why it matters](/docs/authentication-and-security/workload-identities.md#what-spiffe-is-and-why-it-matters).

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

1. Click Menu icon **>** **Members > Workload Identity**. The **Workload Identities** page appears.
2. Select the Workload Identity. The **Workload Identities Details** page appears.
3. Click the **OIDC** tab.
4. Set **Client Authentication Method** to **SPIFFE JWT-SVID**. The SPIFFE configuration fields appear.
5. 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.
6. 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.
7. 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).
8. Optional: Under **Supported Client Authentication Signing Algorithms**, select the algorithms IDaaS accepts for the JWT-SVID signature.
9. 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, do the following:

1. Enter the pattern in the **Allowed SPIFFE IDs** field.
2. Do one of the following to add the pattern:
   - Press **Enter.**
   - Type a comma.
   - Click **Add**.
3. 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. Click Menu icon **>** **Members > Workload Identity**. The **Workload Identities** page appears.
2. Select the Workload Identity. The **Workload Identities Details** page appears.
3. Click the **Claims** tab.
4. Click Circle Plus icon to add a claim, or click Pencil icon next to an existing claim to edit it.
5. To remove a claim, click Trash icon.
6. Configure the claim name, value, and whether to always return the claim with the access token.
7. Click **Save**.

## Configure resource servers

The **Resource Servers** tab lets you grant a workload identity access to the scopes defined by your resource servers, so the workload can call your protected APIs with the access tokens it receives. This tab lists the API/URL resource servers in your environment and uses the standard client credentials grant workflow. Because this workflow is shared with regular applications, you grant scopes by selecting the OIDC and OAuth application that IDaaS created for your workload identity.

Before you begin, make sure the resource server whose scopes you want to grant already exists. If it does not, click **Add Resource Server** on the tab, then click **Create Resource Server** and follow [Add an API/URL resource server](/docs/applications-and-sso/manage-applications/integrate-oidc-and-oauth-cloud-applications/manage-resource-servers/add-an-api-url-resource-server.md).

To grant a workload identity access to a resource server's scopes:

1. Click Menu icon **>** **Members > Workload Identity**. The **Workload Identities** page appears.

2. Select the Workload Identity. The **Workload Identities Details** page appears.

3. Click the **Resource Servers** tab. The **APIs/URLs** page appears.

4. Find the resource server whose scopes you want to grant.

5. In its **Actions** column, click Ellipsis Vertical icon and select Circle Plus icon **Add Client Credentials Grant**. The **Client Credentials Grant** page appears.

note
If grants already exist for that resource server, the option is labeled **Edit Client Credentials Grant** instead.

6. Click **Add**. The **Add Client Credentials Grant** dialog appears.

7. From the **OIDC/OAuth Application** list, select the application that represents your workload identity. The application appears under the same name as the workload identity, which you can confirm on the **OIDC** tab.

8. Under **Scopes**, select each scope you want to grant to the workload identity. You must select at least one scope.

9. Click **Add**. The grant appears in the list.

10. Repeat the required steps to grant scopes to additional applications if required.

11. Click **Save**.

The workload identity can now request the granted scopes when it obtains an access token through the client credentials flow.

To remove a grant:

1. Open the **Client Credentials Grant** page, click Trash icon next to the application.
2. Click **Save**.

For more information about client credentials grants, see [Configure client credential grants](/docs/applications-and-sso/manage-applications/integrate-oidc-and-oauth-cloud-applications/manage-resource-servers/configure-client-credential-grants.md).

## View the audit history

The **Audit** tab shows the authentication audit events for a workload identity's OIDC application, so you can track how and when the workload authenticates. This tab appears only if your role includes the **Reports** view permission.

Every time the workload requests a token from the OIDC token endpoint, IDaaS records an authentication event against the workload's OIDC client. Because every authentication method uses the same endpoint, the tab captures them together:

- **Client credentials authentication.** Requests in which the workload authenticates with its client secret or a private key JWT.
- **SPIFFE JWT-SVID authentication.** Requests in which the workload presents a SPIFFE JWT-SVID. Both accepted and rejected tokens are recorded, so a JWT-SVID that fails validation (for example, an untrusted signature, a trust domain mismatch, or a SPIFFE ID that matches no allowed pattern) appears as a failed authentication event.

Each event shows its outcome (success or failure), date and time, category, resource name, source IP address, subject, and event type. Open an event to see its full details, including the message that describes the result.

To review the audit history:

1. Click Menu icon **>** **Members > Workload Identity**. The **Workload Identities** page appears.
2. Select the Workload Identity. The **Workload Identities Details** page appears.
3. Click the **Audit** tab. By default, the tab shows events from the last 24 hours, with the most recent first.
4. Filter the events by outcome, date range, or source IP address as required.
5. Click an event to view its details.
6. Optional: Export the events to a report. This action requires 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).