PingFederate Server

System-services endpoints

System-services endpoints generally apply to the PingFederate server, whether used as an identity provider (IdP), service provider (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. For more information, 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. For more information, see Runtime reporting.

/pf/adapter2adapter.ping

This endpoint initiates direct IdP-to-SP adapter mapping, when that feature is configured in the Adapter-to-Adapter Mappings window. For more information, 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 Configuring 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 in the Applications → Integration → SP Default URLs window.

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. For more information, see Customizable user-facing pages.

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 on entries defined in the Applications → Integration → Target URL Mapping window. For more information, 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.

To use this parameter, the Allow Password Changes check box must be selected in the adapter configuration of the invoked HTML Form Adapter instance. For more information, see Configuring an HTML Form Adapter instance.

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.

/pf/sts.wst

This endpoint initiates direct security token service (STS) token-to-token exchange and token validation from an IdP token processor to an SP token generator, when that feature is configured in the Token Translator Mappings window. For more information, 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, you must configure a secondary PingFederate listening port used by partners or STS clients for the relevant endpoints—.ssaml and .wst. For more information, 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 System → Server → Protocol Settings → Federation Info tab.

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 on the System → Server → Protocol Settings → Federation Info tab.

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.