The following sections describe PingFederate SP endpoints, including the 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 SP server; for example: https://www.example.com:9031/sp/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).

Parameters are case-sensitive.

/sp/startSSO.ping

This is the path used to initiate SP-initiated SSO. In this scenario, the SP issues an SSO request to the IdP asking for an SSO authentication response. Typically, a systems integrator or developer creates one or more links to this endpoint in SP applications to allow users to access various protected resources via SSO using the IdP as an authentication authority.

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.

Note:

Some parameters described below can have multiple values. Specify these values by using multiple independent query string parameters of the same name.

Parameter Description
PartnerIdpId The federation ID of the IdP that authenticates the user and issues an assertion. This ID is case-sensitive.

Required if more than one IdP connection is configured and Domain is not used, and SP authentication policies are turned off.

Not required if SP authentication policies are turned on.

SpSessionAuthnAdapterId The explicit SP adapter instance ID indicating the adapter to use to create an authenticated session or security context.

Optional if SP authentication policies are turned off.

Required if SP authentication policies are turned on unless the PingFederate SP server is able to determine the applicable SP adapter instance based on the target URL mapping configuration and the TargetResource or TARGET value at runtime.

TargetResource or TARGET This parameter indicates where the end-user is redirected after a successful SSO (the target applications).

Note that the parameter value must be URL-encoded.

When this parameter is not provided in the URL, a default target resource may be specified in the administrative console, either for all IdP connections (see Configuring default URLs) or for individual connections (see Configuring default target URLs), or both.

InErrorResource

(optional)

This parameter indicates where the end-user is redirected after an unsuccessful SSO. If this parameter is not included in the request, PingFederate redirects the user to the SLO error landing page hosted within PingFederate (see Customizable user-facing screens).
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
urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect 

When the parameter is not used for SAML 2.0, the first SSO Service URL configured for the IdP-partner connection is used (see Specifying SSO service URLs (SAML)).

AllowCreate

(optional - SAML 2.0)

Controls the value of the AllowCreate attribute of the NameIDPolicy element in the AuthnRequest. (The default is true.)
AuthenticatingIdpId

(optional - SAML 2.0)

This parameter indicates the preferred IdP for authenticating the user through an IdP proxy, such as PingOne® for Enterprise. The parameter specifies the value of the ProviderID attribute in the Scoping/IDPList/IDPEntry element in the AuthnRequest (see section 3.4.1.3.1 of the OASIS SAML document saml-core-2.0-os.pdf).

Multiple values are permitted in order to build a preferred list.

ForceAuthn

(optional - SAML 2.0 or OpenID Connect)

For SAML 2.0, this parameter controls the attribute of the same name in the AuthnRequest.

