First Mile Integration

An IDP adapter is used in the “first-mile” of an application integration, to gather information about the identity authenticating and return that information to the PingFederate server to continue a federated authentication action.

Examples of where a custom IDP adapter may be used are:

  • Custom web form – ie scenarios where there is an existing login form and it is easier to “re-wire” that form rather than migrate that form into a PingFederate HTML Form adapter. Also where an authentication form has additional custom requirements that are beyond the scope of the packaged HTML Form adapter.
  • Web portal integration – where the user already authenticates to an existing application and wishes to re-use those credentials. In this example a page can be created as a protected resource in the portal. When this page is accessed the regular portal authentication occurs and the portal identity can be presented to PingFederate to use for further federated logins.

There are two ways of building an IDP adapter using the Integration kit:

  • Integrated adapter integration where the adapter is called during a federated SSO process; and
  • Form-first adapter integration where the authentication form is called first to initiate SSO to an application

Additionally, the single log-out (SLO) process will be described.

 

In a traditional integration, a federated SSO request will arrive at the PingFederate IDP instance (either IDP or SP initiated). During the processing of that request, an authentication adapter will be called to provide authentication for the SSO request.

An IDP adapter is used in the “first-mile” of an application integration, to gather information about the identity authenticating and return that information to the PingFederate server to continue a federated authentication action.

There are two ways of building an IDP adapter using the Integration kit:

  • Integrated adapter integration where the adapter is called during a federated SSO process; and
  • Form-first adapter integration where the authentication form is called first to initiate SSO to an application

This page describes the integrated adapter method and will use the following variables in all examples:

Variable Value
PINGFEDERATE_SERVER https://pf.company.com:9031
DROPOFF_ENDPOINT /ext/ref/dropoff
PICKUP_ENDPOINT /ext/ref/pickup
ADAPTER_INSTANCE_ID idp
ADAPTER_USER idp_user
ADAPTER_PW idp_password
ADAPTER_SIGNIN_URL https://idp.company.com/signin
ADAPTER_SIGNOUT_URL https://idp.company.com/signout
TARGET_RESOURCE https://app.company.com/myreport

 

Adapter Initiation

The adapter will be initiated by the user agent being redirected to the “Authentication Endpoint” URL configured in the adapter configuration. The following parameters will also be presented:

resumePath Defines the location that the adapter must redirect the user after authentication and attribute dropoff.
reauth Indicates the value of the SAML2.0 "forceAuthn" parameter that was passed in the AuthnRequest. Default is false.
allowInteraction Indicates the value of the SAML2.0 "isPassive" parameter passed with the AuthnRequest. The value is a negation of the isPassive value, ie:
isPassive = true will result in allowInteraction = false
isPassive = false will result in allowInteraction = true
Default value is true.

An example of an SSO initiation request is as follows:

GET https://pf.company.com:9031/idp/startSSO.ping
  ?TargetResource=https%3A%2F%2Fapp.company.com%2Fmyreport HTTP/1.1

The response from PingFederate will be a redirect to the IDP adapter’s "Authentication Endpoint" URL:

HTTP/1.1 302 Found
Content-Type: text/html;charset=UTF-8
Location: https://idp.company.com/signin
  ?resumePath=%2Fidp%2FVMnNz%2FresumeSAML20%2Fidp%2FstartSSO.ping
  &allowInteraction=true
  &reauth=false

It is at this stage that the custom adapter now has control of the user and can perform the necessary steps to identify and authenticate the entity.

 

Adapter Processing Steps

Step 1 – Remember the "resumePath" value

The resumePath is needed to redirect the user back to the PingFederate SSO process. Ensure this value is persisted across pages / requests as it is needed at the end of the authentication process.

For this example, this value will be referred to as the [RESUME_PATH] variable and will be populated with the value retrieved and URL-decoded from the resumePath attribute passed via the signin URL (/idp/VMnNz/resumeSAML20/idp/startSSO.ping).


Step 2 – Implement authentication logic

The next step is to implement whatever process you need to authenticate the user. This could involve displaying a form, decrypting a cookie or gathering information from the browser or device.

During this process, the adapter should support the "reauth" and "allowInteraction" flags as well as take into consideration any existing session the user may have on the authentication form.

Note: To "fail" authentication, do not return the user to the resume path. Simply display an error page and abort the SSO process.

A sample workflow for an authentication form would look something similar to:

IF ( “reauth” IS TRUE ) THEN
  IF ( “allowInteraction” IS TRUE ) THEN
    DISPLAY LOGIN FORM
  ELSE ( “allowInteraction” IS FALSE)
    IF ( [user is able to be authenticated silently] ) THEN
      AUTHENTICATE SILENTLY
    ELSE
      FAIL AUTHENTICATION
    END IF
  END IF
