--- title: SP services description: 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. component: pingfederate version: 13.0 page_id: pingfederate:developers_reference_guide:pf_sp_services canonical_url: https://docs.pingidentity.com/pingfederate/13.0/developers_reference_guide/pf_sp_services.html revdate: July 5, 2022 section_ids: spStartSsoPing: /sp/startSSO.ping spstartslo-ping: /sp/startSLO.ping spDefederatePing: /sp/defederate.ping spcdcstartsso-ping: /sp/cdcstartSSO.ping spStartAttributeQueryPing: /sp/startAttributeQuery.ping --- # 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](https://www.w3schools.com/tags/ref_urlencode.asp). 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](pf_web_service_interface_api.html). 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 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](../administrators_reference_guide/help_localsettingstasklet_configspeventsstate.html) and [Configuring default target URLs](../administrators_reference_guide/help_idpprotocolsettingstasklet_defaulttargeturlstate.html). | | `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](../administrators_reference_guide/pf_custom_user_facing_pages.html). | | `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)](../administrators_reference_guide/pf_specifying_sso_service_urls_saml.html). | | `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](https://openid.net/specs/openid-connect-core-1_0.html).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](https://docs.oasis-open.org/security/saml/v2.0/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](../administrators_reference_guide/pf_sp_affiliat.html). | | `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](../administrators_reference_guide/help_idpconnectionconfigtasklet_generalinfostate.html) and [Specifying federation information](../administrators_reference_guide/help_protocolsettingstasklet_federationinfostate.html). | | `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](../administrators_reference_guide/help_targeturlmappingtasklet_targeturlmappingstate.html). 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)](../administrators_reference_guide/help_spprotocolsettingstasklet_sloserviceurlconfigstate.html). | | `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](../administrators_reference_guide/pf_custom_user_facing_pages.html). | ## /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](../introduction_to_pingfederate/pf_standard_idp_discov.html) . 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](../introduction_to_pingfederate/pf_attrib_query_xasp.html). 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 . 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](../administrators_reference_guide/help_idpconnectionconfigtasklet_generalinfostate.html) and [Specifying federation information](../administrators_reference_guide/help_protocolsettingstasklet_federationinfostate.html). |