PingFederate Server

SP services

The following sections describe PingFederate service provider (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.

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.

/sp/startSSO.ping

This is the path used to initiate SP-initiated single sign-on (SSO). In this scenario, the SP issues an SSO request to the identity provider (IdP) asking for an SSO authentication response. Typically, a systems integrator or developer creates links to this endpoint in SP applications to allow users to access various protected resources through 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.

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 can 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 the target applications where a successful SSO redirects the end-user.

The parameter value must be URL-encoded.

When this parameter is not provided in the URL, you can specify a default target resource in the administrative console, either for all IdP connections, for individual connections, or both. For more information, see Configuring default URLs and Configuring default target URLs.

InErrorResource

(optional)

This parameter indicates where an unsuccessful SSO redirects the end-user. If this parameter is not included in the request, PingFederate redirects the user to the single log-out (SLO) error landing page hosted within PingFederate. For more information, see Customizable user-facing pages.

Binding

(optional)

Indicates the binding to use; 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. For more information, 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. For more information, see section 3.4.1.3.1 of the OASIS SAML document .

You can specify multiple values 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, see the OpenID Connect specification.

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. For more information, 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.

You can specify multiple values 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. For more information see section 2.7.2.2 of the OASIS SAML document .

You can specify multiple values 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 AuthnRequest does not include the attribute.

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. For more information, see SP affiliations.

vsid

(optional)

Specify 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 partner 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.

If SpSessionAuthnAdapterId specifies an adapter, 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 window. For more information, 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 depends 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 a successful SLO redirects the user. If the request does not include this parameter, PingFederate uses the URL for a successful SLO as a default, as entered on the SP Default URLs window.

Note that the parameter value must be URL-encoded.

Binding

(optional - SAML 2.0)

Indicates the binding to use; 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. For more information, see Specifying SLO service URLs (SAML 2.0).

InErrorResource

(optional)

Indicates where an unsuccessful SLO redirects the user. If the request does not include this parameter, PingFederate redirects the user to the SLO error landing page hosted within PingFederate. For more information, see Customizable user-facing pages.

/sp/defederate.ping

This path terminates an account link created during SSO. Account linking provides a means for subject identification on the SP side. On the SP side, only users create and terminate links. 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 through account linking on the same PingFederate session, this endpoint will terminate each of those links. A local logout is also performed for any link that is terminated.

/sp/cdcstartSSO.ping

This endpoint is used for IdP-Discovery implementations. For more information, 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 initiates an Attribute Query with a SAML 2.0 IdP. For more information, see Attribute Query and XASP.

The following table shows the HTTP parameters for this endpoint.

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 X.509 attribute sharing profile (XASP) is used, which uniquely identifies the entity that issued the user’s certificate. The parameter must be URL-encoded.

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. Without this parameter, the Subject and Issuer are used to determine the correct IdP.

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. For more information, see section 8.3 of the SAML specifications.

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.

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 → System Integration → Service Authentication window.

To avoid recording this parameter in web server logs, only pass it in the message body using the HTTP POST method.

RequestedAttrName

(optional)

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

You can specify multiple values 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 or the SAML federation ID defined in Server Settings. For more information, see Identifying the partner and Specifying federation information.