--- title: Configuring an OpenToken IdP Adapter instance description: Configure an instance of the OpenToken IdP Adapter in PingFederate. component: pingfederate version: 13.0 page_id: pingfederate:administrators_reference_guide:pf_configuring_opentoken_idp_adapter_instance canonical_url: https://docs.pingidentity.com/pingfederate/13.0/administrators_reference_guide/pf_configuring_opentoken_idp_adapter_instance.html revdate: Aprl 24, 2026 page_aliases: ["pf_config_opentoken_idp_adapt_instance.adoc"] section_ids: about-this-task: About this task steps: Steps --- # Configuring an OpenToken IdP Adapter instance Configure an instance of the OpenToken IdP Adapter in PingFederate. ## About this task Configure an OpenToken Identity Provider (IdP) Adapter instance using the administrative console to enable a secure authentication plugin for your custom application. ## Steps 1. Go to **Authentication > Integration > IdP Adapters**. 2. On the **IdP Adapters** page, click **Create New Instance** to start the **Create Adapter Instance** configuration. 3. On the **Type** tab, configure the basics of this adapter instance: 1. Enter the **Instance Name** and **Instance ID**. 2. In the **Type** list, select the adapter type. 3. (Optional) In the **Parent Instance** list, select an existing type. If you're creating an instance that's similar to an existing instance, consider making it a child instance by specifying a parent. A child instance inherits the configuration of its parent unless overridden. You can specify overrides during the rest of the setup. 4. On the **IdP Adapter** tab, configure your OpenToken IdP Adapter instance. | | | | - | ------------------------------------------------------- | | | These values depend on your developer's implementation. | Learn more in the **Description** field provided on-window and in the following table. **PingFederate's field names and descriptions for creating an OpenToken IdP Adapter instance** | Field | Description | | ------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Password**(Required) | The password to use for generating the encryption key. It is also known as the shared secret. | | **Confirm Password** | Re-enter the password to use for generating the encryption key. It is also known as the shared secret. | | **Authentication Service**(Required) | The URL to which the user is redirected for a single sign-on (SSO) event. This URL is part of an external application, which performs user authentication. | | Click **Show Advanced Fields** in the **Instance Configuration** tab to review the following settings. Modify as needed. | | | **Transport Mode** | How the token is transported to and from the application, either through a query parameter, a cookie (default), or as a form POST. | | **Token Name**(Required) | The name of the cookie or query parameter that contains the token. This name must be unique for each adapter instance. Override the default value `opentoken` as needed. | | **Cipher Suite** | The algorithm, cipher mode, and key size that should be used for encrypting the token. The default selected value is **AES-128/CBC**. | | **Logout Service** | The URL to which the user is redirected for a single-logout event. This URL is part of an external application, which terminates the user session. | | **Cookie Demain** | The server domain; for example, `example.com`. If no domain is specified, the value is obtained from the request. | | **Cookie Path** | The path for the cookie that contains the token. | | **Token Lifetime**(Required) | The duration in seconds for which the token is valid. Valid range is 1 to 28800. The default value is `300` (5 minutes). | | **Session Lifetime**(Required) | The duration in seconds for which the token may be re-issued without authentication. Valid range is 1 to 259200. The default value is `43200` (12 hours). | | **Not Before Tolerance**(Required) | The amount of time in seconds to allow for clock skew between servers. Valid range is 0 to 3600. The default value is `0`. | | **Force SunJCE Provider** | If selected, the SunJCE provider is forced for encryption and decryption. | | **Use Verbose Error Messages** | If selected, use verbose TokenException messages. | | **Obfuscate Password** | If selected, the default, the password is obfuscated and password-strength validation is applied. Clearing the checkbox allows backward compatibility with previous OpenToken agents. | | **Session Cookie** | If selected, OpenToken is set as a session cookie, rather than a persistent cookie. Applies only if the **Transport Mode** field is set as **Cookie**. The checkbox is not selected by default. | | **Secure Cookie** | If selected, the OpenToken cookie is set only if the request is on a secure channel (https). Applies only if the **Transport Mode** field is set to **Cookie**. The checkbox is not selected by default. | | **Delete Cookie** | If selected, the token cookie is deleted immediately after consumption. Applies only if the **Transport Mode** field is set to **Cookie**. The checkbox is not selected by default. | | **Replay Prevention** | Selecting this option is recommended only if **Query Parameter** is the chosen token transport mode and form POST is used by an associated connection to send the SAML assertion. If selected, PingFederate ensures that the token can be used only once. By default, the checkbox is not selected. Selecting this option might affect resource utilization and performance. | | **Skip Malformed Attribute Detection** | If not selected, the default, it prevents insecure content from affecting the security of your application and the agent. Update your applications with the latest version of the agent. We recommend not to change the value of this flag. | 5. On the **Actions** tab, click **Download** under **Action Invocation Link**, and then click **Export** to save the properties file. The values in the resulting file, `agent-config.txt`, represent the console configuration and are used by the Identity Provider (IdP) application. You can find more information in the documentation of your respective integration kit. 6. On the **Extended Contract** tab, configure additional attributes for this adapter instance as needed. The OpenToken IdP Adapter contract includes one core attribute: `subject`. The OpenToken IdP Adapter always extends the core contract with an attribute `userId` as well and fulfills it with the value of `subject` for backward compatibility reason. 7. On the **Adapter Attributes** tab, do the following: 1. (Optional) In the **Unique User Key Attribute** list, select an attribute to uniquely identify users signing on with this adapter. The attribute's value is used to identify user sessions across all adapters. **None** is selected by default. | | | | - | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | | If you choose a custom user key attribute, PingFederate uses the value of the attribute after the Adapter Contract Mapping (if any) has been evaluated. If you choose a custom user key attribute that is based on the username, configure the adapter's password credential validator (PCV) *(tooltip: \
\

