Tuesday, March 8, 2016

Facebook (API v2.5) as a Federated Authenticator in WSO2 Identity Server 5.1.0

WSO2 Identity Server supports Federated Authentication [1] where a client application can talk to Identity Server for authentication (i.e SAML) and Identity Server can redirect the user to an external Identity Provider such as Facebook, Google, Twitter, LinkedIn etc. where the user would login to the external Identity Provider with an existing account (i.e facebook account) and upon successful login, the external Identity Provider (i.e facebook) would notify Identity Server with the logged in user’s claims. Then the Identity Server can respond to the client application with the authentication response (i.e SAML response) along with the user claims that are requested by the service provider.

In this post, how to use Facebook as a federated Identity Provider [2] with WSO2 Identity Server 5.1.0 is explained providing step by step instructions. The flow of the authentication is given in the following diagram.

Create an OAuth Application in Facebook
First we need to login to the Developer account of facebook http://developers.facebook.com/ . Go to ‘My Apps’ and click on ‘Add a New App’.

As the platform, select ‘Website’.

Then you need to provide an ID for the facebook application. Here I name the application as ‘IS_FEDERATED_APP_1’.

Select a category for the application and create the App ID.

After creating the application, you can skip the Quick Start and view the configuration of the application.

In the Dashboard of the application, you can view the configuration related to the application. ‘App ID’ is the Client ID and the ‘App Secret’ is the Client Secret in OAuth terminology. API Version is facebook’s API that is used to create the application. By the time of this writing, the latest version of the API is v2.5 and WSO2 Identity Server 5.1.0 is compatible with this version.

Go to the Settings menu and select Basic configuration. Here as an  application domain, I am adding localhost as the Identity Server is running in localhost. Then I am adding a new platform for the application.

As the new platform, I am selecting Website.

As the Website URL, I am adding https://localhost:9443/ where the Identity Server is running.

Then go to the Advanced settings.

Under the Client OAuth Settings, enable Client OAuth Login and Web OAuth Login. As the OAuth redirect URL, I am adding the commonauth endpoint of WSO2 Identity Server, which is https://localhost:9443/commonauth .

Since this application is not yet published, during the authentication flow, you cannot login to facebook with any facebook account other than the account that you used to create the OAuth application in facebook developer account. If you need to add any other accounts, you can go to the Roles menu and add new users.

Now we have completed the basic configuration at facebook side by creating an OAuth application and obtaining Client ID and Client Secret values.  

Register Facebook as a Federated Identity Provider in Identity Server

Next step is registering facebook as a Federated Identity Provider in Identity Server. For that, login to the Management Console of the Identity Server.

Add a new Identity Provider.

Here as the Identity Provider Name, I am giving ‘fb_idp’. You can give any name for this.

In the Identity Provider configuration, set the configuration for the Facebook federated Identity Provider. For the Client ID and Client Secret, enter the App ID and App Secret values you got from the OAuth application created in facebook developer account. As the scope, I am adding email. You can refer [3] and get to know the different permission groups in facebook APIs. As the User Information Fields, I have added “id,name,gender,email,first_name,last_name,age_range,link” fields. These are the claims related to the user account on facebook. Identity Server requests these fields from facebook when a user gets authenticates with facebook through Identity Server. You can get to know more about these fields from [4].

Next step is to map the Facebook user’s claims with the local claims which the Identity Server identifies for a user account. For that, inside the Identity Provider configuration, under Claim Configuration’s Basic Claim Configuration, define a custom claim dialect. In this claim dialect, add mapping for each facebook user claim with the local claim URI. Here, as the User ID Claim URI, I am using the email claim of facebook user which is unique for a user account in facebook.

Now the Identity Provider configuration is successfully added in Identity Server.

Register the Service Provider Configuration for the Client Application

Next step is to configure the Service Provider, so that the client application can talk to Identity Server for authentication. Here I am using the travelocity.com sample web application that uses SAML 2 for user authentication with Identity Server. You can refer [5] for setting up the travelocity sample.

Here I add a new Service Provider in Identity Server with the name ‘travelocity.com’.

Then for Inbound Authentication Configuration, I add SAML 2 Web SSO Configuration. As the SAML Issuer name, I use travelocity.com and for Assertion Consumer URL I define http://localhost:8080/travelocity.com/home.jsp where the travelocity.com webapp is running in a tomcat server in localhost’s 8080 port.

Next step is to set the Requested Claims of the Service Provider. These are the user claims that are ultimately sent to the client application upon a user gets authenticated with the Identity Server. Here I am using the default claim dialect where the travelocity.com sample app will receive the user claims with the same claim URIs as in Identity Server. As the Subject Claim URI, I use the email address claim which would be unique for any user.

Next step is to link the Identity Provider created with the facebook federated authenticator. For that, expand the Local & Outbound Authentication Configuration of the Service Provider and select Federated Authentication. As the federated authenticator, select the Identity Provider which you created for facebook.

Once all the Service Provider configuration is done, update the Service Provider.

Testing the Facebook Federated Authentication with travelocity.com Sample

Now all the configuration at Identity Server and Facebook are complete and we can test the entire authentication flow. Login to the travelocity.com sample application.

The travelocity.com sample will talk to the Identity Server sending a SAML 2 authentication request (along with the SAML issuer’s name as travelocity.com). Identity Server identifies the associated Service Provider for this request by looking at the SAML Issuer name. Then Identity Server gets to know that this Service Provider is linked with an Identity Provider where facebook is configured as a federated Identity Provider. So it redirects the browser to facebook.com . If you have not logged into facebook.com in the browser, it will show the login page of facebook. You need to login to facebook account (from the same account you created the OAuth app in developer account on facebook, or from any other facebook account that is added under the roles of the configuration of the OAuth app, since the OAuth application is not published to public yet).

Upon successful login, Facebook will prompt the user that the OAuth app is trying to access the personal information of the user.

Upon allowing this, facebook will gather the user’s claims which were requested by Identity Server by setting the User Information Fields in Facebook federated authenticator and sends back to the Identity Server.

Then the Identity Server will map these facebook user’s claims to the local claims that the Identity Server knows. Then Identity Server will check the Service Provider’s configuration and find out which claims are requested by the client application and picks the requested claims out of the set of claims and sends back to the client application.

Here the travelocity.com sample app receives the user’s claims and also the user is successfully authenticated to the travelocity.com sample application.

Similarly, you can develop client applications that uses WSO2 Identity Server for authentication and link with any 3rd party Identity Provider for Identity Federation. This way you do not need to manage user accounts at Identity Server, but you let users get authenticated with their existing user accounts at the external Identity Providers.


Tharindu Edirisinghe
Platform Security Team


  1. I am very much pleased with the contents you have mentioned. I wanted to thank you for this great article. I enjoyed every little bit part of it and I will be waiting for the new updates.
    Facebook app development companies

  2. Pretty! This was aan extremely wonderful post. Thank you for providing this info.