PingFederate Server

Configuring SP connections for OAuth token exchange

Configure an service provider (SP) connection to exchange tokens for JSON Web Token (JWT) 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.

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:

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

  1. Click either Do Not Use A Template For This Connection or Use a Template For This Connection.

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

  3. Click Next.

Connection Type

  1. Select OAuth Token Exchange.

  2. Click Next.

General Info

  1. Configure the identifying information for your connection.

    Learn more about each field in Identifying the SP.

By default, the aud claim in the issued JWT token is set to the Partner’s Entity ID value.

OAuth Token Exchange

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

  1. In the Resource URIs field, enter a target URI from which to request the token exchange.

  2. Click Add.

  3. Repeat these steps to add multiple resource URIs.

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

  5. When you’re done adding URIs, click Next.

Token Lifetime

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

  2. Click Next.

Token Creation

  1. Click Configure Token Creation.

Attribute Contract

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

  2. When you’re done adding attributes, click Next.

Processor Policy Mapping

  1. Click Map Processor Policy Instance.

Processor Policy Instance

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

  2. Click Next.

Attribute Retrieval

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

Attribute Contract Fulfillment

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

    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.

  2. After mapping all attributes, click Next.

Issuance Criteria

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

    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.

  2. Click Next to review the summary of this SP connection, or Done to save the configuration.

Processor Policy Mapping and Summary

  1. After you finish mapping your processor policy, click Next.

  2. Review the summary of your token creation policy and click Done.

Token Creation and Summary

  1. After you finish configuring your token creation policy, click Next.

  2. Review the summary of your token exchange policy and click Done.

OAuth token exchange

  1. After you finish configuring your token exchange policy, click Next.

Credentials

  1. Click Configure Credentials.

Digital Signature Settings

  1. Configure the credentials for the SP connection.

Learn more in Configuring digital signatures for service provider connections.

Credentials

  1. After you configure your certificate, click Next.

Activation & Summary

  1. Review the details of your SP connection and click Save to activate it.