Agentless Integration Kit Application Integration Guide Ping Identity, Inc. • 1001 17th Street, Suite 100, Denver, CO 80202 • 303.468.2900 Table of Contents Contents 1 OVERVIEW .......................................................................................................................................... 4 1.1 SAMPLE INTEGRATION SCENARIO .................................................................................................... 4 2 AGENTLESS INTEGRATION KIT OVERVIEW ........................................................................... 7 2.1 PINGFEDERATE INTEGRATION POINTS ............................................................................................. 7 2.2 PICKUP PROCESS............................................................................................................................... 7 2.3 DROPOFF PROCESS ........................................................................................................................... 9 3 PINGFEDERATE CONFIGURATION ........................................................................................... 11 3.1 ADAPTER AUTHENTICATION METHODS ......................................................................................... 11 3.1.1 Custom HTTP header variables .............................................................................................. 12 3.1.2 HTTP BASIC Authentication ................................................................................................... 12 3.1.3 Mutual TLS (Certificate) Authentication ................................................................................. 13 4 IDP ADAPTER INTEGRATION ...................................................................................................... 15 4.1 TRADITIONAL PINGFEDERATE IDP ADAPTER INTEGRATION ........................................................ 17 4.1.1 SSO Process Initiation............................................................................................................. 17 4.1.2 Step 1 – Remember the “resumePath” value .......................................................................... 19 4.1.3 Step 2 – Implement authentication logic ................................................................................. 19 4.1.4 Step 3 – “Dropoff” the attributes to PingFederate ................................................................. 20 4.1.5 Step 4 – Return the user to the SSO process ........................................................................... 21 4.2 STREAMLINED IDP ADAPTER INTEGRATION (FORM-FIRST) .......................................................... 22 4.2.1 SSO Process Initiation............................................................................................................. 22 4.2.2 Step 1 - Implement authentication logic .................................................................................. 22 4.2.3 Step 2 – “Dropoff” the attributes to PingFederate ................................................................. 23 4.2.4 Step 3 – Initiate the SSO process............................................................................................. 24 4.3 SINGLE LOG-OUT (SLO) ................................................................................................................ 25 4.3.1 SLO Process Initiation ............................................................................................................ 25 4.3.2 Step 1 – Grab the REF attribute .............................................................................................. 25 4.3.3 Step 2 – Pickup the information about the Logout .................................................................. 25 4.3.4 Step 3 – Destroy the local application session ........................................................................ 26 4.3.5 Step 4 – Return the user to PingFederate ............................................................................... 26 4.4 ERROR HANDLING .......................................................................................................................... 28 4.5 OTHER CONSIDERATIONS ............................................................................................................... 29 4.5.1 Time Synchronization .............................................................................................................. 29 4.5.2 Timeouts & Session Management ........................................................................................... 29 5 SP INTEGRATION ............................................................................................................................ 30 5.1 SP APPLICATION INTEGRATION...................................................................................................... 30 5.1.1 SSO Process Initiation............................................................................................................. 31 5.1.2 Step 1 – Gather the attributes provided in the URL ................................................................ 32 5.1.3 Step 2 – “Pickup” the attributes from PingFederate .............................................................. 32 5.1.4 Step 3 – Authorize and create an application session ............................................................. 34 5.2 ACCOUNT LINKING ......................................................................................................................... 35 2 5.2.1 Account Linking Process Initiation ......................................................................................... 35 5.2.2 Step 1 – Gather the attributes provided in the URL ................................................................ 35 5.2.3 Step 2 – “Pickup” the attributes from PingFederate .............................................................. 35 5.2.4 Step 3 – Authenticate the user locally to verify link ................................................................ 36 5.2.5 Step 4 – Return the local application user ID ......................................................................... 36 5.2.6 Step 5 – Return the user to PingFederate ............................................................................... 37 5.3 SINGLE LOG-OUT (SLO) ................................................................................................................ 39 5.3.1 SLO Process Initiation ............................................................................................................ 39 5.3.2 Step 1 – Grab the REF attribute .............................................................................................. 39 5.3.3 Step 2 – Pickup the information about the Logout .................................................................. 39 5.3.4 Step 3 – Destroy the local application session ........................................................................ 40 5.3.5 Step 4 – Return the user to PingFederate ............................................................................... 41 5.4 ERROR HANDLING .......................................................................................................................... 42 5.5 OTHER CONSIDERATIONS ............................................................................................................... 43 5.5.1 Time Synchronization .............................................................................................................. 43 5.5.2 Deep-linking / Direct-linking .................................................................................................. 43 5.5.3 Authorization ........................................................................................................................... 43 5.5.4 Application User Profile Management.................................................................................... 43 6 CODE EXAMPLES ............................................................................................................................ 44 6.1 MICROSOFT .NET (C#) ................................................................................................................... 45 6.1.1 Pickup ...................................................................................................................................... 45 6.1.2 Dropoff .................................................................................................................................... 46 6.2 PHP ................................................................................................................................................. 48 6.2.1 Pickup ...................................................................................................................................... 48 6.2.2 Dropoff .................................................................................................................................... 49 6.3 JAVA SERVER PAGES (JSP)............................................................................................................. 50 3 1 Overview This document provides in detail the steps involved with integrating an existing application or login process with PingFederate using the Agentless Integration Kit. In addition to providing detailed integration steps, the document will provide some example integration scenarios and sample code for both IdP and SP integration. This document will use an example “traditional” application and demonstrate how to integrate both the user authentication process and the application session creation into the PingFederate product to facilitate federated authentication. There are multiple ways an application can be integrated into a federated SSO model, for example: 1. Native federation protocol support (i.e. native support of SAML or WS-­‐Federation protocols) 2. Integration with underlying web infrastructure (i.e. integrating with Apache web server) 3. Leveraging PingFederate for federation support and application integration via code; this scenario will be covered by this document. This document specifically refers to the following versions: • PingFederate 6.10 and higher • Agentless Integration Kit 1.2 It is assumed the audience understands core federation concepts (Identity Provider / Service Provider roles, browser SSO authentication process) and basic application development concepts. 1.1 Sample Integration Scenario The sample scenario described in this document involves taking a traditional application and integrating it into PingFederate to support federated authentication. The following diagram describes the “traditional application” scenario: Application
Application Data
User
User Application Data
User Authentication Data
4 A traditional application generally stores some kind of application data, user profile information or user data settings and authentication information about a user (i.e. username and password). In some cases, the application may use an external directory for authentication. In a traditional model, the application or organization managing the application needs to manage all the identities that use the application, even for users who may not belong to that organization (i.e. vendors and external contractors). In addition to having to manage these identities, the application must also manage authentication policies, password security and audit over the authentication actions. The concept of federation allows these user identities to be managed by the organization that is responsible for them. The federation infrastructure will trust this organization and allow users authenticating from that organization access to the application. This alleviates a large amount of the account management burden from the application owner. In addition, authentication is managed at a central point (the federation infrastructure) for audit and policy and the application no longer carries the risk of storing user passwords. Federation SP
Federation IDP
User
Application
Application Data
User Application Data
When a user authenticates, information about them is provided to the application for use in provisioning new accounts in the local application stores and update existing information about a user (i.e. change of name, role etc). Onboarding new Identity Providers (IDPs) is a simple task that can increase the reach of your application to multiple business partners, customers and consumers. Federation IDP
User
Federation IDP
Consumers
Federation SP
User
Application
Application Data
User Application Data
5 In addition, this document will describe how to use an existing log in form and process to general SAML assertions to authenticate to other applications. This is handy when you have a user population that authenticates to their organization in a specific way (i.e. through a company web portal) and you need to integrate applications into that portal using SAML. It may be simpler to integrate the existing portal as an authentication source instead of changing user habits or requiring the user to log in multiple times. SaaS Applications
Federation SP
Internal
Application
Federation SP
Federation IDP
Web Portal
User
Partner
Application
6 2 Agentless Integration Kit Overview 2.1 PingFederate Integration Points For browser SSO, PingFederate supports an “adapter” interface to provide “first-­‐mile” and “last-­‐mile” integration. When a user requests authentication to a federated SSO connection, PingFederate will send the user to an IdP Authentication Adapter to perform the authentication of the identity and to return information about the identity back to the login process. Similarly, when PingFederate receives a federated security token and needs to create an application session from those credentials, an SP Adapter is called to perform this action. PingFederate includes a large number of commercial integration kits and two “SDK” integration methods to perform this IDP and SP adapter processing. The two “SDK” kits include the “OpenToken” method that uses an encrypted token to interface between PingFederate and the endpoint, this supports Java, PHP and .NET; and the Agentless Integration Kit that does not use an intermediate token. The application endpoint must contact the PingFederate server directly to pickup or drop off attributes. Because the agentless kit does not require any libraries to be deployed on the integration endpoint to interface with the OpenToken, it is considered language agnostic and can be used for almost any integration scenario. The Agentless integration kit involves two main processes, the “pickup” process and the “dropoff” process. 2.2 Pickup Process The pickup process is used by the integration endpoint to fetch attributes from the PingFederate server. For example, the SP adapter collects information from the PingFederate server about an identity so that it can create an application session. The pickup process involves the adapter making a HTTP GET to the PingFederate pickup endpoint. The client will authenticate to PingFederate and use a specific “reference” value to pick up the attributes appropriate to the transaction. More details about the pickup process are included in the product documentation for the agentless integration kit. When accessing pickup endpoint, the endpoint should include the adapter instance ID as an HTTP header during the pickup call. When multiple adapters are configured on the PingFederate server, this header is required, so it is a good habit to include the value by default. The header name is “ping.instanceId” and the value must match the “Instance Id” value of the adapter configured in the PingFederate console. The basic steps you must follow to implement the Pickup process are: 1. Open or define an HTTPS connection to the PingFederate pickup URL 2. Identify the Agentless Adapter configured on PingFederate to use 7 3. Authenticate to the service, and optionally configure certificate authentication 4. Retrieve the attributes from the pickup service For example, if a reference ID of 12345 was provided to an adapter, then using the following adapter configuration information: PingFederate server: https://pf.company.com:9031 Adapter instance ID: sample_adapter Adapter user name: sample_id Adapter pass phrase: sample_password The following HTTP GET command would be issued to pickup the attributes referenced by the reference ID 12345. This example uses HTTP BASIC authentication: HTTP Request GET https://pf.company.com:9031/ext/ref/pickup?REF=12345 HTTP/1.1
Headers Authorization:
BASIC c2FtcGxlX2lkOnNhbXBsZV9wYXNzd29yZA==
ping.instanceid:
sample_adapter
Body <N/A> PingFederate will respond with a response containing the attributes and associated session information: HTTP Response HTTP/1.1 200 OK Headers <N/A>
Body {
"authnCtx":"urn:oasis:names:tc:SAML:2.0:ac:classes:unspecified",
"partnerEntityID":"company:saml20:idp",
"subject":"jsmith",
"instanceId":"sample_adapter",
"sessionid":"sFMcTOaropYv5gYQZi1ZOpX7DZ8",
"authnInst":"2013-03-28 20:42:10-0500"
} 8 2.3 Drop off Process The drop off process is the reverse of the pick up process. The integration endpoint will send attribute-­‐
value pairs to PingFederate and in return receive a reference ID to use when referring to these attributes. The high level steps involved in the drop off process are: 1. Open or define an HTTPS connection to the PingFederate pickup URL 2. Identify the Agentless Adapter configured on PingFederate to use 3. Authenticate to the service, and optionally configure certificate authentication 4. Send the attributes to the drop off service 5. Retrieve the reference value from the response Using the same scenario as above, we will drop off the value of “jsmith” in the attribute “subject” to the PingFederate drop off endpoint. HTTP Request POST https://pf.company.com:9031/ext/ref/dropoff HTTP/1.1 Headers Content-Length:
20 Content-Type:
application/json
Authorization:
BASIC c2FtcGxlX2lkOnNhbXBsZV9wYXNzd29yZA==
ping.instanceId:
sample_adapter
Body {
“subject”:”jsmith”
} The response from PingFederate to this request will be a reference ID with the value of “54321”: HTTP Response HTTP/1.1 200 OK Headers <N/A>
Body {
“REF”:”54321”
} 9 10 3 PingFederate Configuration Visit the product documentation section of the Ping Identity website For the Agentless Integration kit installation and configuration guide. This document contains information on how to deploy and configure the adapter in PingFederate. Note: The Agentless Integration Kit is referred to as the “Reference ID Adapter” inside PingFederate. This document will use these terms interchangeably. The following fields are configurable in the PingFederate administration console: Configuration Item Description Instance Name Adapter name used to display in the admin console Instance Id ID used to refer to the adapter from the adapter client Type Adapter type (Reference ID Adapter) Authentication Endpoint Authentication endpoint (entry point into adapter client) User Name Adapter client username Pass Phrase Adapter client password Allowed Subject DN Used for mutual TLS authentication Allowed Issuer DN Used for mutual TLS authentication Logout Service Endpoint Used for SLO only (SLO endpoint) Account Linking Authentication Endpoint Account Linking client entry point (SP Adapter only) Transport Mode Whether the REF values are transferred via a form post or a query parameter between the browser to/from PingFederate. (Form Post or Query Parameter) Reference Duration REF validity duration (1 -­‐ 95 seconds) Reference Length REF length (21 -­‐ 60 characters) Require SSL/TLS If checked, adapter client MUST use HTTPS to connect to PingFederate Outgoing Attribute Format How the attributes will be presented from PingFederate to the Adapter Client (ie during the Pickup process). (JSON or Properties) Incoming Attribute Format How the attributes will be presented from the Adapter Client to PingFederate (ie during the Drop off process). (JSON or Query Parameters) Logout Mode Used for SLO only -­‐ Front Channel or Back Channel Skip Hostname Validation Used for SLO only 3.1 Adapter Authentication Methods There are three methods that the agentless adapter can use to authenticate to PingFederate: • Custom HTTP header variables (ping.uname and ping.pwd) 11 •
•
HTTP BASIC authentication Mutual TLS (client certificate) authentication The examples in this document will use HTTP BASIC authentication (RFC 2617); however, the three authentication mechanisms will be discussed in detail here: 3.1.1 Custom HTTP header variables For applications that don’t have support for certificate authentication or Base64 encoding, the custom HTTP header variables (ping.uname and ping.pwd) can be used to send the adapter credentials to PingFederate. For example, the drop off request sample above can be modified to use custom headers instead of BASIC authentication: HTTP Request POST https://pf.company.com:9031/ext/ref/dropoff HTTP/1.1 Headers Content-Length:
20 Content-Type:
application/json
ping.uname:
sample_id
ping.pwd:
sample_password
ping.instanceId:
sample_adapter
Body {
“subject”:”jsmith”
} 3.1.2 HTTP BASIC Authentication HTTP Basic authentication involves Base64 encoding the username and password and including it in the HTTP Authorization header. The format is: “Authorization: BASIC “ + Base64_Encode( [USERNAME} + “:” + [PASSWORD] ) So using the above example, the Authorization header will be: “Authorization: BASIC “ + Base64_Encode(“sample_id:sample_password”) finally: “Authorization: BASIC c2FtcGxlX2lkOnNhbXBsZV9wYXNzd29yZA==” 12 HTTP Request POST https://pf.company.com:9031/ext/ref/dropoff HTTP/1.1 Headers Content-Length:
20 Content-Type:
application/json
Authorization:
BASIC c2FtcGxlX2lkOnNhbXBsZV9wYXNzd29yZA==
ping.instanceId:
sample_adapter
Body {
“subject”:”jsmith”
} 3.1.3 Mutual TLS (Certificate) Authentication Mutual TLS authentication requires some pre-­‐work on the PingFederate side and a slight change to how the adapter communicates with PingFederate. 1. Enable the secondary HTTPS port in the PingFederate run.properties file. For this example, we will set the value of pf.secondary.https.port to 9032. 2. Restart PingFederate for this to take effect. 3. Modify the adapter configuration to define the “Allowed Subject DN” and/or the “Allowed Issuer DN” of the client certificate you are using. 4. Modify the pickup/dropoff URL to use the secondary https port. 5. Include the client certificate with the request. Using the same example above, I am going to include a client certificate with the subject DN of “CN=sample_cert,O=company.com,C=US”. For step three above, I have modified the “Allowed Subject DN” configuration item with the Subject DN of our certificate. The adapter code was also modified to send the client certificate with the request. The client certificate was exported to a PEM file and the key has a passphrase of “sample_key_password”. The code sample below uses PHP to send the client certificate. $client_cert = dirname(__FILE__).'/sample_cert.cert.pem';
$client_key = dirname(__FILE__).'/sample_cert.key.pem';
$client_key_password = ‘sample_key_password’;
$http_headers[] = 'ping.instanceId: '.$adapter_instance_id;
// PHP can use curl to make the HTTP calls to the pickup endpoint
$crl = curl_init();
// Dropoff URL
13 curl_setopt($crl, CURLOPT_URL, $dropoff_loc);
curl_setopt($crl, CURLOPT_SSLCERT, $client_cert);
curl_setopt($crl, CURLOPT_SSLKEYTYPE, 'PEM');
curl_setopt($crl, CURLOPT_SSLKEY, $client_key);
curl_setopt($crl, CURLOPT_SSLKEYPASSWD, $client_key_password);
…
$result = curl_exec($crl);
The HTTPS request was changed to use the secondary HTTPS port (9032) of our PingFederate server so our HTTP POST now looks like (the certificate is transported during SSL/TLS negotiation and does not appear in the HTTP request): HTTP Request POST https://pf.company.com:9032/ext/ref/dropoff HTTP/1.1 Headers Content-Length:
20 Content-Type:
application/json
ping.instanceId:
sample_adapter
Body {
“subject”:”jsmith”
} Note: OpenSSL can be used to convert the PKCS12 certificate and key that is exported from the PingFederate administration console to a PEM format: PEM certificate only: openssl pkcs12 -­‐in <<certname>>.p12-­‐passin pass:<<pass>> -­‐nokeys -­‐out <<certname>>.cert.pem PEM key only: openssl pkcs12 -­‐in <<certname>>.p12 -­‐passin pass:<<pass>> -­‐nocerts -­‐out <<certname>>.key.pem PEM certificate + key: openssl pkcs12 -­‐in <<certname>>.p12 -­‐passin pass:<<pass>> -­‐out <<certname>>.certandkey.pem 14 4 IDP Adapter 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 – e.g. 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: • Traditional adapter integration, where the adapter is called during a federated SSO process; and • Streamlined adapter integration (form-­‐first) where the authentication form is called first to initiate SSO to an application They will be described separately due to slightly different integration steps, however we 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 The PingFederate IdP adapter configuration will look as follows: 15 16 4.1 Traditional PingFederate IdP Adapter Integration 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. IDP Authentication Adapter
Login Form
User's Browser
Identity Store
User requests authentication
User redirected to appropriate
IDP authentication adapter
User requests login
IDP adapter form presented
User submits credentials
Validate creds
vs ID store
Validation response
Successful authentication attempt
Return authn results
Provide SAML assertion /
integration kit token
Login Form
User's Browser
Identity Store
4.1.1 SSO Process 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: 17 Key Description 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: HTTP Request GET
https://pf.company.com:9031/idp/startSSO.ping?TargetResource=https%3A%2F%2Fap
p.company.com%2Fmyreport HTTP/1.1 Headers <N/A>
Body <N/A> The response from PingFederate will be a redirect to the IDP adapter’s “Authentication Endpoint” URL: HTTP Response HTTP/1.1 302 Found Headers Content-Type:
text/html;charset=UTF-8 Location:
https://idp.company.com/signin?resumePath=%2Fidp%2FVMnNz%2Fres
umeSAML20%2Fidp%2FstartSSO.ping&allowInteraction=true&reauth=f
alse
Body <N/A> 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. 18 4.1.2 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 sign-­‐in URL (/idp/VMnNz/resumeSAML20/idp/startSSO.ping). 4.1.3 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
19 4.1.4 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”. An HTTP request is made to the dropoff endpoint URL on the PingFederate server. This request contains the two attribute-­‐value pairs: HTTP Request POST https://pf.company.com:9031/ext/ref/dropoff HTTP/1.1 Headers Content-Length:
36 Content-Type:
application/json
Authorization:
BASIC aWRwX3VzZXI6aWRwX3Bhc3N3b3Jk
ping.instanceId:
idp
Body {
“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. HTTP Response HTTP/1.1 200 OK Headers <N/A>
Body {
“REF”:”ABCDEFGHIJKLMNOPQRSTUVWXYZ1234”
} Extract this reference token for use in the next step. This value will be referred to as [REF_VALUE] below and will be populated by the value received above (ABCDEFGHIJKLMNOPQRSTUVWXYZ1234). 20 4.1.5 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 Response HTTP/1.1 302 Found Headers Content-Type:
text/html;charset=UTF-8 Location:
https://pf.company.com:9031/idp/VMnNz/resumeSAML20/idp/startS
SO.ping?REF=ABCDEFGHIJKLMNOPQRSTUVWXYZ1234
Body <N/A> The IDP authentication adapter process is now complete and the user will continue with the SSO process. 21 4.2 Streamlined IDP Adapter Integration (Form-­‐First) A streamlined SSO process can be used in cases where the SSO action will always begin at the form. The workflow for this scenario is: IDP Authentication Adapter
Login Form
User's Browser
Identity Store
User requests authentication
Login form presented
User submits credentials
Validate creds
vs ID store
Validation response
Redirect to SSO initialization URL
Request SSO initialization URL
Provide SAML assertion /
integration kit token
Login Form
User's Browser
Identity Store
4.2.1 SSO Process 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. 4.2.2 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. 22 4.2.3 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 an 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: HTTP Request POST https://pf.company.com:9031/ext/ref/dropoff HTTP/1.1 Headers Content-Length:
36 Content-Type:
application/json
Authorization:
BASIC aWRwX3VzZXI6aWRwX3Bhc3N3b3Jk
ping.instanceId:
idp
Body {
“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 Response HTTP/1.1 200 OK Headers <N/A>
Body {
“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). 23 4.2.4 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 Response HTTP/1.1 302 Found Headers Content-Type:
Location:
text/html;charset=UTF-8 https://pf.company.com:9031/idp/startSSO.ping?TargetResource=
https%3A%2F%2Fapp.company.com%2Fmyreport&REF=ABCDEFGHIJKLMNOP
QRSTUVWXYZ1234
Body <N/A> The IDP authentication adapter process is now complete and the user will continue with the SSO process. 24 4.3 Single Log-­‐Out (SLO) Single Log-­‐Out 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. 4.3.1 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 Response HTTP/1.1 302 Found Headers Content-Type:
Location:
text/html;charset=UTF-8 Location:
https://idp.company.com/signout?REF=AABBCCDDEEFFGGHHIIJJKKLLM
MNNOO
Body <N/A> 4.3.2 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). 4.3.3 Step 2 – Pickup the information about the Logout 25 Similar to an SSO request, the adapter will make a HTTP GET request to the pickup endpoint to retrieve attributes about the logout: HTTP Request GET
https://pf.company.com:9031/ext/ref/pickup?REF=AABBCCDDEEFFGGHHIIJJKKLLMMNNOO
HTTP/1.1 Headers Authorization:
BASIC aWRwX3VzZXI6aWRwX3Bhc3N3b3Jk
ping.instanceId:
idp
Body <N/A> The response will contain information about the user who is requesting logout. HTTP Response HTTP/1.1 200 OK Headers <N/A>
Body {
"realm":"corp",
"subject":"jsmith",
"TargetResource":"https:\/\/app.company.com\/myreport",
"resumePath":"\/idp\/qrPqO\/resume\/idp\/startSLO.ping"
} 4.3.4 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. 4.3.5 Step 4 – Return the user to PingFederate 26 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 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 URL of: HTTP Response HTTP/1.1 302 Found Headers Content-Type:
Location:
text/html;charset=UTF-8 Location:
https://pf.company.com:9031/idp/qrPqO/resume/idp/startSLO.pin
g?source=idp
Body <N/A> The IDP authentication adapter process is now complete and the user will continue with the SSO process. 27 4.4 Error Handling Any errors during the processing of pick and dropoff requests from PingFederate will be returned as HTTP status codes. For example, if an incorrect client ID or password was specified, then a 401 HTTP error would be returned during the pickup / dropoff process. If an error occurs during an authentication attempt, then the authentication form should handle the error (e.g. display a message to the user) and abort the SSO process. 28 4.5 Other Considerations 4.5.1 Time Synchronization Ensure that the application server and the federation server are both within reasonable close time synchronization. The value of the “Reference Duration” configuration setting can also be used to allow for a larger tolerance for time skew. 4.5.2 Timeouts & Session Management The IdP adapter should maintain session for the user so that subsequent calls for authentication can re-­‐
use this login session and provide single sign-­‐on for the user. Note: The IdP adapter should honor the “forceAuthn” parameter to force the user to enter credentials even if the user has an existing session. 29 5 SP integration 5.1 SP Application Integration 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 (e.g. 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: Variable Value 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 The PingFederate SP adapter PingFederate configuration will look as follows: 30 5.1.1 SSO Process Initiation 31 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 an SSO event, PingFederate will redirect the user to this endpoint with the following parameters: Key Description 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 Response HTTP/1.1 302 Found Headers Content-Type:
Location:
text/html;charset=UTF-8 https://app.company.com/signin?TargetResource=https%3A%2F%2Fa
pp.company.com%2Fmyreport&REF=4321ZYXWVUTSRQPONMLKJIHGFEDCBA
Body <N/A> 5.1.2 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 5.1.3 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 an HTTP GET to the “pickup” endpoint with the [REF_VALUE] appended: 32 HTTP Request GET
https://pf.company.com:9031/ext/ref/pickup?REF=4321ZYXWVUTSRQPONMLKJIHGFEDCBA
HTTP/1.1 Headers Authorization:
BASIC YXBwX3VzZXI6YXBwX3Bhc3N3b3Jk
ping.instanceId:
app
Body <N/A> The response will contain the attributes about the identity and the authentication context: HTTP Response HTTP/1.1 200 OK Headers <N/A>
Body {
"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: Key Description 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. 33 5.1.4 Step 3 – Authorize and create an 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. 34 5.2 Account Linking 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 users 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. 5.2.1 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 Response HTTP/1.1 302 Found Headers Content-Type:
Location:
text/html;charset=UTF-8 https://app.company.com/actlink?REF=A1B2C3D4E5F6G7H9I0J1K2L3M
4N5O6
Body <N/A> 5.2.2 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. 5.2.3 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: 35 HTTP Request GET
https://pf.company.com:9031/ext/ref/pickup?REF=A1B2C3D4E5F6G7H9I0J1K2L3M4N5O6
HTTP/1.1 Headers Authorization:
BASIC YXBwX3VzZXI6YXBwX3Bhc3N3b3Jk
ping.instanceId:
app
Body <N/A> The response will contain the attributes about the identity and the authentication context: HTTP Response HTTP/1.1 200 OK Headers <N/A>
Body {
"partnerEntityID":"company:saml20:idp",
"resumePath":"\/sp\/stPFE\/resume\/sp\/ACS.ping"
}
A summary of these attributes is as follows: Key Description partnerEntityID The partner entity ID who authenticated the user. resumePath The location to return the user after completing the Account Link process. 5.2.4 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. 5.2.5 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. 36 For this example, we will use a local application ID of “M00123” as the local account to link. HTTP Request POST https://pf.company.com:9031/ext/ref/dropoff HTTP/1.1 Headers Content-Length:
22 Content-Type:
application/json
Authorization:
BASIC YXBwX3VzZXI6YXBwX3Bhc3N3b3Jk
ping.instanceId:
app
Body {
“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 Response HTTP/1.1 200 OK Headers <N/A>
Body {
“REF”:”P7Q8R9S0T1U2V3W4X5Y6Z7A8B9C0D1”
} Extract this reference token for use in the next step. This value will be referred to as [REF_VALUE] below. 5.2.6 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 37 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 Response HTTP/1.1 302 Found Headers Content-Type:
Location:
text/html;charset=UTF-8 Location:
https://pf.company.com:9031/sp/stPFE/resume/sp/ACS.ping?REF=P
7Q8R9S0T1U2V3W4X5Y6Z7A8B9C0D1
Body <N/A> 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. 38 5.3 Single Log-­‐Out (SLO) 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. 5.3.1 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 Response HTTP/1.1 302 Found Headers Content-Type:
Location:
text/html;charset=UTF-8 https://app.company.com/signout?REF=PPQQRRSSTTUUVVWWXXYYZZ112
23344
Body <N/A> 5.3.2 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”. 5.3.3 Step 2 – Pickup the information about the Logout 39 Similar to an SSO request, the adapter will make a HTTP GET request to the pickup endpoint to retrieve attributes about the logout: HTTP Request GET
https://pf.company.com:9031/ext/ref/pickup?REF=PPQQRRSSTTUUVVWWXXYYZZ11223344
HTTP/1.1 Headers Authorization:
BASIC YXBwX3VzZXI6YXBwX3Bhc3N3b3Jk
ping.instanceId:
app
Body <N/A> The response will contain information about the session requesting logout. HTTP Response HTTP/1.1 200 OK Headers <N/A>
Body {
"resumePath":"\/sp\/pCyCo\/resume\/sp\/SLO.ping",
"sessionid":"sFMcTOaropYv5gYQZi1ZOpX7DZ8"
}
The following attributes will be returned in the response: Attribute Description 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. 5.3.4 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). 40 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. 5.3.5 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 Response HTTP/1.1 302 Found Headers Content-Type:
Location:
text/html;charset=UTF-8 Location:
https://pf.company.com:9031/sp/pCyCo/resume/sp/SLO.ping?sourc
e=app
Body <N/A> The local application logout process is now complete and the user will continue with the SLO activity. 41 5.4 Error Handling Similar to the IDP scenario, any errors during the processing of pickup and dropoff requests from PingFederate will be returned as HTTP status codes. For example if an incorrect client ID or password was specified, then a 401 HTTP error would be returned during the pickup / dropoff process. The application will only receive a sign-­‐in request from a previously authenticated user. Any errors received during the authentication process should be handled as appropriate with application branding. The user would have already completed the authentication process at the IDP. Note: Error screens should be located outside the protected content. When a user receives an error during the sign-­‐in or authorization stages, they need to be able to view the error rather being sent back through the authentication process. 42 5.5 Other Considerations 5.5.1 Time Synchronization Ensure that the application server and the federation server are both within reasonably close time synchronization. The value of the “Reference Duration” configuration setting can also be used to allow for a larger tolerance for time skew. 5.5.2 Deep-­‐linking / Direct-­‐linking Deep linking or direct linking refers to the ability to access a page nested inside the protected content directly without having to navigate through a landing page. A deep link will be received by the application via the “TargetResource” parameter included in the initial redirect to the sign-­‐in URL. The application should honor this URL during the sign-­‐on process and redirect the user to the deep-­‐link after the application session is created. When recovering from a timeout or other scenario that may require re-­‐authentication, the application should include the requested URL in the request also. Note: When passing the TargetResource parameter or any URL parameter, be sure to URL-­‐encode the value. 5.5.3 Authorization Authorization includes determining whether the user has access to the application and what roles the user has when they are inside the application. The application will receive an already authenticated user and should perform any authorization decisions before creating an application session. It is important to place any error pages (i.e. “You are not authorized” errors) outside of the protected content area – otherwise you will send the user through an authentication loop as they continually try to authenticate to view the error page. 5.5.4 Application User Profile Management The application will receive an already authenticated user from a trusted identity provider that can contain additional attributes. This authenticated identity can be used to provision new accounts into the application store or update existing user profile information. 43 6 Code examples The following section contains sample pickup and dropoff code that can be used as a reference for integrating your application. Note: The below code is sample code and should not be considered production-­‐ready. Ensure any code deployed to a production environment is appropriately reviewed for that environment. 44 6.1 Microsoft .NET (C#) 6.1.1 Pickup string
string
string
string
string
string
pf_base_url = “https://pf.company.com:9031”;
ref_value = “ABCDEFGHIJKLMNOPQRSTUVWXYZABCD”;
app_instanceid = “app”;
app_username = “app_user”;
app_password = “app_password”;
pickup_loc = pf_base_url + “/ext/ref/pickup?REF=” + ref_value;
string
string
string
string
jsonResponseMessage = "";
httpResponseMessage = "";
httpResponseCode = "500";
returnUrl = "";
try
{
HttpWebRequest httpRequest =
(HttpWebRequest)HttpWebRequest.Create(pickup_loc);
// DEBUG / TESTING ONLY - Ignore SSL Cert Mismatch Errors
//ServicePointManager.ServerCertificateValidationCallback = delegate {
return true; };
byte[] httpAuthZHeaderBytes =
System.Text.Encoding.UTF8.GetBytes(app_username + ":" + app_password);
httpRequest.Headers.Add("Authorization", "Basic " +
Convert.ToBase64String(httpAuthZHeaderBytes));
httpRequest.Headers.Add("ping.instanceId", app_instanceid);
httpRequest.Method = "GET";
HttpWebResponse httpResponse =
(HttpWebResponse)httpRequest.GetResponse();
httpResponseCode = httpResponse.StatusCode.ToString();
httpResponseMessage = httpResponse.StatusDescription;
using (StreamReader rd = new
StreamReader(httpResponse.GetResponseStream()))
{
jsonResponseMessage = rd.ReadToEnd();
}
httpResponse.Close();
}
catch (WebException webex)
{
httpResponseCode = "500";
httpResponseMessage = webex.Message;
}
if (httpResponseCode == "OK")
{
// Parse the JSON response for the attributes
}
45 6.1.2 Dropoff string
string
string
string
string
string
json_attributes = “{ \”subject\”:\”jsmith\” }”;
pf_base_url = “https://pf.company.com:9031”;
app_instanceid = “app”;
app_username = “app_user”;
app_password = “app_password”;
dropoff_loc = pf_base_url + “/ext/ref/dropoff”;
string jsonResponseMessage = "";
string httpResponseMessage = "";
string httpResponseCode = "500";
try
{
HttpWebRequest httpRequest =
(HttpWebRequest)HttpWebRequest.Create(dropoff_loc);
// DEBUG / TESTING ONLY - Ignore SSL Cert Mismatch Errors
//ServicePointManager.ServerCertificateValidationCallback = delegate {
return true; };
byte[] httpAuthZHeaderBytes =
System.Text.Encoding.UTF8.GetBytes(app_username + ":" + app_password);
httpRequest.Headers.Add("Authorization", "Basic " +
Convert.ToBase64String(httpAuthZHeaderBytes));
httpRequest.Headers.Add("ping.instanceId", app_instanceid);
httpRequest.Method = "POST";
httpRequest.ContentType = "application/json";
byte[] httpRequestMessage =
System.Text.Encoding.UTF8.GetBytes(json_attributes);
httpRequest.ContentLength = httpRequestMessage.Length;
using (Stream stream = httpRequest.GetRequestStream())
{
stream.Write(httpRequestMessage, 0, httpRequestMessage.Length);
}
HttpWebResponse httpResponse =
(HttpWebResponse)httpRequest.GetResponse();
httpResponseCode = httpResponse.StatusCode.ToString();
httpResponseMessage = httpResponse.StatusDescription;
using (StreamReader rd = new
StreamReader(httpResponse.GetResponseStream()))
{
jsonResponseMessage = rd.ReadToEnd();
}
httpResponse.Close();
}
46 catch (WebException webex)
{
httpResponseCode = "500";
httpResponseMessage = webex.Message;
}
if (httpResponseCode == "OK")
{
// grab the REF value returned in the JSON string
}
47 6.2 PHP 6.2.1 Pickup function PickupAttributes($ref_value)
{
// Get adapter configuration
$pingfederate_base_url = “https://pf.company.com:9031”;
$adapter_instance_id = “app”;
$app_username = “app_user”;
$app_password = “app_password”;
$pickup_loc = $pingfederate_base_url.'/ext/ref/pickup?REF='.$ref_value;
$http_headers[] = “ping.instanceId: “.$adapter_instance_id;
// PHP can use curl to make the HTTP calls to the pickup endpoint
$crl = curl_init();
// Pickup URL
curl_setopt($crl, CURLOPT_URL, $pickup_loc);
// HTTP BASIC authentication
curl_setopt($crl, CURLOPT_HTTPAUTH, CURLAUTH_BASIC ) ;
curl_setopt($crl, CURLOPT_USERPWD, $app_username.':'.$app_password);
// OR CERTIFICATE authentication
//$client_cert = dirname(__FILE__).'/pm-test.cert.pem';
//$client_key = dirname(__FILE__).'/pm-test.keyP.pem';
//$client_key_password = 'pm-test';
//curl_setopt($crl, CURLOPT_SSLCERT, $client_cert);
//curl_setopt($crl, CURLOPT_SSLKEYTYPE, 'PEM');
//curl_setopt($crl, CURLOPT_SSLKEY, $client_key);
//curl_setopt($crl, CURLOPT_SSLKEYPASSWD, $client_key_password);
// Add the ping.instanceId
// Also where custom HTTP header authentication is defined
// $http_headers[] = “ping.uname: “.$app_username;
// $http_headers[] = “ping.pwd: “.$app_password;
curl_setopt($crl, CURLOPT_HTTPHEADER, $http_headers);
// For debug purposes - Ignore SSL errors
curl_setopt($crl, CURLOPT_SSL_VERIFYHOST, false);
curl_setopt($crl, CURLOPT_SSL_VERIFYPEER, false);
// We want curl to return response
curl_setopt($crl, CURLOPT_RETURNTRANSFER, true);
$result = curl_exec($crl);
if ( $result == false ) {
print_r('Curl error: ' . curl_error($crl));
} else {
// Successful Pickup
$json_attributes = json_decode($result, true);
}
48 curl_close($crl);
return $json_attributes;
//
$json_attributes[‘subject’] == “jsmith”
}
6.2.2 Dropoff function DropoffAttributes($json_attributes)
{
// Get adapter configuration
$pingfederate_base_url = “https://pf.company.com:9031”;
$adapter_instance_id = “app”;
$app_username = “app_user”;
$app_password = “app_password”;
$dropoff_loc = $pingfederate_base_url.'/ext/ref/dropoff’;
$content_length = strlen( utf8_decode( $json_attributes ) );
$http_headers[] = “ping.instanceId: “.$pf_instanceid;
$http_headers[] = “Content-length: “.$content_length);
$http_headers[] = “Content-type: application/json”;
$crl = curl_init();
//HTTP BASIC authentication
curl_setopt($crl, CURLOPT_HTTPAUTH, CURLAUTH_BASIC ) ;
curl_setopt($crl, CURLOPT_USERPWD, $app_username.':'.$app_password);
// OR CERTIFICATE authentication
//$client_cert = dirname(__FILE__).'/pm-test.cert.pem';
//$client_key = dirname(__FILE__).'/pm-test.keyP.pem';
//$client_key_password = 'pm-test';
//curl_setopt($crl, CURLOPT_SSLCERT, $client_cert);
//curl_setopt($crl, CURLOPT_SSLKEYTYPE, 'PEM');
//curl_setopt($crl, CURLOPT_SSLKEY, $client_key);
//curl_setopt($crl, CURLOPT_SSLKEYPASSWD, $client_key_password);
// Dropoff URL
curl_setopt($crl, CURLOPT_URL, $dropoff_loc);
// Add the additional HTTP headers
// Also where custom HTTP header authentication is defined
// $http_headers[] = “ping.uname: “.$app_username;
// $http_headers[] = “ping.pwd: “.$app_password;
curl_setopt($crl, CURLOPT_HTTPHEADER, $http_headers);
// For debug purposes - Ignore SSL errors
curl_setopt($crl, CURLOPT_SSL_VERIFYHOST, false);
curl_setopt($crl, CURLOPT_SSL_VERIFYPEER, false);
// We want curl to return response
curl_setopt($crl, CURLOPT_RETURNTRANSFER, true);
49 // We are making a HTTP POST
curl_setopt($crl, CURLOPT_POST, true);
curl_setopt($crl, CURLOPT_POSTFIELDS, $json_attributes);
$return_object = curl_exec($crl);
if ( $return_object == false ) {
print_r('Curl error: ' . curl_error($crl));
} else {
// Successful Pickup
$json_reference = json_decode($return_object, true);
$reference = $json_reference[‘REF’];
}
curl_close($crl);
return $reference;
}
6.3 Java Server Pages (JSP) See the Agentless Integration Kit sample applications. 50