These endpoints apply to the PingFederate server generally, whether used as an IdP, SP, or both.
Parameters are case-sensitive.
/pf/heartbeat.ping
This endpoint returns an HTTP status code of 200 and a message body of OK if the PingFederate runtime server is up and functional. You can customize the message by modifying a PingFederate property and a Velocity template file (see Customizing the heartbeat message).
If a GET request receives a connection error or an HTTP status code other than 200, the server associated with the endpoint is down or malfunctioning.
Load balancers can use this endpoint to determine the status of PingFederate independently of checks used to determine the status of the supporting hardware.
You can also configure the server to provide regular status information to a network-management utility (see Runtime reporting).
/pf/adapter2adapter.ping
This endpoint initiates direct IdP-to-SP adapter mapping, when that feature is configured on the Adapter-to-Adapter Mappings screen (see Adapter-to-adapter mappings).
To prevent users from circumventing the SP authentication policies, this endpoint becomes inactive when SP authentication policies are enabled but IdP authentication policies are disabled. Administrators can configure SP authentication policies for the internal users to re-enable access to protected resources.
For information, see Configure SP authentication policies for internal users.
The following table shows the HTTP parameters for this endpoint.
| Parameter | Description |
|---|---|
| TargetResource (optional) |
Indicates where the user is redirected after a successful SSO. If this parameter is not included in the request, PingFederate redirects the user to a default location if one is specified on the screen. |
| InErrorResource (optional) |
Indicates where the user is redirected if the SSO is unsuccessful. If this parameter is not included in the request, PingFederate redirects the user to the SSO error landing page hosted within PingFederate (see Customizable user-facing screens). |
| IdpAdapterId (optional) |
Indicates the IdP adapter instance to use for authentication if more than one IdP adapter is configured in adapter-to-adapter mappings. |
| SpSessionAuthnAdapterId (optional) |
Indicates the SP adapter instance to be used. If not provided and more than one SP adapter instance is configured with adapter-to-adapter mapping, PingFederate selects one based entries defined on the screen (see Configuring target URL mapping). |
| ChangePassword | If a request
includes this parameter with a value of true and invokes an HTML Form Adapter
instance, the user is redirected to the Change Password template and
prompted to update the network password. Note:
In order to use this parameter, the Allow Password Changes check box must be selected in the adapter configuration of the invoked HTML Form Adapter instance (see Configuring an HTML Form Adapter instance). |
/pf/sts.wst
This endpoint initiates direct STS token-to-token exchange and token validation from an IdP token processor to an SP token generator, when that feature is configured on the Token Translator Mappings screen (see Token translator mappings).
The following table shows the HTTP parameters for this endpoint.
| Parameter | Description |
|---|---|
| TokenProcessorId | Indicates the IdP token processor to use in the mapping. Required when multiple IdP token processors are configured in token-to-token mappings. |
| TokenGeneratorId | Indicates the SP token generator to use in the mapping. Required when multiple SP token generators are configured in token-to-token mappings. |
If mutual SSL/TLS is used for authentication, a secondary PingFederate listening port must be configured and used by partners or STS clients for the relevant endpoints—*.ssaml* and *.wst (see Configuring PingFederate properties).
/pf/sts_mex.ping
This endpoint returns STS metadata for use in expediting configuration of web-service applications.
The following table shows the HTTP parameters for this endpoint:
| Parameter | Description |
|---|---|
| PartnerSpId | The connection ID of the SP to whom the SAML token will be issued. This parameter determines the connection for which metadata will be generated. |
| PartnerIdpId | The connection ID of the IdP issuing the SAML token to be consumed by PingFederate. This parameter determines the connection for which the metadata will be generated. |
| vsid (optional) |
Specify the virtual server ID. If absent, PingFederate uses the default virtual server ID (if specified) for the connection or the federation ID defined on the screen. |
If your partner fails to retrieve metadata when sending both the PartnerSpId (or the PartnerIdpId) and the vsid query parameters, perhaps it is only capable of sending one query parameter in such requests. An alternative metadata exchange endpoint that includes the virtual server ID information should resolve the issue.
For more information, see Constructing an alternative metadata exchange endpoint.
/pf/federation_metadata.ping
This endpoint returns SAML and WS-Federation metadata.
The following table shows the HTTP parameters for this endpoint:
| Parameter | Description |
|---|---|
| PartnerSpId | The connection ID of the SP to whom the assertions or tokens are issued. This parameter determines the connection for which metadata is generated. |
| PartnerIdpId | The connection ID of the IdP issuing the assertions or tokens to be consumed by PingFederate. This parameter determines the connection for which the metadata is generated. |
| vsid (optional) |
Specify the virtual server ID.
If absent, PingFederate generates the metadata based on the connection's default virtual server ID (if two or more virtual server IDs are defined) or the federation ID defined in the screen. |
If your partner fails to retrieve metadata when sending both the PartnerSpId (or the PartnerIdpId) and the vsid query parameters, perhaps it is only capable of sending one query parameter in such requests. An alternative metadata exchange endpoint that includes the virtual server ID information should resolve the issue.
For more information, see Constructing an alternative metadata exchange endpoint.