The following sections describe PingFederate 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

Important:

When the parameter TargetResource (or TARGET) is used and includes its own query parameters, the parameter value must be URL-encoded.

Any other parameters that contain restricted characters (many SAML URNs, for example) also must be URL-encoded.

For information about URL encoding, please refer to third party resources, such as HTML URL-encoding Reference (www.w3schools.com/tags/ref_urlencode.asp).

User-facing templates can be customized and localized.

/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 an 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.

Note that 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 (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).
Note:

This parameter may be overridden by policy based on authentication policies. For example, an CIDR Authentication Selector instance could enforce the use of a given adapter instance based on whether a user is on or off the network (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.
Note:

In order to use this parameter, the Allow Password Changes check box must be selected in the adapter configuration of the invoked HTML Form Adapter instance (see Configuring an HTML Form Adapter instance).

RequestedFormat

(optional - SAML 2.0)

Allows control over the NameId format.
vsid

(optional)

Specify the virtual server ID.

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

/idp/startSLO.ping

This is the path used to initiate an IdP-initiated SLO (under SAML 2.0) or an OpenID Connect logout (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.

The following table shows 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 screen.

Note that 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 be used; 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 (see Specifying SLO service URLs (SAML 2.0)).

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

Note that 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.
Tip:

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

/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.
Tip:

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

/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.
Note:

When target resource validation is enabled for this endpoint, as indicated by the SLO and Other check box on the Security > Redirect Validation (Local Redirect Validation) screen, PingFederate honors the URL only if the parameter value satisfies the configured requirement on the Redirect Validation (Local Redirect Validation) screen. 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, unlock their account, or 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 are 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, unlock their account, or recover their username.
Note:

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

(For more information, see Configuring redirect validation.)