Skip to main content

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.

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.

To set the authentication method and manage the OIDC application:

  1. Click > 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.

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.

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

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

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

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

  1. Click > 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 and select 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 next to the application.
  2. Click Save.

For more information about client credentials grants, see Configure client credential grants.

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

Next steps​