Integrate an application with Facebook Login for Apps

Learn how to incorporate ISAM 9.0.2 with social media authentication


Modern applications frequently contain social login capabilities, allowing customers to reuse their existing IDs from other providers, such as Facebook. Safely implementing social login capabilities can be difficult, time consuming, and can potentially introduce vulnerabilities. Retrieving a user's social ID is just part of the broader security picture, as many offerings do not also consider access control and authorization.

IBM Security Access Manager (ISAM) contains strong access control and authorization capabilities, and now features a powerful new capability that allows rich custom authentication scenarios, like a social login. This article will demonstrate how identities from Facebook, LinkedIn, and Instagram can be used in your ISAM environment.

Integrating social authentication into any application for many social login providers requires implementing an OAuth 2.0 client. After implementation of the client, social authentication requires exercising an authorization code flow with the social identity provider, followed by the retrieval of an identity profile resource.

This pattern of using OAuth 2.0 for authentication is quite common. For example, Facebook, LinkedIn, and Instagram all provide similar, yet subtly different, interfaces that achieve the same goal of retrieving a user's social identity profile.

In this article, we demonstrate the complete process of social login integration for ISAM with Facebook as an example, and provide resources for recreating the same type of integration with LinkedIn and Instagram.

What differentiates the technique that is described in this article from previous social integrations with ISAM is that the entire solution runs on the ISAM appliance.

About Facebook Login for Apps

Facebook Login for Apps is a popular authentication mechanism that is used by developers to provide a frictionless method for users. Users with an existing Facebook account can enroll new accounts, link to existing local accounts, and authenticate. The solution requires users to register as a Facebook developer. They must include the creation of a Facebook "application" definition and its associated OAuth 2.0 client credentials. These credentials are used within your application (in our case, an ISAM authentication plugin) to interact with Facebook to achieve user authentication.

About ISAM authentication and the 9.0.2 InfoMap authentication mechanism

ISAM supports third-party authentication via the External Authentication Interface (EAI), and existing examples demonstrate how to use EAI and an auxiliary application to achieve a succesful Facebook login to WebSEAL. This approach, while functional, requires running a third-party web application server to act as the EAI host (such as WebSphere®).

