PingFederate Server

Identifying the partner

When creating an identity provider (IdP) connection, you must identify your partner and provide basic information about them.

About this task

On the General Info tab, you provide your partner’s unique federation identifier, the display name of the connection, and some other optional information, such as virtual server IDs, contact information, and logging mode for runtime transaction logging.

In addition, on this tab you can define a default error message that end users see in the event that single sign-on (SSO) fails.

Steps

  1. Provide the basic information to identify your partner.

    See the following table for more information.

    Field Description

    Partner’s Entity ID, Issuer, Partner’s Realm, or Connection ID

    (Required)

    The published, protocol-dependent, unique identifier of your partner.

    For a SAML 2.0 connection, this is your partner’s SAML Entity ID. For a SAML 1.x connection, this is the audience your partner advertises. This ID might have been obtained out-of-band or through a SAML metadata file.

    For a WS-Federation connection, this is your partner’s Realm.

    For an OpenID Connect connection, this is the Issuer Identifier of the OpenID Provider (OP).

    For a security token service (STS)-only connection, this ID can be any unique identifier.

    Enable Additional Issuers

    (Applicable only to OpenID Connect connection)

    When selected, PingFederate takes into consideration additional issuers when validating ID tokens obtained through this connection.

    Enable this option if you want to support multi-tenant OpenID providers, such as Microsoft Azure AD.

    This check box is not selected by default.

    Issuer information is defined on the Additional Issuers tab.

    Connection Name

    (Required)

    A plain-language identifier for the connection: for example, a company or department name. This name is displayed in the connection list on the administrative console.

    Virtual Server IDs

    (Not applicable to OpenID Connect connections)

    If you want to identify your server to this connection partner using an ID other than the one you specified on the Federation Info tab, enter a virtual server ID in this field and click Add.

    Enter additional virtual server IDs as needed.

    Client ID and Client Secret

    (Applicable to and required for OpenID Connect connections)

    The client ID and the client secret to communicate with the OP.

    This client represents PingFederate and is created and managed at the OP. For more information, see the documentation provided by the OP.

    Base URL

    The fully qualified hostname and port on which your partner’s federation deployment runs (for example, https://www.example.com:9031). This entry is an optional convenience, allowing you to enter relative paths to specific endpoints, instead of full URLs, during the configuration process.

    Company

    The name of the partner company to which you are connecting.

    Contact Name

    The contact person at the partner company.

    Contact Number

    The phone number of the contact person at the partner company.

    Contact Email

    The email address for the contact person at the partner company.

    Error Message

    (Applicable only to SAML or OpenID Connect connections)

    If an error occurs on this server, the end user’s browser might be redirected in a default situation to an error page hosted within PingFederate.

    The default entry errorDetail.spSsoFailure is a variable from the <pf_install>/pingfederate/server/default/conf/language-packs/pingfederate-messages.properties file, which is part of the PingFederate localization framework. If localization is not needed, you can also specify a message directly in this field to change the default.

    Logging Mode

    The level of transaction logging applicable for this connection.

    The default selection is Standard.

    If the OP supports the OpenID Connect Discovery specification, the connection setup is expedited by loading the metadata from the OP. Based on the discovery specification, PingFederate makes a direct HTTP GET request to the /.well-known/openid-configuration endpoint at the OP and populates the attribute contract and the protocol settings of the connection automatically. Manual adjustments can be made during the connection setup or at a later time.

    Additionally, you can refresh the protocol settings by reloading the metadata from the OP at any time. If additional claims are supported, PingFederate adds them to the attribute contract, so that they can be mapped to the target applications later. In the event that the previously supported claims have been dropped by the OP from the metadata, they remain in the attribute contract. While the existing mapping configuration might not be adversely affected, runtime errors might occur if certain attributes are no longer available to the target applications. If runtime errors occur, review the server log and modify the mapping configuration accordingly.

  2. Optional: Click Load Metadata.

    This step is not applicable to an STS-only connection.