ELSE ( “reauth” IS FALSE )
  IF ( [user has an existing session] ) THEN
    RETURN EXISTING IDENTITY
  ELSE
    IF ( “allowInteraction” IS TRUE ) THEN
      DISPLAY LOGIN FORM
    ELSE ( “allowInteraction” IS FALSE)
      IF ( [user is able to be authenticated silently] ) THEN
        AUTHENTICATE SILENTLY
      ELSE
        FAIL AUTHENTICATION
      END IF
    END IF
  END IF
END IF

 

Step 3 – “Dropoff” the attributes to PingFederate

At this stage the entity has been authenticated and the identifying attribute(s) have been gathered, the next step is to push these attributes back to PingFederate to use in the SSO process. This is achieved via a HTTP POST to the “dropoff” URL. The attributes dropped off will correspond to the attribute contract defined in the adapter configuration.

In this example, we will return a “subject” attribute with a value of “jsmith” and a “realm” attribute with a value of “corp”.

A HTTP request is made to the dropoff endpoint URL on the PingFederate server. This request contains the two attribute-value pairs:

POST https://pf.company.com:9031/ext/ref/dropoff HTTP/1.1
Content-Length: 36
Content-Type: application/json
Authorization: BASIC aWRwX3VzZXI6aWRwX3Bhc3N3b3Jk
ping.instanceId: idp

{
“subject”:”jsmith”,
“realm”:”corp”
}

The response from this POST will be a reference ID that must be included in the next step when the user is returned to PingFederate.

 

Step 4 – Return the user to the SSO process

At this point, the adapter will return the user to the SSO process. The components collected in the previous steps will be used to generate the HTTP redirect:

  • [PINGFEDERATE_SERVER] value from configuration
  • [RESUME_PATH] value gathered in Step 1
  • [REF_VALUE] value gathered in Step 3

Taking these three components we can create the full resume URL using the format:

  • [PINGFEDERATE_SERVER] + [RESUME_PATH] + ?REF= + [REF_VALUE]

The user will then be redirect to this URL (how this redirect performed is up to the browser/application) to continue the SSO process:

HTTP/1.1 302 Found
Content-Type: text/html;charset=UTF-8
Location: https://pf.company.com:9031/idp/VMnNz/resumeSAML20/idp/startSSO.ping
  ?REF=ABCDEFGHIJKLMNOPQRSTUVWXYZ1234

The IDP authentication adapter process is now complete and the user will continue with the SSO transaction.

 

A streamlined SSO process can be used in cases where the SSO action will always begin at the form or authentication event. This is commonly used is to authenticate to a third-party application using the identity of the currently logged in user. For example a web portal may have a link to a thrid-party support application, the agentless integration kit can be used to take the identity of the user authenticated at the portal, and initiate an SSO session to the third-party without prompting the user.

This scenario will use the same configuration as the "integrated IDP adapter" method:

Variable Value
PINGFEDERATE_SERVER https://pf.company.com:9031
DROPOFF_ENDPOINT /ext/ref/dropoff
PICKUP_ENDPOINT /ext/ref/pickup
ADAPTER_INSTANCE_ID idp
ADAPTER_USER idp_user
ADAPTER_PW idp_password
ADAPTER_SIGNIN_URL https://idp.company.com/signin
ADAPTER_SIGNOUT_URL https://idp.company.com/signout
TARGET_RESOURCE https://app.company.com/myreport

 

Adapter Initiation

In a form-first scenario, the user will initially hit the authentication adapter prior to redirecting through the browser SSO flow. This adapter may be an existing login form; a web part in an existing portal; an SSO redirect page located as protected content inside a portal or even a native or thick client application that can interface through a web browser. 

 

Adapter Processing Steps

Step 1 - Implement authentication logic

This scenario differs from step 2 above in that we won’t have the additional parameters passed in to the adapter, the user will be authenticated by the adapter and the applicable attributes are gathered to send through the SSO process.

 

Step 2 – “Dropoff” the attributes to PingFederate

This step is identical to step 3 above. At this stage the entity has been authenticated and the identifying attribute(s) have been gathered, the next step is to push these attributes back to PingFederate to use in the SSO process. This is achieved via a HTTP POST to the “dropoff” URL.

In this example, we will return a “subject” attribute with a value of “jsmith” and a “realm” attribute with a value of “corp”. A HTTP request is made to the dropoff endpoint URL on the PingFederate server. This request contains the two attribute-value pairs:

POST https://pf.company.com:9031/ext/ref/dropoff HTTP/1.1
Content-Length: 36
Content-Type: application/json
Authorization: BASIC aWRwX3VzZXI6aWRwX3Bhc3N3b3Jk
ping.instanceId: idp

{
“subject”:”jsmith”,
“realm”:”corp”
}

The response from this POST will be a reference ID that must be sent with the user to the resume path specified on the initial request.