In addition to EAI (it is actually an instance of an EAI that's part of ISAM), the Advanced Access Control (AAC) capabilities of ISAM include an authentication service. This service contains various mechanisms, such as TOTP, SMS OTP, knowledge questions, and more.

ISAM 9.0.2 introduces a new, highly flexible authentication mechanism to the authentication service known as InfoMap. This new mechanism allows rich and sophisticated authentication logic to be built by using server-side JavaScript and client-side HTML page templates. The server-side JavaScript is able to leverage ISAM-specific platform APIs (similar to federation mapping rules), such as account-linking functions, an HTTPS client, and temporary and expirable storage.

In AAC, mechanisms are assembled into authentication policies. Authentication policies are linear workflows that consist of one or more authentication mechanisms. The authentication service and the new InfoMap authentication mechanism were used to construct all of the new User Self Care scenarios that are available in ISAM 9.0.2.

This article introduces a method for using the InfoMap authentication mechanism to implement OAuth 2.0 clients for social authentication with Facebook as the primary example. You'll also find Downloadable resources for LinkedIn and Instagram the at the end of this tutorial, which we tested.


To use Facebook Login with ISAM, the following prerequisites are required:

Facebook setup

You will need to set up your Facebook account by using the Facebook Login product. At a high level, these steps are:

  1. Enroll on the Facebook for Developers site.
  2. Create a new Facebook Login application.
  3. Configure the Facebook Login application with the correct redirect URI to your Reverse Proxy instance.
  4. Retrieve the Application ID and Application Secret for your Facebook Login application – these will be used in the ISAM configuration.

Enroll as a Facebook developer and create an application

Complete your enrollment on If you are enrolling for the first time, you might be asked to create an application as part of the enrollment flow. If you are already enrolled, you will need to log in and create a new application. Either way, go ahead and create a Facebook application.


At this point, you registered as a Facebook developer and created a Facebook application (in our case, called ISAM9Demo).


Add the Facebook Login product to your app

Facebook requires your application to have the Facebook Login "product" configured for your application.

Select My Apps and then select the App ID that was created in the previous step.

fb app landing page
fb app landing page

This is the landing page for the Facebook application to which we will add the Facebook Login product. Note that Facebook Login is just one of many products you can add to this Facebook application.

fb app dashboard
fb app dashboard

On the Dashboard page, click Add product. Then click the Get Started button (next to Facebook Login).

You will see the Settings page for the new instance of Facebook Login. Client OAuth Login and Web OAuth Login should be enabled by default, and the only data we need to enter is the redirect URI.


Configure the redirect URI

When interacting with Facebook Login, the Facebook Login application needs a list of valid redirect URIs. The URI that should be provided to Facebook is the URL to the authentication service. This URL usually looks like, where is the address of the Reverse Proxy and /mga is the path of the AAC junction.

Note: /mga is the default path configured when using the AAC config tool.

Complete the redirect URI configuration as shown in the following image.

valid oauth redirect uri
valid oauth redirect uri

Retrieve the Facebook application credentials

Navigate back to the application Dashboard to display the properties of the Facebook application. On this page, record the App ID and App Secret. Click the Show button to show the masked App Secret field.

app secret
app secret

You just configured a Facebook application with the Facebook Login product! You also retrieved the App ID and App Secret that are ready for configuration in ISAM.

ISAM setup

To configure the ISAM authentication service for Facebook Login, you need to create a new authentication mechanism and policy.

The authentication mechanism will be an instance of an InfoMap authentication mechanism. Instances of the InfoMap mechanism require a JavaScript mapping rule, which handles the server-side logic and an HTML page that is served to the browser.

At a high level, the steps to set up ISAM are:

  1. Upload the JavaScript mapping rule and HTML template.
  2. Create a new instance of the InfoMap mechanism that is configured to use the JavaScript mapping rule and HTML template.
  3. Create a new authentication policy that contains the new InfoMap mechanism instance.
  4. Configure ISAM to allow users that do not exist in the user registry to be able to log in.
  5. Ensure that Facebook is accessible from the Appliance and that the AAC runtime trusts the signer CA's of Facebook's endpoint.
  6. Update the Reverse Proxy instance to pass some additional information to the Advanced Access Control Runtime.

Upload the JavaScript mapping rule and HTML template

There are two files that are used by the InfoMap mechanism:

  1. A JavaScript mapping rule, which performs the server side logic, including communication with Facebook Login
  2. An HTML template page that is used to initiate the login process in the web browser.

Before the JavaScript mapping rule can be used, it must be populated with the authentication service URL and Facebook Login App ID/Secret. Open the file facebook.js in a text editor and update the values listed below:

// Parameters you need to update - the appID and appSecret come
from your Facebook application
// and the redirectHostAndJunction depends on your ISAM
var appID = "xxxx";
var appSecret = "yyyy";
var redirectHostAndJunction = "";

Upload the updated facebook.js mapping rule to the appliance. The steps for uploading a mapping rule can be found in the "Managing JavaScript mapping rules" section within the ISAM documentation.

When uploading the rule, use the category InfoMap. The next steps in this article assume that the mapping rule was uploaded with the name FacebookInfoMap.

create mapping rule
create mapping rule

The HTML template file can be used as is, but can later be customized to suit your environment. The steps for uploading a HTML template page can be found in the Modifying template files" section within the ISAM documentation.

The HTML template should be uploaded to the path /authsvc/authenticator/facebook/facebook.html

create a file
create a file

Configure the InfoMap authentication mechanism

Now that the required JavaScript and HTML are on the appliance, create a mechanism to use them.

Navigate to Browse Secure: Access Control > Authentication and select the Mechanisms tab. On this tab, create a new instance of the Info Map Mechanism.

create new instance
create new instance

Specify a name (FacebookInfoMap), identifier suffix (facebook), and description for the mechanism on the General tab.

new authentication mechanism
new authentication mechanism

On the Properties tab, select the Mapping Rule that was uploaded in the previous step and provide the path for the HTML template.

Mapping Rule: FacebookInfoMap

Template Page: /authsvc/authenticator/facebook/facebook.html


Save and deploy the changes before continuing.


Create the authentication policy

Now that you created the required Facebook mechanism, you can create an authentication policy to make use of this mechanism.

An authentication policy is a linear, ordered list of authentication mechanisms that must be completed for the policy to be satisfied. In this scenario, there is only a single mechanism in the policy.

Return to the Policies tab and create a new policy. Provide a name (Facebook Authentication), identifier suffix (facebook), and a description for the policy. The identifier is used in the URL, which invokes the policy. In the Workflow Steps, add a new step and select the FacebookInfoMap mechanism that was created in the previous step.

create a new policy
create a new policy

Save and deploy the changes before continuing.


Trust the Facebook CA certificates

The mapping rule will communicate with Facebook over HTTPS during the OAuth 2.0 authorization code flow. For this reason, the runtime must trust Facebook's signing certificate.

The recommended approach is to upload the signing certificate chain for the SSL endpoint. At the time of publishing this article, the Facebook server's certificate was issued by DigiCert, and we have provided the intermediate and root CA certs as part of the files, Resources for Facebook, Resources for Instagram, and Resources for LinkedIn.

Navigate to Manage: System Settings > SSL Certificates.

Select rt_profile_keys and then navigate to Manage > Edit SSL Certificate Database.

Import both the Digicert SHA2 High Assurance Server CA and the DigiCert High Assurance EV Root CA.

import digicerts
import digicerts

Save and deploy the changes.


Set the Point of Contact profile

Facebook users, as identified by their Facebook unique ID, will not exist in the ISAM user registry. Attempts to establish an ISAM session by using the Facebook unique ID as a username will result in a "Could not acquire a client credential" error.

You can configure ISAM to allow authentication and session establishment for asserted users that do not exist in the user registry by way of changing the point of contact profile.

Browse to Secure: Access Control > Point of Contact.

Select the Access Manager Credential profile and click Set As Current.

authentication for asserted users
authentication for asserted users

Configure WebSEAL

To allow the FacebookInfoMap mechanism to maintain state information during the authentication process, you need to update the Reverse Proxy instance configuration so that it will establish and maintain sessions for unauthenticated users.

Two entries need to be changed in the WebSEAL configuration file:

[server]force-tag-value-prefix = no

[session]create-unauth-sessions = yes

Browse to Secure: Web Settings > Reverse Proxy.

Select your instance and navigate to Manage > Configuration > Edit Configuration File.

Update or verify the values for force-tag-value-prefix and create-unauth-sessions. Save and deploy the changes, then restart the Revese Proxy instance as prompted.

edit config file
edit config file
create unauth sessions
create unauth sessions

You must also modify the junction to the authentication service (typically /mga to indicate that the session_index property is added to each request as a HTTP header. Use the ISAM admin tool to set a HTTP-Tag-Value attribute on the junction:

pdadmin> object modify /WebSEAL/localhost-default/mga setattribute HTTP-Tag-Value tagvalue_session_index=session_index

Note that your object space name (the localhost-default portion) will change depending on the instance name and appliance hostname. The following command can determine the correct hostname/instance name:

pdadmin> object list /WebSEAL

To access the ISAM admin tool, SSH to the appliance as the admin user and enter the command isam admin.

isam admin
isam admin

Testing Facebook Login

The AAC policy identifier suffix created in this tutorial was facebook, which resulted in a complete policy URN of urn:ibm:security:authentication:asf:facebook.

Individual authentication policies can be invoked by URL. To access the facebook policy, use the following URL:

When correctly configured, you will see a Login with Facebook button.

correct login page
correct login page

Clicking the link will take you to the Facebook login page. If your browser is already logged in to Facebook, you might see the consent page pop up.

fb login page
fb login page

If this is the first time the Facebook account is used with this instance of Facebook Login, you'll see a consent page. If you prefer, you can reconfigure the Facebook Login instance to require consent on each login attempt. This configuration option is located under the Facebook Login configuration on

facebook login configuration
facebook login configuration

Once the user is authenticated with Facebook and is authorized the login, the user will be returned to ISAM and an authenticated session is established.

isam fb successful login
isam fb successful login

To verify the properties in the credentials, use a mechanism like the mobile demo app to display them. The mobile demo app can be found at:

mobile demo app
mobile demo app

The user's firstName, lastName, and email is populated with details that are retrieved from Facebook. The principal name is the URL of the Facebook profile.



Check the redirect URI

Facebook requires an exact match on redirect URI and will throw an error if incorrect. Verify that the URI is correct and update your application settings on if necessary.


Monitoring Traffic Between the Runtime and Facebook

Trace can be used to debug the authentication service and the HTTP requests that are being sent to Facebook via Add the following trace to the runtime profile:**=ALL


Network connectivity

The appliance must be able to resolve and contact the host This can be tested with the nslookup utility, which is provided on the admin command line:

Isam-demo> tools nslookup
Address 1:

Address 1:
Address 2: 2a03:2880:f002:109:face:b00c:0:2

Debugging EAI Authentication

If the flow appears to be successful, but the user is not being authenticated, check that EAI authentication has been correctly configured.

Check the EAI trigger URLs, and that eai-auth is enabled in the WebSEAL instance's configuration:

eai-auth = https 
trigger = /mga/sps/authsvc* 
trigger = /mga/sps/auth* 
trigger = /mga/sps/authservice/authentication*

Monitoring Traffic Between WebSEAL and the Runtime

If all appears correct, the WebSEAL trace component pdweb.snoop.jct can be used to see the request/response headers between the runtime and WebSEAL.

Set pdweb.snoop.jct trace in the ISAM admin tool with the command:

server task <instance> trace set pdweb.snoop.jct 9 file path=pdweb.snoop.jct.log

Next Steps

Facebook Login with account linking

One obvious evolution of this concept is to add the ability to link and unlink ISAM user accounts with Facebook accounts. A second mapping rule is provided in the Resources section that provides linking functionality. Simply replace the contents of facebook.js on the appliance with the provided file facebook-account-linking.js, while being sure to update the App ID/App Secret/redirect URL in facebook-account-linking.js first.

The new mapping rule with linking capabilities operates in the following manner:

  1. If the user session is currently unauthenticated, and the Facebook login is for a user that we previously linked, you are logged in as the linked user.
  2. If the user session is currently unauthenticated, and the Facebook login is for a user we have NOT previously linked, an error will occur: "Unlinked Facebook account." This would be a good location to implement just-in-time provisioning.
  3. If the user session is already authenticated and the Facebook login is for a user we have previously linked, authentication will work only if the user currently logged in is the same as the one that was previously linked. Otherwise, an error will occur: "Facebook account linked to a different user."
  4. If the user session is already authenticated and the Facebook login is for a user we have NOT previously linked, the Facebook account will be linked to the current user.

To unlink a previously linked user, log in as that user and then access the authentication policy URL with the extra query string parameter unlink=true.

Other Identity Providers: LinkedIn and Instagram

The core logic that is required to communicate with Facebook is a rudimentary OAuth 2.0 client, implemented within an easily customized JavaScript mapping rule. As a result, this same pattern can be applied to provide login capabilities with other identity providers implementing similar OAuth 2.0-based login patterns.

Due to high demand, we produced assets for LinkedIn and Instagram. Click the buttons below to grab the js files.

Resources for Instagram ( for LinkedIn (

Downloadable resources

Related topics


Sign in or register to add and subscribe to comments.

ArticleTitle=Integrate an application with Facebook Login for Apps