--- title: Configuring SP connections for OAuth token exchange description: Configure an service provider (SP) connection to exchange tokens for JSON Web Token (JWT) tokens. component: pingfederate version: 13.1 page_id: pingfederate:administrators_reference_guide:pf_configuring_sp_connections_oauth_token_exchange canonical_url: https://docs.pingidentity.com/pingfederate/13.1/administrators_reference_guide/pf_configuring_sp_connections_oauth_token_exchange.html llms_txt: https://docs.pingidentity.com/pingfederate/llms.txt docs_for_agents: https://developer.pingidentity.com/build-with-ai/docs-for-agents.md revdate: April 10, 2026 section_ids: before-you-begin: Before you begin steps: Steps connection-template: Connection Template connection-type: Connection Type general-info: General Info oauth-token-exchange: OAuth Token Exchange protocol-settings: Protocol Settings token-lifetime: Token Lifetime token-creation: Token Creation attribute-contract: Attribute Contract processor-policy-mapping: Processor Policy Mapping processor-policy-instance: Processor Policy Instance attribute-retrieval: Attribute Retrieval choose-from: Choose from: attribute-contract-fulfillment: Attribute Contract Fulfillment issuance-criteria: Issuance Criteria processor-policy-mapping-and-summary: Processor Policy Mapping and Summary token-creation-and-summary: Token Creation and Summary oauth-token-exchange-2: OAuth token exchange credentials: Credentials digital-signature-settings: Digital Signature Settings credentials-2: Credentials activation-summary: Activation & Summary --- # Configuring SP connections for OAuth token exchange Configure an service provider (SP) *(tooltip: \
\

In SAML, an entity that receives and accepts an authentication assertion issued by an IdP, typically for the purpose of allowing access to a protected resource.\