HTTP/1.1 200 OK
{
  "REF":"ABCDEFGHIJKLMNOPQRSTUVWXYZ1234"
}

Extract this reference token for use in the next step. This value will be referred to as [REF_VALUE] below and will contain the value retrieved from the response above (ABCDEFGHIJKLMNOPQRSTUVWXYZ1234).

 

Step 3 - Initiate the SSO process

At this point, the adapter initiates the SSO process by redirecting the user through the PingFederate IDP-initiated SSO URL. The [REF_VALUE] collected in the previous step will be appended to the URL as a “REF” parameter using the format:

[IDP-initiated SSO URL] + [?|&] + REF= + [REF_VALUE]

For this example we want to trigger the same SSO process as above, which results in a redirect URL of:

HTTP/1.1 302 Found
Content-Type: text/html;charset=UTF-8
Location: https://pf.company.com:9031/idp/startSSO.ping
  ?TargetResource=https%3A%2F%2Fapp.company.com%2Fmyreport
  &REF=ABCDEFGHIJKLMNOPQRSTUVWXYZ1234

The IDP authentication adapter process is now complete and the user will continue with the SSO process.

 

Single Log-Out (SLO) allows a user to request log out from multiple connected systems from a single request. Commonly used in “portal” scenarios where a user has initiated multiple SSO sessions to different systems, when the user requests “Log out” from the portal, this process can log the user out of all applications.

The below steps are for a front-channel SLO. In a back-channel scenario, PingFederate will call the logout page with any attributes you define in the querystring. You can then kill the session with the values passed from PingFederate.

For example, if the sessions were maintained in a database according to the subject of the assertion, to use back-channel logout, I can modify the PingFederate configuration to specify back-channel logout and set the logout service endpoint to include “?subject=${subject}” appended to the SLO url.

The application would then need to take this “subject” query parameter (as opposed to the “REF” parameter it receives in a front-channel SLO) and kill the appropriate application sessions.
 

SLO Process Initiation

During a front-channel SLO activity a request will be made to the “Logout Service Endpoint” defined in the IDP adapter configuration. This request will contain a “REF” parameter for the SLO endpoint to use to retrieve attributes about the session requesting logout.

HTTP/1.1 302 Found
Content-Type: text/html;charset=UTF-8
Location: https://idp.company.com/signout
  ?REF=AABBCCDDEEFFGGHHIIJJKKLLMMNNOO

 

SLO Processing Steps

Step 1 – Grab the REF attribute

When an SLO request is received, this REF parameter must be retrieved and used to pickup attributes regarding the session requesting logout. The value will be referred to as [REF_VALUE] in the steps below and be populated with the value parse from the parameters (AABBCCDDEEFFGGHHIIJJKKLLMMNNOO).

 

Step 2 – Pickup the information about the Logout

Similar to an SSO request, the adapter will make a HTTP GET request to the pickup endpoint to retrieve attributes about the logout:

GET https://pf.company.com:9031/ext/ref/pickup?REF=AABBCCDDEEFFGGHHIIJJKKLLMMNNOO HTTP/1.1
Authorization: BASIC aWRwX3VzZXI6aWRwX3Bhc3N3b3Jk
ping.instanceId: idp

The response will contain information about the user who is requesting logout.

HTTP/1.1 200 OK

{
  "realm":"corp",
  "subject":"jsmith",
  "TargetResource":"https:\/\/app.company.com\/myreport",
  "resumePath":"\/idp\/qrPqO\/resume\/idp\/startSLO.ping"
}

 

Step 3 – Destroy the local application session

The SLO page will parse these attributes and destroy the local session, delete session cookies and perform any logout processing corresponding to the attributes. (ie if a session is maintained in a database for an active user, the application could delete all rows where the username is jmsith to complete the logout cleanup process).

Also in the returned attributes is the resumePath value that is needed in the next step to redirect the user after destroying the session. This will be referred to as the [RESUME_PATH] value and will contain the value retrieved from the pickup response /idp/qrPqO/resume/idp/startSLO.ping.

 

Step 4 – Return the user to PingFederate

To continue the SLO process, the user must be returned to the [RESUME_PATH] gathered in Step 3. The source of the resume request must also be provided on this URL and appended as a “source” query parameter. So using the following variables:

  • [PINGFEDERATE_SERVER] value from configuration
  • [RESUME_PATH] value gathered in Step 2
  • [ADAPTER_INSTANCE_ID] value from configuration

we can create the full resume URL using the format:

  • [PINGFEDERATE_SERVER] + [RESUME_PATH] + ?source= + [ADAPTER_INSTANCE_ID]

Which results in a redirect URL of:

HTTP/1.1 302 Found
Content-Type: text/html;charset=UTF-8
Location: https://pf.company.com:9031/idp/qrPqO/resume/idp/startSLO.ping?source=idp

The IDP authentication adapter process is now complete and the user will continue with the SLO process.