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 |
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 | ||
---|---|---|---|
|
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 |
||
(optional) |
For SAML 2.0, the value of either parameter is passed to the SP as the For SAML 1.x, the value is sent to the SP as a parameter named |
||
(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. |
||
(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 |
||
(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 |
||
(optional) |
Allows an application to call out what IdP adapter to use for authentication in a configuration with multiple IdP adapters.
|
||
|
If a request includes this parameter with a value of
|
||
(optional - SAML 2.0) |
Allows control over the |
||
(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. |
||
(optional) |
The HTML Form Adapter immediately returns the value of this parameter in the |
/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:
-
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 | ||
---|---|---|---|
(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. |
||
(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. |
||
(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). |
||
(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 |
---|---|
(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 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 | ||
---|---|---|---|
|
Indicates which profile management page that PingFederate should serve to the authenticated users based on the ID of the local identity profile.
|
/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 | ||
---|---|---|---|
|
Indicates the local identity profile from which the authenticated users, who are requesting additional email-verification notifications, originate.
|
/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 | ||
---|---|---|---|
|
Indicates the desired destination after users have successfully change their network password.
|
/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 | ||
---|---|---|---|
|
Indicates the desired destination after users have successfully reset their network password or unlocked their account.
|
/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 | ||
---|---|---|---|
|
Indicates the desired destination after users have successfully recovered their username.
|