\
)* connection to exchange tokens for JSON Web Token (JWT) *(tooltip: \
\

An IETF standard container format for a JSON object used for the secure exchange of content, such as identity or entitlement information. You can find the industry standard in \RFC 7519\.\

\
)* tokens. This capability lets clients or AI agents obtain tokens from third-party authorization servers using a cross-domain assertion. It also supports Identity Assertion JWT Authorization Grant (ID-JAG) token exchange. Learn more in [Configuring a Refresh Token Token Processor instance](pf_configuring_refresh_token_processor_instance.html). You can add the token exchange function to existing SP connections. This guide shows you how to create a new SP connection for token exchanges. ## Before you begin This process requires the following policies: * [OAuth token processor instance](pf_config_oauth_token_process_instance.html) * [Token exchange processor policy](pf_defining_token_exchange_processor_policies.html) * [Digital signing certificate](help_certmanagementtasklet_dsigsigningcert_certmanagementstate.html) You can create new processors and certificates for this configuration, or use existing ones. ## Steps 1. Go to **Applications > Integration > SP Connections**. 2. Click **Create Connection**. ## Connection Template 3. Click either **Do Not Use A Template For This Connection** or **Use a Template For This Connection**. 4. If you selected **Use a Template For This Connection**, select a connection template in the **Connection Template** list. | | | | - | ----------------------------------------------------------------------------------------------------------------------------------------------------- | | | When you select a connection template, many settings are configured automatically. However, you still need to configure the token exchange functions. | 5. Click **Next**. ## Connection Type 6. Select **OAuth Token Exchange**. 7. Click **Next**. ## General Info 8. Configure the identifying information for your connection. Learn more about each field in [Identifying the SP](help_spconnectionconfigtasklet_generalinfostate.html). | | | | - | ------------------------------------------------------------------------------------------------ | | | By default, the `aud` claim in the issued JWT token is set to the **Partner's Entity ID** value. | ## OAuth Token Exchange 9. Click **Configure OAuth Token Exchange**. ### Protocol Settings Specify a list of resource URIs that the PingFederate OAuth authorization server uses to select the token management instance when the `resource` parameter is provided in the token exchange request. 10. In the **Resource URIs** field, enter a target URI from which to request the token exchange. 11. Click **Add**. 12. Repeat these steps to add multiple resource URIs. 13. In **Allowed Requested Token Types**, select the **Identity Assertion JWT (ID-JAG)** checkbox to allow this connection to issue ID-JAG tokens through token exchange. 14. When you're done adding URIs, click **Next**. ### Token Lifetime 14. (Optional) Override the default token lifetime settings. The following table describes the fields: | Field | Description | | ------------------ | ---------------------------------------------------------------------------------------------------------------- | | **Minutes Before** | The amount of time before the JWT token was issued during which it's considered valid. The default value is `5`. | | **Minutes After** | The amount of time after the JWT token was issued during which it's considered valid. The default value is `30`. | 15. Click **Next**. ### Token Creation 16. Click **Configure Token Creation**. ### Attribute Contract 17. (Optional) In the **Extend the Contract** field, enter an attribute and click **Add**. Repeat this for every attribute you want to add to the contract. 18. When you're done adding attributes, click **Next**. ### Processor Policy Mapping 19. Click **Map Processor Policy Instance**. ### Processor Policy Instance 20. In the **Processor Policy Instance** list, select a processor policy instance. If you need to configure a new processor policy instance or edit an existing one, click **Manage Processor Policies**. Learn more in [Defining token exchange processor policies](pf_defining_token_exchange_processor_policies.html). 21. Click **Next**. ### Attribute Retrieval 22. Choose from: ### Choose from: * If the incoming token contains all the attributes that your application requires, select **Use only the attributes available in the incoming token**. This is the default option. * To set up a data store query, select **Use the incoming token to look up additional information** and then follow a series of sub-tasks to complete the configuration. Learn more in [Choosing a datastore](pf_choosing_datastore.html). ### Attribute Contract Fulfillment 23. For each **Attribute Contract** attribute, map a **Source** and a **Value**. The following table describes the available options for each field: | **Source** | **Value** | | -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Context** | When selected, the **Value** list is populated with attributes from the token processor instance. Select the desired attribute in the list.At runtime, the attribute value is mapped to the value of the attribute in the SAML security token. | | **Expression** | This option provides more complex mapping capabilities, such as transforming incoming values into different formats.Select **Expression** in the **Source** list, click **Edit** under **Actions**, and compose your OGNL expressions. All variables for text entries are also available for expressions.Learn more in the **Text** description below\.Expressions aren't enabled by default. Learn more about enabling and editing OGNL expressions in [Attribute mapping expressions](pf_attribute_mapping_expressions.html). | | **No Mapping** | Select this option to ignore the **Value** field. | | **Processor Policy** | In the **Value** list, select attributes associated with the processor policy. | | **Text** | When selected, the text you enter is mapped to the token value of the attribute in the OAuth tokens at runtime.You can mix text with references to any of the values from the authentication source using the `${attributeName:-defaultValue}` syntax. If specified, the default value will be used at runtime when the attribute value isn't available. | 24. After mapping all attributes, click **Next**. ### Issuance Criteria 25. (Optional) Define issuance criteria for PingFederate to use to evaluate whether clients are authorized to perform token exchanges. For each evaluation criteria you want to add, complete the following steps: 1. Select an attribute **Source** and an **Attribute Name**: | **Source** | **Description** | | --------------------- | -------------------------------------------------------------------------------------- | | **Context** | Select to evaluate properties returned from the context of the transaction at runtime. | | **Mapped Attributes** | Select to evaluate mapped attributes. | | **Processor Policy** | Select to evaluate attributes from the processor policy instance. | 2. In the **Condition** list, select an evaluation method. The available methods are: * **equal to** * **equal to (case insensitive)** * **equal to DN** * **not equal to** * **not equal to (case insensitive)** * **not equal to DN** * **multi-value contains** * **multi-value contains (case insensitive)** * **multi-value contains DN** * **multi-value does not contain** * **multi-value does not contain (case insensitive)** * **multi-value does not contain DN** 3. In the **Value** field, enter a comparison value. | | | | - | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | | Values are compared verbatim. If you require complex evaluations, including conditional criteria or partial matching, define them using [attribute mapping expressions](pf_attribute_mapping_expressions.html). | 4. In the **Error Result** field, enter an error code. Using an error code in the **Error Result** field allows an application to process the code in a variety of ways, such as displaying an error message or e-mailing an administrator. 5. Click **Add**. 26. Click **Next** to review the summary of this SP connection, or **Done** to save the configuration. ### Processor Policy Mapping and Summary 27. After you finish mapping your processor policy, click **Next**. 28. Review the summary of your token creation policy and click **Done**. ### Token Creation and Summary 29. After you finish configuring your token creation policy, click **Next**. 30. Review the summary of your token exchange policy and click **Done**. ### OAuth token exchange 31. After you finish configuring your token exchange policy, click **Next**. ## Credentials 32. Click **Configure Credentials**. ### Digital Signature Settings 33. Configure the credentials for the SP connection. Learn more in [Configuring digital signatures for service provider connections](pf_configuring_digital_signatures_service_provider_connections.html). ## Credentials 34. After you configure your certificate, click **Next**. ## Activation & Summary 35. Review the details of your SP connection and click **Save** to activate it.