PingFederate Server

IdP endpoints

The following sections describe PingFederate identity provider (IdP) endpoints, including the case-sensitive query parameters that each accepts or requires. These endpoints accept either the HTTP GET or POST methods.

Begin each URL with the fully-qualified server name and port number of your PingFederate IdP server, for example, https://www.example.com:9031/idp/startSSO.ping.

When using the parameters TargetResource or TARGET with their own query parameters included, the parameter value must be URL-encoded. Any other parameters that contain restricted characters, such as many SAML URNs, also must be URL-encoded. For information about URL encoding, see third party resources such as HTML URL-encoding Reference. Parameters are case-sensitive.

You can customize and localize user-facing templates.

/idp/startSSO.ping

This is the path used to initiate an unsolicited IdP-initiated SSO transaction during which a SAML response containing an assertion is sent to a service provider (SP). Typically, a systems integrator or developer creates one or more links to this endpoint in the IdP application or portal to allow users to initiate SSO to various SPs.

For information about allowing applications to retrieve configuration data from the PingFederate server over SOAP, see Web service interfaces and APIs.

The following table shows the HTTP parameters for this endpoint.

Parameter Description

PartnerSpId or PARTNER

The federation ID of the SP to whom the SAML response containing an assertion should be issued. This ID value is case-sensitive.

One of these parameters is required unless the federation ID can be derived from TargetResource or TARGET.

TargetResource or TARGET

(optional)

For SAML 2.0, the value of either parameter is passed to the SP as the RelayState element of a SAML response message. This is the PingFederate implementation of the SAML 2.0 indicator for a desired resource at the SP during IdP-initiated SSO.

For SAML 1.x, the value is sent to the SP as a parameter named TARGET.The parameter value must be URL-encoded.

InErrorResource

(optional)

Indicates where the user is redirected after an unsuccessful SSO. If this parameter is not included in the request, PingFederate redirects the user to the SSO error landing page hosted within PingFederate.

Binding

(optional)

Indicates the binding to be used; allowed values are URIs defined in the SAML specifications. For example, the SAML 2.0 applicable URIs are:

  • urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Artifact

  • urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Post

When the parameter is not used, the default ACS URL configured for the SP-partner connection is used unless an ACS index is specified using the ACSIdx parameter.

ACSIdx

(optional - SAML 2.0)

Specifies the index number of partner’s ACS. For more information, see Setting Assertion Consumer Service URLs (SAML). Takes precedence over the Binding parameter if both are specified. If neither the binding nor index is specified in the call, the default ACS is used.

IdpAdapterId

(optional)

Allows an application to call out what IdP adapter to use for authentication in a configuration with multiple IdP adapters.

This parameter might be overridden by policy based on authentication policies. For example, a CIDR Authentication Selector instance could enforce the use of a given adapter instance based on whether a user is on or off the network. For more information, see Authentication policies.

ChangePassword

If a request includes this parameter with a value of true and invokes an HTML Form Adapter instance, the user is redirected to the Change Password template and prompted to update the network password.

To use this parameter, the Allow Password Changes check box must be selected in the adapter configuration of the invoked HTML Form Adapter instance. For more information, see Configuring an HTML Form Adapter instance.

RequestedFormat

(optional - SAML 2.0)

Allows control over the NameId format.

vsid

(optional)

Specifies the virtual server ID.

When absent, PingFederate uses the default virtual server ID, if specified, for the connection or the SAML federation ID defined in Server Settings. For more information, see Identifying the SP and Specifying federation information.

PolicyAction

(optional)

The HTML Form Adapter immediately returns the value of this parameter in the policy.action attribute, allowing the policy to bypass the adapter in favor of an alternative authentication source, provided a rule matching the action is configured. When this parameter is set to identity.registration and the adapter is followed by a local identity profile, the user is directed to the registration page for the profile.

/idp/startSLO.ping

