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 single sign-on (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:
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. Note:
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. Note:
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. |
/idp/startSLO.ping
This is the path used to start an IdP-initiated SLO (under SAML 2.0) or an OpenID Connect 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.
- IdP adapters
- SAML IdP partners
- SP adapters
- SAML SP partners
- 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:
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:
|
/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. Tip:
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. Tip:
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. Note:
When target resource validation is enabled for this endpoint, as indicated by the SLO and Other check box on the 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. Note:
When target resource validation is enabled for this endpoint, as indicated by the SLO and Other check box on the 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. Note:
When target resource validation is enabled for this endpoint, as indicated by the SLO and Other check box on the 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. |