PingFederate

The Authentication Service can be integrated with PingFederate to deliver login and account management capabilities. This can be useful when PingFederate is serving as an OAuth Authorization Service or a Federation Service, as depicted in the following figure:

../../_images/pf-sp-integration.png

Fig. 133 PingFederate SP Integration

To use the Authentication Service in this way, an administrator needs to do two basic things:

  1. Install the requisite PingFederate integration kit and configure PingFederate
  2. Configure the Authentication Service

The details involved in doing these two things and how to test the final results are described below.

Note

The Identity Server can also be used as an OAuth Authorization Server. In this role, it can be configured to use PingFederate as an Authentication Service. This setup is described elsewhere in the manual; this section describes the reverse setup.

Configuring PingFederate

Depending on the role that PingFederate has in a deployment – as an OAuth Server or a Federation Server – the configuration will be slightly different.

Server Configuration

Regardless of which roles or capabilities PingFederate is providing, certain basic configuration must be done to integrate it with the Authentication Service. For the two products to interoperate, you need to perform the following initial configuration in PingFederate:

  1. Enable the IdP role
  2. Create a new IdP adapter

To integrate the Authentication Service, PingFederate has to be configured as an Identity Provider (IdP). This is usually done after installation when the initial setup wizard is run, but can also be configured afterwards. Once done, you will be able to setup an IdP adapter.

The Curity Authentication Server can also be used with PingFederate and integrated using the SAML protocol. When using the Curity Authentication Server in this way, enable PingFederate’s SP role, and create an IdP connection in PingFederate to the Curity Authentication Server.

Adapter Configuration

The type of adapter used to integrate PingFederate with the Authentication Service is an Agentless Integration or ReferenceID Adapter. To use this type of adapter, you need to download it from Ping Identity’s web site, and follow the instructions in the manual to install, as it is not included in the base installation. Then, use the information in the following table to configure an adapter instance of this type:

Field Name Field Value
Authentication Endpoint The URL of the Authentication Service
Username / Password The credentials used to identify the Authentication Service
Transport Mode Form Post (no other mode is supported)
Incoming Attribute Format JSON (no other format is supported)

Note

Transport Mode and Incoming Attribute Format are only visible in the advanced field section of the adapter configuration.

OAuth-specific Configuration

When using PingFederate as an OAuth Authorization Server, the agentless IdP adapter must be mapped. Before you can do this, the OAuth role must be enabled. Once done and the OAuth server is configured, you can map the IdP adapter. To do this, follow the instructions in the manual. When choosing the Source Instance, select the agentless adapter that was setup to connect to the Authentication Service. Then, complete the mapping as desired.

Note

The Authentication Service will communicate to PingFederate which factor or method the end user authenticated themselves with (e.g., smartcard, facebook, 2fa, etc.). This will be included in the ID Token issued by PingFederate if and only if the OAuth client requests the openid scope, OpenID Connect has been enabled in PingFederate, and the client policy in PingFederate doesn’t disallow it from using the openid scope. You can configure the authenticator reference value to change the actual value sent to PingFederate for a particular authenticator.

Web Single Sing-on Configuration

Similarly to the OAuth setup described above, the same agentless adapter can be used when defining a Service Provider (SP) connection in PingFederate. To do this, map the Authentication Service’s agentless adapter instance to an SP connection, selecting it as the authentication source. After doing so, the SP application will connect to PingFederate using SAML or WS-Federation per the connection details. At such time, users will be redirected to the Authentication Service to login. Once they do, the Authentication Service will use the protocol defined by the agentless adapter to assert the user’s identity to PingFederate. It will translate this identity data and communicate it back to the SP via SAML or WS-Federation.

Configuring the Authentication Service

In order for the Authentication Service to be able to communicate with PingFederate, the following must be configured:

  • An authentication service profile
  • A PingFederate protocol which is set as the one used by the authentication service profile
  • The PingFederate server must be added to the redirect white list of the authentication service profile

See also

For information about how to create an authentication service profile, refer to the section about creating a new profile earlier in this guide.

Defining a PingFederate Protocol

The Authentication Service can be integrated using numerous protocols. To communicate with PingFederate a specific type of protocol needs to be added to an authentication profile. This can be done using the REST API with a PUT request on the profile endpoint.

...
<profiles>
    <profile>
        <type xmlns:auth="https://curity.se/ns/conf/profile/authentication">
            auth:authentication-service
        </type>
        ...
        <protocols>
            <protocol>
                <id>${ID}</id>
                <ping-federate>
                    <dropoff-url>/ext/ref/dropoff</dropoff-url>
                    <dropoff-username>${REF_ADAPTER_USERNAME}</dropoff-username>
                    <dropoff-password>${REF_ADAPTER_PASSWORD}</dropoff-password>
                    <idp-adapter-id>${REF_ADAPTER_ID}</idp-adapter-id>
              </ping-federate>
            </protocol>
        ...
        </protocols>
        ...
    </profile>
...
</profiles>
...

In the snippet of XML config above, ${REF_ADAPTER_USERNAME} and ${REF_ADAPTER_PASSWORD} refer to the credentials that were set when the reference adapter instance was created (refer to table above for details). ${REF_ADAPTER_ID} is the ID of the adapter instance that was chosen when it was defined in PingFederate.