This is the path used to start an IdP-initiated SLO (under SAML 2.0) or an OpenID Connect (OIDC) logout. For more information see Asynchronous Front-Channel Logout. Typically, a systems integrator or developer creates one or more links to this endpoint in the protected resources of their IdP application or portal to allow users to end their sessions at various SPs. This endpoint uses the local PingFederate session to determine which SPs have been issued an SSO assertion and sends them a SAML logout request.

PingFederate sends SLO requests in the following sequence, which prioritizes synchronous logouts:

  1. IdP adapters

  2. SAML IdP partners

  3. SP adapters

  4. SAML SP partners

  5. WS-Fed and OIDC partners in parallel

The LogoutType parameter lets you customize the SLO process. For example, you can change the SLO process so that it does not prioritize synchronous logouts.

To start with asynchronous logouts, you could chain the logouts. Start with /idp/startSLO.ping?LogoutType=AsyncOnly. Set the TargetResource to /idp/startSLO.ping?LogoutType=SyncOnly. In this case, you would also need to add the /idp/startSLO.ping endpoint as an allowed redirect for SLO on the Redirect Validation window.

To perform asynchronous and synchronous logouts in parallel, you could create a page with two iframes. One iframe points to /idp/startSLO.ping?LogoutType=AsyncOnly and the other points to /idp/startSLO.ping?LogoutType=SyncOnly.

The following table describes the HTTP parameters for this endpoint.

Parameter Description

TargetResource

(optional)

Indicates where the user is redirected after a successful SLO. If this parameter is not included in the request, PingFederate uses as a default the URL for a successful SLO as entered on the IdP Default URL window.

The parameter value must be URL-encoded.

InErrorResource

(optional)

Indicates where the user is redirected after an unsuccessful SLO. If this parameter is not included in the request, PingFederate redirects the user to the SLO error landing page hosted within PingFederate.

Binding

(optional - SAML 2.0)

Indicates the binding to use. The allowed values are URIs defined in the SAML specifications. The SAML 2.0 applicable URIs are:

  • urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Artifact

  • urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST

  • urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect

  • urn:oasis:names:tc:SAML:2.0:bindings:SOAP

When the parameter is not used, the first SLO Service URL configured for the SP-partner connection is used. For more information, see Specifying SLO service URLs (SAML 2.0).

LogoutType

(optional)

Controls which kinds of adapters and partners PingFederate will send SLO requests to. The allowed values are:

  • All(the default value) logs out all adapters and partners in the default sequence

  • SyncOnly logs out only SAML partners and adapters in series

  • AsyncOnly logs out only WS-Fed and OIDC partners in parallel

    When WS-Fed partner logout entries exist, LogoutType=AsyncOnly might still cause the log out of all partners and adapters. The reason is that WS-Fed logout requests to a partner might reflect back to PingFederate. For example, a wsignout1.0 request to an IdP reflects back to PingFederate as a wsignoutcleanup1.0 request. When PingFederate receives the signout request, there is no context connecting it to the original request. As a result, PingFederate performs a full SLO.

/idp/writecdc.ping

This endpoint is used for SAML 2.0 IdP Discovery. This is the path used when the IdP wants to write to the common domain cookie (CDC) held within the user’s browser. The information written to the cookie indicates from which IdP this user has authenticated.

The following table shows the one HTTP query parameter for this endpoint.

Parameter Description

TargetResource

(optional)

Indicates where the user is redirected after successful IdP Discovery. If this parameter is not included in the request, PingFederate redirects the user to the referrer in the HTTP header. If there is no TargetResource or referrer, the call to this endpoint will fail.

The parameter value must be URL-encoded.

/pf/idprofile.ping

This endpoint is used for profile management. When profile management is enabled for customer identities, authenticated users can review and modify the local identity fields that have been configured to be shown on the profile management page, connect or disconnect third-party identity providers, also known as Social Connections to the end users on the profile management page, and delete their local identities if the option to do so has been enabled. Each local identity profile has its own profile management URL.

