Skip to main content

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 > Members > Workload Identity. The Workload Identities page appears.
  2. Click . 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 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 > 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 > 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 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 > 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 > Members > Workload Identity. The Workload Identities page appears.
  2. Do one of the following:
    • To disable an active workload identity, click for that workload identity.
    • To enable a disabled workload identity, click 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 > Members > Workload Identity. The Workload Identities page appears.
  2. Click 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.

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.
  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​

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 to add a claim, or click next to an existing claim to edit it. To remove a claim, click .
  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 (). 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.

Next steps​