Last Mile Integration

After authenticating the user (via a federated security token or authentication adapter), the user will be presented to the protected application via an SP adapter. This adapter provides the last-mile connection between the federation server (PingFederate) and the application, the user will be presented to the application which can then create a session and render the application for the authenticated user.

There are three items to cover in the last-mile scenario:

  • Application Integration - how the application is provided with information about the authenticated user;
  • Account Linking - how the authenticated user can be linked to an application account (optional);
  • Single Log-Out - how the users session will be terminated when they send a log-out request
 

Integration on the application side uses an SP adapter; this provides the “last-mile” integration between PingFederate and the application. The attributes that are received from a federated token (ie a SAML assertion) are provided to the SP adapter, which creates an authenticated session inside an application.

The following variables will be used in the following examples:

PINGFEDERATE_SERVER https://pf.company.com:9031
DROPOFF_ENDPOINT /ext/ref/dropoff
PICKUP_ENDPOINT /ext/ref/pickup
ADAPTER_INSTANCE_ID app
ADAPTER_USER app_user
ADAPTER_PW app_password
ADAPTER_SIGNIN_URL https://app.company.com/signin
ADAPTER_SIGNOUT_URL https://app.company.com/signout

 

SSO Process Initiation

The process that is used on the SP side is similar to the IDP adapter. During an SSO process, an SP adapter will be used to create the application session based on attributes received in an assertion.

The entry point into the SP adapter is through the “Authentication Endpoint” URL configured in the reference ID adapter configuration. During a SSO event, PingFederate will redirect the user to this endpoint with the following parameters:

TargetResource Contains a url-encoded location (ie a deep-link or an application landing page that the user requested.
REF Contains a reference value that the adapter uses to pick up the attributes.

For the following example, the HTTP response that was received is below:

HTTP/1.1 302 Found
Content-Type: text/html;charset=UTF-8
Location: https://app.company.com/signin
  ?TargetResource=https%3A%2F%2Fapp.company.com%2Fmyreport
  &REF=4321ZYXWVUTSRQPONMLKJIHGFEDCBA

 

SSO Processing Steps

Step 1 - Gather the attributes provided in the URL

The TargetResource and REF attributes should be extracted and stored for use in the next steps. These values will be referred to as [TARGET_RESOURCE] and [REF_VALUE] and will be populated as follows (after URL-decoding):

  • [TARGET_RESOURCE] https://app.company.com/myreport
  • [REF_VALUE] 4321ZYXWVUTSRQPONMLKJIHGFEDCBA
 

Step 2 - "Pickup" the attributes from PingFederate

At this stage, the SP adapter will use the REF value and call back to PingFederate to pick up the user attributes. This is achieved through a HTTP GET to the “pickup” endpoint with the [REF_VALUE] appended:

GET https://pf.company.com:9031/ext/ref/pickup?REF=4321ZYXWVUTSRQPONMLKJIHGFEDCBA HTTP/1.1
Authorization: BASIC YXBwX3VzZXI6YXBwX3Bhc3N3b3Jk
ping.instanceId: app

The response will contain the attributes about the identity and the authentication context:

HTTP/1.1 200 OK

{
"authnCtx":"urn:oasis:names:tc:SAML:2.0:ac:classes:unspecified",
"partnerEntityID":"company:saml20:idp",
"subject":"jsmith",
"instanceId":"app",
"realm":"corp",
"sessionid":"sFMcTOaropYv5gYQZi1ZOpX7DZ8",
"authnInst":"2013-03-28 20:42:10-0500"
}

A summary of these attributes is as follows:

authnCtx The authentication context specified during the SSO event.
partnerEntityID The partner entity ID who authenticated the user.
subject An attribute passed from the assertion.
instanceId The SP adapter instance ID.
realm An attribute passed from the assertion.
sessionid A unique session ID that PingFederate uses to track this session. This will also be returned during an SLO event.
authnInst The timestamp of the authentication action.

 

Step 3 – Authorize and create the application session

The application now has the attributes describing the identity that authenticated. Using the attributes received in step 2, the application can perform any necessary authorization or provisioning, then create a local application session.

Once the session is established, the application can use the value of the [TARGET_RESOURCE] gathered in step 1 to redirect the user to the requested URL (ie in a deep-link scenario). If the [TARGET_RESOURCE] parameter is not present, the application should redirect to a default URL or application landing page.

The application authentication process is now complete.

 

Account Linking allows for a link to be established between the name ID provided in a SAML assertion and a local ID stored in an application (for example, an application may store user’s using a specific application ID rather than an enterprise employee ID).

The account link process on the SP adapter only needs to return the value of the local application ID back to PingFederate.  So the process should authenticate the user to retrieve the local application ID and return that value to PingFederate.

 

Account Linking Process Initiation

The Account Linking process will be triggered by the SP adapter calling the “Account Linking Authentication Endpoint” URL defined in the adapter configuration. This request will contain a reference value for the account link process to pickup information about the account link session.

For the following example, the HTTP response that triggers the Account Link process is:

HTTP/1.1 302 Found
Content-Type: text/html;charset=UTF-8
Location: https://app.company.com/actlink?REF=A1B2C3D4E5F6G7H9I0J1K2L3M4N5O6

 

Account Linking Processing Steps

Step 1 – Gather the attributes provided in the URL

The REF attribute provided to the Account Link URL must be extracted and used to pickup information about the Account Link session.

In this example, we retrieve the REF value (A1B2C3D4E5F6G7H9I0J1K2L3M4N5O6) from the query string, this is referred to as [REF_VALUE] in the steps below.

 

Step 2 – "Pickup" the attributes from PingFederate

The Account Link process will use the REF value received in the previous step and call back to PingFederate to pick up the user attributes. This is achieved through a HTTP GET to the “pickup” endpoint with the [REF_VALUE] appended:

GET https://pf.company.com:9031/ext/ref/pickup?REF=A1B2C3D4E5F6G7H9I0J1K2L3M4N5O6 HTTP/1.1
Authorization: BASIC YXBwX3VzZXI6YXBwX3Bhc3N3b3Jk
ping.instanceId: app

The response will contain the attributes about the identity and the authentication context:

HTTP/1.1 200 OK

{
"partnerEntityID":"company:saml20:idp",
"resumePath":"\/sp\/stPFE\/resume\/sp\/ACS.ping"
}

A summary of these attributes is as follows:

partnerEntityID The partner entity ID who authenticated the user.
resumePath The location to return the user after completing the Account Link process.

 

Step 3 – Authenticate the user locally to verify link

The process now needs to determine who the local application user is and return that value back to PingFederate to establish the link. This step usually involves presenting the user with a local application login form and having them authenticate locally to verify their application user.

 

Step 4 – Return the local application user ID

Once the local application user has been determined, this value must be returned to PingFederate to establish the link between the SAML name ID and the local application ID. This value will be returned to PingFederate as an attribute named “subject” using the dropoff process.

For this example, we will use a local application ID of “M00123” as the local account to link.

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

{
"subject":"M00123"
}

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":"P7Q8R9S0T1U2V3W4X5Y6Z7A8B9C0D1"
}

