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
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.
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:
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 The
default is |
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 The default is
|
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.
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:
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).
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
If not specified, the parameter defaults to
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 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). |