--- title: Configuring an X.509 Certificate IdP Adapter description: The X.509 Certificate IdP Adapter allows a PingFederate identity provider (IdP) server to perform client X.509 certificate authentication for single sign-on (SSO) to service provider (SP) applications. component: pingfederate version: 13.1 page_id: pingfederate:administrators_reference_guide:pf_configuring_x509_certificate_idp_adapter canonical_url: https://docs.pingidentity.com/pingfederate/13.1/administrators_reference_guide/pf_configuring_x509_certificate_idp_adapter.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: March 13, 2026 section_ids: about-this-task: About this task steps: Steps --- # Configuring an X.509 Certificate IdP Adapter The X.509 Certificate IdP Adapter allows a PingFederate identity provider (IdP) *(tooltip: \
\

A service that manages identity information and provides authentication services to relying clients or SPs within a federated or distributed network.\

\
)* server to perform client X.509 certificate authentication for single sign-on (SSO) *(tooltip: \
\

The process of authenticating an identity (signing on) at one website (usually with a user ID and password) and then accessing resources secured by other domains without reauthenticating.\

\
)* to 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.\

\
)* applications. ## About this task When PingFederate is acting as an IdP, this adapter validates X.509 certificates against the certificate authority (CA) *(tooltip: \
\

An entity that issues digital certificates.\

\
)* in the PingFederate certificate store. Use the **IdP Adapter** page to configure the X.509 Certificate IdP Adapter. ## 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. | | | | - | ---------------------------------------------------------------------------------------------------------------- | | | Use Object-Graph Navigation Language (OGNL) expressions to extract other information from the X.509 certificate. | 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 is 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. (Optional) On the **IdP Adapter** tab, in the **Constrain Acceptable Root Issuers** section, specify the CAs that you want to use to validate end-user X.509 certificates. | | | | - | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | | Client certificates are always validated against all trusted CAs in PingFederate and the Java Virtual Machine. This section only restricts which issuers are used to validate end-user certificates. | 1. Click **Add a new row to 'Constrain Acceptable Root Issuers'**. 2. In the **Issuer DN** field, enter the subject distinguished name (DN) of an issuer listed on the **Trusted CAs** window. Learn more in [Manage trusted certificate authorities](help_certmanagementtasklet_trustedcas_certmanagementstate.html). 3. In the **Action** column, click **Update**. 4. To add more acceptable issuers, repeat steps a - c. 5. Enter values for the adapter configuration, as described in the following table: | Field | Description | | ----------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Client Auth Port** | The port that PingFederate uses to validate client certificates. | | **Client Auth Hostname** | The PingFederate hostname that is configured to use client-certificate authentication. | | **Parse Client Cert Subject and Issuer DNs** | When enabled, the subject and issuer distinguished name (DN) *(tooltip: \
\

A name uniquely identifying an object within the hierarchy of a directory tree.\

\
)* in the client certificate are treated as separate attributes. This allows you to do the following:- Add subject or issuer DN attributes, such as CN or UID, to the adapter's extended contract. - Use the subject DN `email` attribute in the adapter's core contract.This option is enabled by default. | | **Match Issuer DN in Client X.509 Certificate** | Determines how PingFederate validates the issuer distinguished name (DN) for the client certificate.When selected, the issuer DN is matched against the entries that are defined in the **Constrain Acceptable Root Issuers** section.When cleared, the issuer DN is matched against the default top-level certificate in the chain that is presented by the client. | | **Advanced Fields** | | | **Return Success on SLO** | When enabled, a success message is sent in response when the adapter receives a single logout (SLO) *(tooltip: \
\

The process of signing a user out of multiple sites where the user has started a SSO session.\

\
)* request.SLO is not supported by this adapter and the user session is not terminated. This feature only prevents other sites from experiencing an SLO failure.This option is enabled by default. | | **Authentication Context** | The value used to populate the "Authentication Context" field in the Security Assertion Markup Language (SAML) *(tooltip: \
\

A standard, XML-based, message-exchange framework enabling the secure transmittal of authentication tokens and other user attributes across domains.\

\
)* token that PingFederate sends after validating the X.509 certificate.**Default**: Sets the value to "TLSClient".**Policy OID**: Sets the value to the identifier for the policy.**Custom**: Sets based on the value you enter in the **Custom Authentication Context** field. | | **Custom Authentication Context** | The value used to populate the **Authentication Context** field in the SAML token. Applies when **Authentication Context** is set to **Custom**. | | **Include Subject Alternative Name (SAN)** | When enabled, the adapter includes the following decoded SAN attributes from the X.509 certificate and makes them available in the attribute contract:- userPrincipalName - RFC822Name - fascn\_sen - fascn\_wo\_sen - fascn\_hex | 6. On the **Extended Contract** tab, add any attributes that you want to include in the extended contract. Enter attributes in uppercase. Only attributes specified in [RFC 2253](https://datatracker.ietf.org/doc/html/rfc2253/) are allowed: * `CN` * `L` * `ST` * `O` * `OU` * `C` * `STREET` * `DC` * `UID`. | | | | - | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | | You can include subject DN components in this list.If you selected **Parse Client Cert Subject and Issuer DNs** on the **IdP Adapter** tab, you can also include the subject DN `email` component, as well as issuer DN components.For issuer DN components, prefix the attribute with `issuer_`, such as`issuer_CN`. | 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's 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 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 isn't 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**.