PingFederate
®
Cloud Identity Connector
for Facebook
Version 1.0
User Guide
© 2010 Ping Identity® Corporation. All rights reserved.
PingFederate Cloud Identity Connector for Facebook User Guide
Version 1.0
December, 2010
Ping Identity Corporation
1099 18th Street, Suite 2950
Denver, CO 80202
U.S.A.
Phone: 877.898.2905 (+1 303.468.2882 outside North America)
Fax: 303.468.2909
Web Site: www.pingidentity.com
Trademarks
Ping Identity, the Ping Identity logo, PingFederate, and the PingFederate icon are trademarks or registered
trademarks of Ping Identity Corporation.
All other trademarks or registered trademarks are the properties of their respective owners.
Disclaimer
This document is provided for informational purposes only, and the information herein is subject to change
without notice. Ping Identity Corporation does not provide any warranties and specifically disclaims any liability in
connection with this document.
PingFederate Cloud Identity Connector for Facebook
2
User Guide
Contents
Introduction .....................................................................................................................................4 Intended Audience .....................................................................................................................4 Additional Resources .................................................................................................................4 ZIP Manifest ...............................................................................................................................4 Overview ....................................................................................................................................5 System Requirements ................................................................................................................6 Installation and Configuration.......................................................................................................6 Step 1: Install the Facebook Adapter .........................................................................................6 Step 2: Register the Facebook Application ................................................................................6 Step 3: Configure PingFederate ................................................................................................7 Step 4: Application Integration .................................................................................................11 Extended Development ................................................................................................................12 Troubleshooting ...........................................................................................................................12 PingFederate Cloud Identity Connector for Facebook
3
User Guide
Introduction
The Facebook Cloud Identity Connector allows a Service Provider (SP) enterprise to leverage Facebook
as a Cloud Identity Provider (IdP) in order to access applications and services in the SP domain. The
included Facebook Adapter works with the Facebook Graph Reference API to allow PingFederate to
perform single sign-on (SSO) to Service Provider (SP) applications based on Facebook credentials.
Intended Audience
This document is intended for system administrators with experience in the configuration and
maintenance of IT infrastructure. Some familiarity with the Facebook Graph Reference API as it
pertains to your application may be helpful for extended implementations. Knowledge of networking
and user-management configuration is assumed. Please consult documentation provided at Facebook if
you encounter any difficulties in areas not directly associated with PingFederate or the Facebook
Adapter.
Additional Resources
Administrators may want to review the PingFederate Administrator’s Manual—specifically the
information on adapters and integration kits.
Tip: If you encounter any difficulties with configuration or deployment, please try searching
the Ping Identity Customer Portal (www.pingidentity.com/support-and-downloads/portal.cfm)
under Answers.
PingFederate documents may include hypertext links to third-party Web sites that provide installation
instructions, file downloads, and reference documentation. These links were tested prior to publication,
but they may not remain current throughout the life of these documents. Please contact Ping Identity
Support (support.pingidentity.com) if you encounter a problem.
ZIP Manifest
The distribution ZIP file for the Integration Kit contains the following:
•
/docs – contains this documentation:
–
Facebook_Cloud_Identity_Connector_Qualification_Statement.pdf – testing and
platform information
•
–
Facebook_Cloud_Identity_Connector_User_Guide.pdf – this document
–
Legal.pdf – copyright and license information
/dist – contains libraries needed for the Adapter
–
pf-facebook-adapter-1.0.jar – Facebook Adapter JAR file
–
json-simple-1.1.jar – JavaScript Object Notation (JSON) JAR file
PingFederate Cloud Identity Connector for Facebook
4
User Guide
Overview
The following figure displays an example SSO process flow between Facebook, PingFederate, and the
Web Application using the Facebook Adapter:
Processing Steps
1. User navigates to a Web application and chooses to log on using Facebook.
2. The browser is redirected to the Facebook Adapter.
3. PingFederate redirects the user to Facebook for authentication. A list of requested permissions is
provided in this call. Facebook authenticates the user and provides a consent page for the user to
authorize the sharing of information. Once the user authorizes, Facebook redirects the browser to
the /ext/facebook-authn/ endpoint with an authorization code.
If the user does not authorize Facebook to share information, an error is returned rather than the
authorization code.
4. The Adapter makes an HTTP request to Facebook to obtain an access token, sending the
Application ID, Application Secret, and authorization code.
5. Facebook validates these components and returns an access token.
6. The Adapter uses the access token to request user information. The fields requested are based on
the fields listed in the Adapter contract.
7. Facebook returns the user information.
8. The Adapter redirects the user to the Web application with the user attributes.
PingFederate Cloud Identity Connector for Facebook
5
User Guide
System Requirements
The Facebook Adapter requires installation of PingFederate 6.2 or higher.
Installation and Configuration
This section describes how to:
•
Install the Facebook Adapter
•
Register an application within Facebook
•
Configure PingFederate
•
Add a URL link to a Web application
Step 1: Install the Facebook Adapter
To install the Facebook Adapter:
1. Stop the PingFederate server if it is running.
2. From the /dist directory, copy the pf-facebook-adapter-1.0.jar and the json-simple1.1.jar into:
<PF-install>/server/default/deploy
3. Start or restart PingFederate.
Step 2: Register the Facebook Application
You must use an existing Facebook profile to register the Facebook application.
To register the Facebook application:
1. Log on to your Facebook account and register the new application.
See http://www.facebook.com/developers/ for more information on setting up the application.
Important: The Site URL requested when creating the new application is the fully qualified
host name, port, and path for the PingFederate endpoint:
http[s]://<pf host>:<pf port>/ext/facebook-authn/
2. After setting up the application, make note of the Application ID, Application Secret, and the Site
URL.
PingFederate Cloud Identity Connector for Facebook
6
User Guide
Step 3: Configure PingFederate
To configure PingFederate, follow the instructions in each of the following sections, in order:
Configuring System Settings
If you have not yet used PingFederate, follow the instructions under “Running PingFederate for the First
Time” in the “Installation” chapter of the Getting Started manual. To enable connections to Facebook,
several selections (described in the following procedure) are required when you reach Roles and
Protocols in the Configuring My Server screen sequence.
If you have already run and configured the PingFederate server, you may need to verify or change settings
on the Roles and Protocols screen.
To configure System Settings:
1. On the Roles and Protocols screen, ensure that the IdP role is enabled and the SAML 2.0 protocol is
selected for that role.
(Click Server Settings on the Main Menu to locate this screen after initial installation.)
2. Enable the SP role, also using SAML 2.0 as the protocol.
Configuring the IdP Adapter
1. Log on to the PingFederate administrative console and click Adapters under My IdP Configuration
on the Main Menu.
(For more information about IdP Adapters, see the PingFederate Administrator’s Manual.)
2. On the Manage IdP Adapter Instances screen, click Create New Instance.
3. On the Type screen, enter an Instance Name and Instance ID.
The Name is any you choose for identifying this Adapter Instance. The ID is used internally and may
not contain spaces or non-alphanumeric characters.
Note: You can have multiple types of adapters, but only one Facebook Adapter instance.
4. Select Facebook Adapter 1.0 from the Type list and click Next.
PingFederate Cloud Identity Connector for Facebook
7
User Guide
5. On the IdP Adapter screen provide entries for each of the fields shown, as indicated in the table
below.
Field Name
Description
Application ID
Enter the Application ID Facebook generates when you create the
Facebook application. For information on creating this application, see Step
2: Register the Facebook Application on page 6.
Application Secret
Enter the Application Secret Facebook generates when you create the
Facebook application. For information on creating this application, see Step
2: Register the Facebook Application on page 6.
Site URL
Enter the Site URL for the PingFederate endpoint. You define this URL
when creating the Facebook application.
Unauthorized
Redirect URL
Enter an endpoint URL for redirecting the user if the user declines
authorizing Facebook to share information. This URL may contain query
parameters.
PingFederate Cloud Identity Connector for Facebook
8
User Guide
Field Name
Description
Error Redirect URL
Enter a URL for redirecting the user if there are errors, for example: wrong
parameters in the link. This URL may contain query parameters.
6. (Optional) To add attributes beyond the defaults that Facebook provides, use the Scope Permissions
section of the IdP Adapter screen.
a. Click Add a new row to ‘Scope Permissions.’
b. Select an attribute from the drop-down list on the left.
Note: If the desired attribute does not appear in the list, type it into the Additional Facebook
Scope Permission box. You must use the correct syntax for manual entries. For more
information, see the Extended Permissions page on Facebook:
http://developers.facebook.com/docs/authentication/permissions.
c. Click Update.
7. Click Next.
PingFederate Cloud Identity Connector for Facebook
9
User Guide
8. On the Extended Contract screen, if you added additional permissions on the previous screen, then
you must add the corresponding attribute to the contract in order for those values to be passed to the
Web application.
Although some permissions do not have a corresponding attribute, most permissions do. For
example, the current version of Facebook includes an extended permission called
user_religion_politics. Once the user authorizes Facebook to share that information, Facebook sends
back the attributes: religion and/or political (if the information exists in the profile). In order for the
religion and/or political attributes to be passed to the Web application, you must add those attributes
on this page.
Note: For a list of the properties associated with extended permissions in Facebook, see
http://developers.facebook.com/docs/authentication/permissions.
9. Click Next.
PingFederate Cloud Identity Connector for Facebook
10
User Guide
10. On the Adapter Attributes screen, select any checkbox under Pseudonym.
Pseudonyms are opaque subject identifiers used for SAML account linking and are not applicable in
the context of cloud-identity deployments. To ensure correct PingFederate performance under all
circumstances, however, a selection is required. (For information about account linking, refer to the
“Key Concepts” chapter in the PingFederate Administrator’s Manual, or click Help on this screen.)
11. On the Summary screen, verify that the information is correct and click Done.
12. On the Manage IdP Adapter Instances screen, click Save to complete the configuration.
Configuring the SP Adapter
In order to establish a session with the user, you must configure an SP Adapter. Ping Identity offers
numerous SP integration kits as well as the OpenToken Adapter that is bundled with PingFederate.
To configure the OpenToken Adapter, see “OpenToken Adapter Configuration” in the Administrator’s
Manual. For more information on the Ping Identity integration kits, see the list of kits available on the
Ping Identity Web site-www.pingidentity.com/support-and-downloads.
Configuring Adapter-to-Adapter Mapping
Use this configuration when you are using Facebook as the IdP for SSO to a Web application at your
site. This configuration allows user attributes from the IdP Facebook Adapter to be used to create an
authenticated session via an SP adapter on the same PingFederate server.
Note: If you want to leverage Facebook credentials for SSO to another SP, you can also set
up an SP connection using the Facebook Adapter instance (see “Identity Provider SSO
Configuration” in the Administrator’s Manual).
1. To configure Adapter-to-Adapter Mapping, ensure that you have already configured the required IdP
and SP adapter instances (see “Configuring the IdP Adapter” on page 7 and “Configuring the SP
Adapter” on page 11).
2. Select IdP-to-SP Adapter Mapping from the PingFederate Main Menu to complete the
configuration (see the “IdP-to-SP Adapter Mapping” section of the “System Settings” chapter of the
PingFederate Administrator’s Manual (or see the Help).
Step 4: Application Integration
To authenticate using the Facebook Cloud Identity Connector, users must go to PingFederate to initiate
authentication:
¾ Use the following URL in a hypertext link on your Web-application logon page to start SSO:
https://<pf_host>:<pf_port>/pf/adapter2adapter.ping?IdpAdapterId=<adapterId>
PingFederate Cloud Identity Connector for Facebook
11
User Guide
where:
•
<pf_host> is the host name or IP address where PingFederate is running.
•
<pf_port> is the port number for PingFederate.
•
<adapterId> is the Instance ID defined in the Facebook IdP Adapter setup earlier.
Extended Development
By default, the Web application can access all public data in a user’s profile, including name, profile
picture, gender, and friends. If your Web application needs to access other parts of the user’s profile that
may be private, you must request extended permissions. For example, if you want to incorporate a user’s
photos into your Web application, you would request the user_photos extended permission. During
authentication, users are asked whether they want to authorize your application to access their photos.
However, no actual photos are sent. The Facebook Adapter sends back an access token and the user
attributes to your application. Incorporate this access token into an HTTP request from the Web
application to the Facebook API to get the actual photos from Facebook.
For information on using the access token to fetch information that requires additional calls, see the
Facebook developer documentation: http://developers.facebook.com/docs/authentication/permissions
Note: The Facebook Adapter provides no check to determine whether a requested field is
available for the User API call. It is up to the SP Provider to make this determination.
Troubleshooting
The following table lists potential problems administrators might encounter during the setup or
deployment of the Facebook Adapter, along with possible solutions.
Problem
Possible Cause/Solution
The launch URL fails to reach
the PingFederate endpoint, and
you are running the
PingFederate server behind a
reverse proxy.
You may need to extend the existing proxy rules within your
network to allow network traffic to the endpoint (<pf
host>:<pf port>/ext/facebook-authn/).
User is redirected to the
configured Unauthorized URL (in
the Adapter UI) with an
error_msg parameter appended
to the URL.
• During authentication, the user did not authorize transfer of
• An administrator entered an invalid permission in the Adapter
The HTTP Error 400 - Bad
Request error message displays.
The user attempted to access the Site URL endpoint directly
from the browser.
his or her attributes.
setup.
PingFederate Cloud Identity Connector for Facebook
12
User Guide