For OpenID Connect, a value of true sets the prompt parameter in the authentication request to login. For more information about the authentication request and its parameter, please refer to the OpenID Connect specification (openid.net/specs/openid-connect-core-1_0.html#AuthRequest).

The default is false.

IsPassive

(optional - SAML 2.0 or OpenID Connect)

For SAML 2.0, this parameter controls the attribute of the same name in the AuthnRequest.

For OpenID Connect, a value of true sets the prompt parameter in the authentication request to none.

The default is false.

RequestedACSIdx

(optional - SAML 2.0)

The index number of your site's Assertion Consumer Service, where you want the assertion to be sent.
RequestedAcsUrl

(optional - SAML 2.0)

The URL of your site's Assertion Consumer Service, where you want the assertion to be sent.
RequestedAuthnCtx

(optional - SAML 2.0 or OpenID Connect)

For SAML 2.0, this parameter indicates the requested authentication context of the assertion; allowed values include URIs defined in the SAML specifications (see the OASIS SAML document saml-authn-context-2.0-os.pdf).

For OpenID Connect, the specified value becomes the acr_values parameter value in the authentication request.

Multiple values are permitted in order to build a preferred list.

RequestedAuthnDeclRef

(optional - SAML 2.0)

An alternative to RequestedAuthnCtx, above, indicating the requested authentication context of the assertion by declaring any URI reference (see section 2.7.2.2 of the OASIS SAML document saml-core-2.0-os.pdf).

Multiple values are permitted in order to build a preferred list.

RequestedBinding

(optional - SAML 2.0)

Indicates the binding requested for the response containing the assertion; allowed values are URIs defined in the SAML specifications.
RequestedFormat

(optional - SAML 2.0)

Specifies the value for the Format attribute in the NameIDPolicy element of the AuthnRequest. If not specified, the attribute is not included in the AuthnRequest.
RequestedSPNameQualifier

(optional - SAML 2.0)

Indicates that the IdP should return the given name qualifier as part of the assertion (used primarily to identify SP affiliations, see SP affiliations).
vsid

(optional)

Specify the virtual server ID.

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

If an adapter is specified in SpSessionAuthnAdapterId, then that adapter is used to create an authenticated session for SP-initiated SSO. If there is no SpSessionAuthnAdapterId, the ultimate destination of the user after SSO (either the TargetResource or the default SSO success URL) is used along with the mappings defined in the administrative console on the Map URLs to Adapter Instances screen (see Configuring target URL mapping).

Note that adapter selection for SP-initiated SSO is similar to that for IdP-initiated SSO except that, because the adapter ID is dependent on the SAML deployment, PingFederate cannot expect it from an IdP. Therefore, it uses only the URL mapping for adapter selection for SSO.

/sp/startSLO.ping

This is the path used to initiate SP-initiated SLO. Typically, a systems integrator or developer creates one or more links to this endpoint in the protected resources of their SP application, which allows users to end a session by sending a logout request to the IdP that authenticated the session.

Note that the IdP might send additional logout request messages to other SPs when it receives a logout request from a PingFederate server acting as an SP.

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 SP Default URLs screen.

Note that the parameter value must be URL-encoded.

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 IdP-partner connection is used (see Specifying SLO service URLs (SAML 2.0)).

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 (see Customizable user-facing screens).

/sp/defederate.ping

This is the path used to terminate an account link created during SSO. Account linking provides a means for subject identification on the SP side. Links are created and terminated entirely by a user on the SP side. The link contains the name identifier from the IdP, the IdP's federation ID, the adapter instance ID, and the local user identifier.

There are no HTTP parameters for this endpoint.

You can unlink a user session only if it was established during SSO using an existing account link on the SP side. If more than one SP session was established via account linking on the same PingFederate session, each of those links will be terminated by this endpoint. A local logout is also performed for any link that is terminated.

/sp/cdcstartSSO.ping

This endpoint is used for IdP-Discovery implementations (see Standard IdP Discovery). This endpoint is similar to /sp/startSSO.ping and accepts the same parameters, with the exception of PartnerIdpId and vsid. Instead of this parameter, the server attempts to use the common domain cookie to determine the IdP.

/sp/startAttributeQuery.ping

This endpoint is used to initiate an Attribute Query with a SAML 2.0 IdP (see Attribute Query and XASP).

The following table shows the HTTP parameters for this endpoint.
Note:

Some parameters described below can have multiple values. Specify these values by using multiple independent query string parameters of the same name.

Parameter Description
Subject Uniquely identifies the user to the IdP. When user authenticates with an X.509 certificate, this is the Subject DN, which must be URL-encoded.
Issuer

(optional)

The IssuerDN from the user's X.509 certificate (when XASP is used), which uniquely identifies the entity that issued the user's certificate. The parameter must be URL-encoded.
Note:

When specified this parameter overrides the Subject parameter.

PartnerIdpId

(except for XASP)

Used to identify the specific IdP partner to which the Attribute Query should be sent. If this parameter is not present, the Subject and Issuer are used to determine the correct IdP.
Note:

For XASP, this parameter overrides both the Subject and Issuer parameters.

Format

(required for XASP, otherwise optional)

Identifies the name-identifier format of the Subject query parameter. If included, the value must be one of the SAML 2.0 Name Identifier Format URIs (see section 8.3 of the SAML specifications (docs.oasis-open.org/security/saml/v2.0/saml-core-2.0-os.pdf).
Note:

For XASP, this parameter must be set to urn:oasis:names:tc:SAML:1.1:nameid-format:X509SubjectName.

If not specified, the parameter defaults to urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified.

Note that the parameter must be URL-encoded.

AppId The unique identifier of the initiating application.
SharedSecret Used to authenticate the initiating application. Both the AppId and SharedSecret values must match those defined on the Security > Service Authentication screen.
Important:

This is a sensitive parameter. To avoid recording it in web server logs, we recommend to only pass in this parameter (via the HTTP POST method) in the message body, instead of in a query string.

RequestedAttrName

(optional)

A name of a user attribute requested from the IdP. For each such desired user attribute, include this parameter. If this parameter is not present, then all allowable user attributes are returned from the IdP.

Multiple values are permitted in order to build a preferred list.

vsid

(optional)

Specify the virtual server ID.

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