On this page
Authenticate a client with a SPIFFE JWT-SVID
Configure an OAuth 2.0 client so that a workload, such as a back-end service, a scheduled job, or an AI agent, authenticates to Okta with a JWT-SVID from its SPIFFE deployment. You don't create, store, or rotate a client secret or a private key in Okta.
Learning outcomes
- Understand how Okta uses a SPIFFE JWT-SVID to authenticate an OAuth 2.0 client.
- Register a SPIFFE trust domain in your org.
- Configure an app integration or a Client ID Metadata Document (CIMD) client to authenticate with
spiffe_jwt. - Request a token with a JWT-SVID.
What you need
- A SPIFFE implementation, such as SPIRE, that issues JWT-SVIDs to your workloads. See SPIRE (opens new window).
- The SPIFFE ID of each workload that authenticates to Okta. See SPIFFE ID specification (opens new window).
- The trust domain of those SPIFFE IDs and the HTTPS URL of its bundle endpoint. Okta must be able to reach the endpoint, and it must serve JWT-SVID signing keys. See SPIFFE Trust Domain and Bundle (opens new window).
- An org with SPIFFE JWT-SVID client authentication enabled.
- A super or API access management admin role to manage trust domains. An org admin or read-only admin role can view trust domains but can't manage them.
- A scoped OAuth 2.0 access token with the
okta.spiffe.manageandokta.apps.managescopes. - An authorization server that issues tokens to the client. See Create an authorization server.
- For a CIMD client, an org with CIMD enabled and a CIMD URL that you host. See Register apps with a Client ID Metadata Document (CIMD).
Overview
This guide explains how to use SPIFFE JWT-SVIDs for client authentication with Okta. To follow the steps, you must already run SPIFFE and use Okta to protect APIs or AI agents. The guide doesn't explain how to set up SPIRE or another SPIFFE implementation.
Key terms
This guide uses the following terms. SPIFFE terms come from the SPIFFE standards (opens new window) and Okta doesn't define them.
| Term | Description |
|---|---|
| SPIFFE | Secure Production Identity Framework For Everyone. A set of open-source standards for identifying software systems. |
| SPIRE | SPIFFE Runtime Environment. An implementation of the SPIFFE standards that issues identities to workloads. Other SPIFFE implementations exist, such as Istio, Consul, and cert-manager. |
| Workload | A piece of software that runs for a specific purpose, such as a back-end service, a scheduled job, or an AI agent. In this guide, a workload is also the OAuth 2.0 client that authenticates to Okta. |
| SPIFFE ID | A URI that identifies a workload, in the format spiffe://{trustDomain}/{workloadPath}. For example, spiffe://example.org/payments-service. |
| Trust domain | The identity namespace that one SPIFFE implementation controls. It's the part of a SPIFFE ID after spiffe:// and before the next /. In Okta, you register each trust domain with the URL of its bundle endpoint. |
| SVID | SPIFFE Verifiable Identity Document. The document that a workload uses to prove its SPIFFE ID. An SVID is either an X.509 certificate or a JWT. Okta only supports JWT-SVIDs. |
| JWT-SVID | An SVID in JSON Web Token format. The sub claim holds the SPIFFE ID of the workload. Okta supports JWT-SVIDs for client authentication. |
| Bundle | The object that contains a trust domain's cryptographic keys, and is also called a trust bundle. Okta uses the keys that are marked for JWT-SVIDs to verify signatures. |
| Bundle endpoint | The HTTPS URL where a trust domain publishes its bundle. Okta retrieves the keys from this URL and caches them, so you don't upload keys to Okta. |
SPIFFE values that Okta needs
Okta doesn't issue, store, or manage workload identities. It verifies the JWT-SVID that your SPIFFE implementation issues, and then applies your authorization server's access policy, as it does for any other client. With spiffe_jwt, the JWT-SVID replaces a client secret or a private_key_jwt assertion. The spiffe_jwt method is based on OAuth SPIFFE Client Authentication (opens new window) (IETF Internet-Draft).
You bring three values from your SPIFFE implementation to Okta.
| SPIFFE value | Where it comes from | Where you use it in Okta |
|---|---|---|
| Trust domain and bundle endpoint URL | Your SPIFFE implementation. The bundle endpoint publishes the public keys that verify the trust domain's JWT-SVIDs. | The trust domain registration. Okta retrieves the keys itself, so you don't register or upload keys. |
SPIFFE ID, such as spiffe://example.org/payments-service | Your SPIFFE implementation assigns it to the workload. | The spiffe_id of the client |
| JWT-SVID | The workload requests it from your SPIFFE implementation. | The client_assertion in the token request |
How Okta authenticates a client with a JWT-SVID
- The workload requests a JWT-SVID from your SPIFFE implementation, with the issuer of your authorization server as the audience. It sends the JWT-SVID and its client ID to the token endpoint of your authorization server.
- Okta confirms that the JWT-SVID hasn't expired, that the
audclaim is the issuer of the authorization server, and that thesubclaim is the SPIFFE ID that you registered for the client. - Okta retrieves the signing keys from the bundle endpoint that you registered for the trust domain, and verifies the signature.
- Okta authenticates the client and issues a token according to your access policy.
Supported clients and limits
You can use spiffe_jwt with OpenID Connect (OIDC) web, native, and service apps that you create as app integrations, and with CIMD clients. You can also use it with AI agents. To add an AI agent with a SPIFFE credential in the Admin Console, see Add AI agents manually (opens new window). To register an AI agent as a CIMD client, see Register AI agents with a CIMD.
You can't use spiffe_jwt with single-page apps (SPAs) or with apps from the Okta Integration Network (OIN). Each client has one SPIFFE ID. Okta enforces that a SPIFFE ID belongs to only one app integration in your org, but it doesn't check CIMD clients. It works with the org authorization server and with custom authorization servers.
Configure client authentication with a JWT-SVID
- Register the trust domain so that Okta can find the signing keys.
- Configure the client with its SPIFFE ID, either as an app integration or as a CIMD client. For a CIMD client, the app owner adds the SPIFFE ID to the CIMD document.
- Get a JWT-SVID for the workload from your SPIFFE implementation.
- Request a token with the JWT-SVID.
- Manage trust domains to update or remove a registration.
Register the trust domain
Register the trust domain of the SPIFFE IDs that your workloads use. The registration tells Okta where to get the keys that verify JWT-SVIDs from that trust domain. If your workloads use SPIFFE IDs in more than one trust domain, register each of those trust domains.
Complete this task before you configure any client. Okta rejects a client configuration, and token requests from a CIMD client, when the trust domain of the SPIFFE ID isn't registered.
Find the trust domain of your workloads' SPIFFE IDs and the HTTPS URL of its bundle endpoint. Both come from your SPIFFE implementation. For
spiffe://example.org/payments-service, the trust domain isexample.org.Send a
POSTrequest to the Create a SPIFFE trust domain registration (opens new window) endpoint to register the trust domain.- Set
trustDomainto the trust domain andbundleUrlto the HTTPS URL of the bundle endpoint. - Save the
idfrom the response. You need it to update or delete the registration.
curl -i -X POST \ 'https://{yourOktaDomain}/spiffe/api/v1/trust-domains' \ -H 'Authorization: Bearer {yourOktaAccessToken}' \ -H 'Accept: application/json' \ -H 'Content-Type: application/json' \ -d '{ "trustDomain": "example.org", "bundleUrl": "https://bundle.example.com/spiffe/bundle.json" }'- Set
You can also register a trust domain in the Admin Console. See Add SPIFFE trust domains (opens new window).
Note the following rules about how registration of a trust domain works:
- The
bundleUrlmust use HTTPS and can't contain a wildcard or credentials. Okta checks that it's a valid URL, but it doesn't request the URL when you register the trust domain. Confirm that the URL returns your trust domain's bundle before you register it. A wrong URL shows up later as a failed token request. - Each trust domain can have one registration, and you can't change
trustDomainafter you create it. An org can have up to 100 registrations. A duplicate or a request over the limit returns a409 Conflicterror.
Configure the client
Configure the client so that Okta can match a JWT-SVID to it. Okta matches the sub claim of the JWT-SVID to the SPIFFE ID of the client.
- Use an app integration if you manage the client's configuration in your org.
- Use a CIMD client if the app owner publishes the client's configuration at a URL.
Configure an app integration
In this scenario, you create or update the app integration for the workload.
Send a
POSTrequest to the Create an application (opens new window) endpoint to create the app integration for the workload. To update an existing app integration instead, send aPUTrequest to the Replace an application (opens new window) endpoint with the full app object.In the request body, set
credentials.oauthClient.token_endpoint_auth_methodtospiffe_jwtandsettings.oauthClient.spiffe_idto the SPIFFE ID of the workload. You must set both, and the trust domain of the SPIFFE ID must already be registered.curl -i -X POST \ 'https://{yourOktaDomain}/api/v1/apps' \ -H 'Authorization: Bearer {yourOktaAccessToken}' \ -H 'Accept: application/json' \ -H 'Content-Type: application/json' \ -d '{ "name": "oidc_client", "label": "Payments service", "signOnMode": "OPENID_CONNECT", "credentials": { "oauthClient": { "token_endpoint_auth_method": "spiffe_jwt" } }, "settings": { "oauthClient": { "application_type": "web", "grant_types": ["authorization_code"], "response_types": ["code"], "redirect_uris": ["https://example.com/oauth2/callback"], "spiffe_id": "spiffe://example.org/payments-service" } } }'Save the
client_idfrom the response. The workload sends it with every token request.
To create a service app, set application_type to service and grant_types to client_credentials in the request body, and omit the redirect URIs.
You can also set the authentication method and SPIFFE ID in the Admin Console. See Add a SPIFFE credential for client authentication (opens new window).
Note the following rules about how updating an app integration works:
- The
spiffe_idmust be a valid SPIFFE ID, can't contain a wildcard, and can't belong to another app integration in your org. - Single-page apps and the implicit and password grant types aren't supported with
spiffe_jwt. - Okta removes the
spiffe_idif you change the authentication method or delete the app integration. - If
spiffe_jwtisn't enabled for your org, Okta rejects the request.
Configure a CIMD client
For a CIMD client, you register the CIMD URL in your org, and the app owner, who hosts the CIMD document, adds the SPIFFE ID to it.
Register the CIMD URL as an app integration, or convert an existing app integration to use the CIMD URL. See Add a CIMD client to an app integration.
Ask the app owner to set
token_endpoint_auth_methodtospiffe_jwtin the CIMD document and to add thespiffe_idof the workload. The app owner can also addspiffe_bundle_endpoint.{ "client_id": "https://partner.example.com/.well-known/cimd/payments-service.json", "client_name": "Payments service", "redirect_uris": ["https://partner.example.com/callback"], "grant_types": ["authorization_code"], "token_endpoint_auth_method": "spiffe_jwt", "spiffe_id": "spiffe://example.org/payments-service", "spiffe_bundle_endpoint": "https://bundle.example.com/spiffe/bundle.json" }
Note the following rules about how updating a CIMD client works:
- Register the trust domain in your org first, even if the document includes
spiffe_bundle_endpoint. - If the document includes
spiffe_bundle_endpoint, it must match thebundleUrlthat you registered, or Okta rejects the request. If the document omits it, Okta uses the registeredbundleUrl. - The document doesn't need
jwksorjwks_uri. This is because Okta gets the signing keys from the trust domain. - Okta doesn't check that a SPIFFE ID is unique across CIMD clients.
Get a JWT-SVID
Get a JWT-SVID for the workload from your SPIFFE implementation. The workload requests it through the SPIFFE Workload API (opens new window). This section shows the request with the SPIRE agent command line. If you use a different SPIFFE implementation, use its Workload API.
Run the following command on the node where the workload runs to request a JWT-SVID. Set
-audienceto the issuer of the authorization server that receives the token request, and don't add other audiences. For the org authorization server, the audience is the issuer of your org, which ishttps://{yourOktaDomain}unless the client uses a custom domain issuer.spire-agent api fetch jwt \ -audience https://{yourOktaDomain}/oauth2/{authorizationServerId} \ -socketPath /tmp/spire-agent/public/api.sockSave the JWT-SVID that the command prints. You send it as the
client_assertionin the token request.Verify the claims in the JWT-SVID before you send it to Okta. A JWT-SVID has three parts separated by periods, and the claims are in the second part.
Decode the second part of the JWT-SVID. The following command uses
jq. Replace{jwtSvid}with the JWT-SVID.echo '{jwtSvid}' | cut -d. -f2 | tr '_-' '/+' | jq -R '@base64d | fromjson'The command prints the claims.
{ "sub": "spiffe://example.org/payments-service", "aud": "https://{yourOktaDomain}/oauth2/{authorizationServerId}", "exp": 1767225900, "iat": 1767225600, "jti": "5f0c2a9e-3b7d-4c1e-9a62-8d4b1e7f0a33" }The
expclaim is required. Theiatandjticlaims are optional. If the JWT-SVID includes ajti, Okta accepts it only once, so request a new JWT-SVID for each retry.Confirm that
subis the SPIFFE ID that you registered for the client.Confirm that
audis the issuer of the authorization server that receives the token request.Confirm that
expis in the future and no more than one hour from now.
If a claim doesn't match, request a new JWT-SVID with the correct audience, or correct the SPIFFE ID registered for the client. Request a new JWT-SVID before the current one expires.
After your SPIFFE implementation rotates its signing keys, Okta can reject a JWT-SVID that a new key signs until Okta refreshes its cached copy of the bundle.
Request a token
At this point, you have a JWT-SVID with the correct claims and the client_id of the client.
Next, send the JWT-SVID to the token endpoint of the authorization server as the client assertion. The request must also include the client_id, even though the JWT-SVID identifies the workload. For an app integration, the client_id is the Okta-generated client ID. For a CIMD client, it's the CIMD URL.
Request a token with the authorization code flow
Your app completes these steps. The user signs in during the authorization request.
Start the authorization request from the app so that the user signs in and Okta returns an authorization code. See Implement the authorization code flow. That guide's token request uses a client secret, so skip it and use the request in the next step.
Send a
POSTrequest to the/tokenendpoint (opens new window) to exchange the code for tokens.Set
client_assertion_typetourn:ietf:params:oauth:client-assertion-type:jwt-spiffeandclient_assertionto the JWT-SVID. If the app requires PKCE, also include thecode_verifierparameter.curl -i -X POST \ 'https://{yourOktaDomain}/oauth2/{authorizationServerId}/v1/token' \ -H 'Accept: application/json' \ -H 'Content-Type: application/x-www-form-urlencoded' \ --data-urlencode 'grant_type=authorization_code' \ --data-urlencode 'code={authorizationCode}' \ --data-urlencode 'redirect_uri=https://example.com/oauth2/callback' \ --data-urlencode 'client_id={clientId}' \ --data-urlencode 'client_assertion_type=urn:ietf:params:oauth:client-assertion-type:jwt-spiffe' \ --data-urlencode 'client_assertion={jwtSvid}'
Request a token with the client credentials flow
Use this flow when the workload acts on its own behalf and not for a user. AI agent CIMD clients can't use it. See Register AI agents with a CIMD.
Configure a service app as described in Configure an app integration, and confirm that a rule in the authorization server's access policy allows the
client_credentialsgrant type. See Configure an access policy.Send a
POSTrequest to the/tokenendpoint (opens new window) to get an access token. Okta returns the access token if the request succeeds.curl -i -X POST \ 'https://{yourOktaDomain}/oauth2/{authorizationServerId}/v1/token' \ -H 'Accept: application/json' \ -H 'Content-Type: application/x-www-form-urlencoded' \ --data-urlencode 'grant_type=client_credentials' \ --data-urlencode 'scope={scope}' \ --data-urlencode 'client_id={clientId}' \ --data-urlencode 'client_assertion_type=urn:ietf:params:oauth:client-assertion-type:jwt-spiffe' \ --data-urlencode 'client_assertion={jwtSvid}'
Note the following rules about how the token request works:
- Send only the JWT-SVID as the client credential, for a client that is set to
spiffe_jwt. A request with a second credential, such as a client secret, or a client that uses another method returns aninvalid_requesterror. - Okta matches the scheme and trust domain of the
subclaim without regard to case, but matches the path exactly. - Okta accepts a JWT-SVID that has a
jticlaim only once. Request a new JWT-SVID for each retry. - You can also use
spiffe_jwtto authenticate on the introspection and revocation endpoints. - The org authorization server accepts
spiffe_jwtfor service apps.
If authentication fails, Okta returns an invalid_client error. Check the following causes:
| Cause | What to check |
|---|---|
The sub claim doesn't match | Check that the SPIFFE ID registered for the client |
| The trust domain isn't registered | Check that the registration for the trust domain of the SPIFFE ID exists |
| Okta can't verify the signature | Check that the bundleUrl is reachable and that the bundle has a key for the JWT-SVID kid |
The aud claim is wrong | Check that it's the only audience and is the issuer of the authorization server |
| The JWT-SVID has expired | Check that exp is in the future and no more than one hour away |
Manage trust domains
A trust domain registration tells Okta where to get the keys that verify JWT-SVIDs from that trust domain. Keep the trust domain in sync with your SPIFFE setup. Update the registration if the URL of the bundle endpoint changes. Delete it if you stop using the trust domain, or to make room under the limit of 100 registrations per org.
The following tasks change the trust domain registration, but not the clients that use it. Each request needs the ID of the registration. To find it, send a GET request to the List all SPIFFE trust domain registrations (opens new window) endpoint with the query search=trustDomain eq "example.org".
Update the bundle endpoint
Update the registration when your SPIFFE implementation serves the trust domain's bundle from a different URL. Until you update it, Okta keeps requesting the old URL. To change the bundle endpoint of a trust domain, send a PUT request to the Replace a SPIFFE trust domain registration (opens new window) endpoint. Include the new bundleUrl and the existing trustDomain in the request body. The request can't change the trustDomain. If a CIMD document includes spiffe_bundle_endpoint, it must match the new bundleUrl, so ask the app owner to update it.
curl -i -X PUT \
'https://{yourOktaDomain}/spiffe/api/v1/trust-domains/{trustDomainRegistrationId}' \
-H 'Authorization: Bearer {yourOktaAccessToken}' \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-d '{
"trustDomain": "example.org",
"bundleUrl": "https://bundle.example.com/spiffe/new-bundle.json"
}'
Delete a trust domain
Delete the registration when you no longer use the trust domain, for example after you retire it or move its workloads to another trust domain. After you delete a trust domain, workloads in it can no longer authenticate with a JWT-SVID.
Find the app integrations and AI agents that use the trust domain.
- Send a
GETrequest to the List all applications (opens new window) endpoint with the queryfilter=spiffeTrustDomainId eq "{trustDomainRegistrationId}"andincludeNonDeleted=true. - Send a
GETrequest to the List all AI agents (opens new window) endpoint with the queryspiffeTrustDomainId={trustDomainRegistrationId}.
- Send a
Stop using the trust domain in each app integration and AI agent that the requests return, whether it's active or inactive. For an app integration, change its authentication method, change its
spiffe_idto a SPIFFE ID in another registered trust domain, or delete it. For an AI agent, change or delete it.Send a
DELETErequest to the Delete a SPIFFE trust domain registration (opens new window) endpoint to delete the registration. A successful request returns204 No Content.curl -i -X DELETE \ 'https://{yourOktaDomain}/spiffe/api/v1/trust-domains/{trustDomainRegistrationId}' \ -H 'Authorization: Bearer {yourOktaAccessToken}'
Note the following rules about deleting trust domains:
- The request returns a
409 Conflicterror while an app integration or AI agent, active or inactive, still has a SPIFFE ID in that trust domain. - Okta doesn't count CIMD clients in that check, and the
spiffeTrustDomainIdfilter doesn't return them. If you delete a trust domain that only CIMD clients use, the request succeeds and their token requests fail until you register the trust domain again.
See also
- Client authentication methods (opens new window)
- Register apps with a Client ID Metadata Document (CIMD)
- Register AI agents with a Client ID Metadata Document (CIMD)
- SPIFFE overview (opens new window)
- JWT-SVID specification (opens new window)
- OAuth SPIFFE Client Authentication (opens new window) (IETF Internet-Draft)