Configures a centralized location for user credential validation. The validator instances can then be referenced by PingFederate.\

\
)* to trim spaces. | | | | | - | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | | For the HTML Form Adapter, If you enabled the **Revoke Sessions after Password Change or Reset** option on the **IdP Adapter** tab, you cannot select **None** as the unique user key attribute. Doing so results in an error message. | 2. Select the checkbox under **Pseudonym** for the user identifier of the adapter and optionally for the other attributes, if available. This selection is used if any of your 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.\

\
)* partners use pseudonyms for account linking. | | | | - | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | | A selection is required whether or not you use pseudonyms for account linking. This allows account linking to be used later without having to delete and reconfigure the adapter. Ensure that you choose at least one attribute that is unique for each user, such as a user's email, to prevent assigning the same pseudonym to multiple users. | 3. Select the checkbox under **Mask Log Values** for any attributes whose values you want PingFederate to mask in its logs at runtime. | | | | - | ------------------------------------------------------------------------------------------------------------------------------------------------ | | | Masking is not applied to the unique user key attribute in the logs even though the attribute used for the key is marked as **Mask Log Values**. | 4. If you plan to use OGNL expressions to map derived values into outgoing assertions and want those values masked, select the **Mask all OGNL-expression generated log values** checkbox. 8. []()(Optional) On the **Adapter Contract Mapping** tab, configure the adapter contract for this instance with the following optional workflows: * Configure one or more data sources for datastore queries. * Fulfill adapter contract with values from the adapter, the default, datastore queries, if configured, context of the request, text, or expressions, if enabled. * Set up the Token Authorization framework to validate one or more criteria prior to the issuance of the adapter contract. 9. On the **Summary** tab, review your configuration and modify as needed. Click **Save**. 10. When finished in the **IdP Adapters** window, click **Save** to confirm the adapter instance configuration. If you want to exit without saving the configuration, click **Cancel**.