The following table shows the one HTTP query parameter for this endpoint.

Parameter Description

LocalIdentityProfileID

Indicates which profile management page that PingFederate should serve to the authenticated users based on the ID of the local identity profile.

You can copy the profile management URL for a given local identity profile on its configuration summary window.

/pf/id/verification.ping

This endpoint is used for email ownership verification. When email ownership verification is enabled for customer identities, authenticated users can request additional email-verification notifications by accessing this endpoint.

The following table shows the one HTTP query parameter for this endpoint.

Parameter Description

LocalIdentityProfileID

Indicates the local identity profile from which the authenticated users, who are requesting additional email-verification notifications, originate.

You can copy the email ownership verification endpoint for a given local identity profile on its configuration summary window.

/ext/pwdchange/Identify

The Change Password endpoint allows users to change their password through an HTML Form Adapter instance without submitting SSO requests. This endpoint requires one parameter, AdapterId; the parameter value is the identifier of the HTML Form Adapter instance that has been configured with such capability. For example, if the fully-qualified name of your PingFederate environment and the adapter ID are www.example.com and HTMLFormSimplePCV respectively, the resulting URL is /https://www.example.com/ext/pwdchange/Identify?AdapterId=HTMLFormSimplePCV.

The following table shows the one additional HTTP query parameter for this endpoint.

Parameter Description

TargetResource

Indicates the desired destination after users have successfully change their network password.

When target resource validation is enabled for this endpoint, as indicated by the SLO and Other check box on the Security → System Integration → Redirect Validation → Local Redirect Validation tab, PingFederate honors the URL only if the parameter value satisfies the configured requirement on the Local Redirect Validation tab. If the validation fails, PingFederate displays the default success or error message.

For more information, see Configuring redirect validation.

/ext/pwdreset/Identify

The Account Recovery endpoint allows users to reset their password or unlock their account through an HTML Form Adapter instance without submitting SSO requests. This endpoint requires one parameter, AdapterId; the parameter value is the identifier of the HTML Form Adapter instance that has been configured with such capabilities. For example, if the fully-qualified name of your PingFederate environment and the adapter ID is www.example.com and HTMLFormSimplePCV respectively, the resulting URL is https://www.example.com/ext/pwdreset/Identify?AdapterId=HTMLFormSimplePCV.

The following table shows the one additional HTTP query parameter for this endpoint.

Parameter Description

TargetResource

Indicates the desired destination after users have successfully reset their network password or unlocked their account.

When target resource validation is enabled for this endpoint, as indicated by the SLO and Other check box on the Security → System Integration → Redirect Validation → Local Redirect Validation tab, PingFederate honors the URL only if the parameter value satisfies the configured requirement on the Local Redirect Validation tab. If the validation fails, PingFederate displays the default success or error message.

For more information, see Configuring redirect validation.

/ext/idrecovery/Recover

The Username Recovery endpoint allows users to recover their username through an HTML Form Adapter instance without submitting SSO requests. This endpoint requires one parameter, AdapterId; the parameter value is the identifier of the HTML Form Adapter instance that has been configured with such capabilities. For example, if the fully-qualified name of your PingFederate environment and the adapter ID is www.example.com and HTMLFormSimplePCV respectively, the resulting URL is /https://www.example.com/ext/idrecovery/Recover?AdapterId=HTMLFormSimplePCV.

The following table shows the one additional HTTP query parameter for this endpoint.

Parameter Description

TargetResource

Indicates the desired destination after users have successfully recovered their username.

When target resource validation is enabled for this endpoint, as indicated by the SLO and Other check box on the Security → System Integration → Redirect Validation → Local Redirect Validation tab, PingFederate honors the URL only if the parameter value satisfies the configured requirement on the Local Redirect Validation tab. If the validation fails, PingFederate displays the default success or error message.

For more information, see Configuring redirect validation.