Extract this reference token for use in the next step. This value will be referred to as [REF_VALUE] below.

 

Step 5 – Return the user to PingFederate

To continue the SSO process, the user must be returned to the [RESUME_PATH] gathered in Step 2. The reference value of the dropped off attributes must also be provided on this URL and appended as a “REF” query parameter. So using the following variables:

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

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

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

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/sp/stPFE/resume/sp/ACS.ping
  ?REF=P7Q8R9S0T1U2V3W4X5Y6Z7A8B9C0D1

The account link process is now complete. To “break” this account link, the user should be redirected to the /sp/defederate.ping link after authenticating to the application they are linked with.

 

The SLO process on the SP side is similar to the IDP SLO process, however different attributes are returned during the pickup process and the user’s local application session will be destroyed rather than the authentication process session.

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://app.company.com/signout?REF=PPQQRRSSTTUUVVWWXXYYZZ11223344

 

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 of “PPQQRRSSTTUUVVWWXXYYZZ11223344”.

 

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=PPQQRRSSTTUUVVWWXXYYZZ11223344 HTTP/1.1
Authorization: BASIC YXBwX3VzZXI6YXBwX3Bhc3N3b3Jk
ping.instanceId: app

The response will contain information about the session requesting logout.

HTTP/1.1 200 OK
{
"resumePath":"\/sp\/pCyCo\/resume\/sp\/SLO.ping",
"sessionid":"sFMcTOaropYv5gYQZi1ZOpX7DZ8"
}

The following attributes will be returned in the response:

resumePath URL to send the user at the end of the local logout process to continue the SLO activity.
sessionid The sessionid PingFederate uses to track the authenticated session. This will be the same as the value received when the SSO attributes are picked up.

 

Step 3 – Destroy the local application session

The SLO page will parse these attributes and destroy the local session (ie delete session cookies) and perform any logout processing corresponding to the attributes. (ie if the session maintained a row in a database, the application could use the sessionid provided to delete these rows and end the session).

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 /sp/pCyCo/resume/sp/SLO.ping retrieved from the response above.

 

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 3
  • [ADAPTER_INSTANCE_ID] value from configuration

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

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

Which results in a redirect of:

HTTP/1.1 302 Found
Content-Type: text/html;charset=UTF-8
Location: Location: https://pf.company.com:9031/sp/pCyCo/resume/sp/SLO.ping?source=app

The local application logout process is now complete and the user will continue with the SLO activity.