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.
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:
- A Facebook account that will be used to register a Facebook Application.
- ISAM 9.0.2 or greater.
- Activated Base and Advanced Access Control offerings.
- Appliance network connectivity to https://graph.facebook.com.
- A configured Reverse Proxy instance, set up for use with the AAC and
the AuthSvc (via
isam aac configor equivalent).
- Enabled ISAM demo application (suggested for testing)
You will need to set up your Facebook account by using the Facebook Login product. At a high level, these steps are:
- Enroll on the Facebook for Developers site.
- Create a new Facebook Login application.
- Configure the Facebook Login application with the correct redirect URI to your Reverse Proxy instance.
- 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 https://developers.facebook.com. 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.
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.
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
mywebseal.com is the address of the Reverse Proxy and
/mga is the path of the AAC junction.
/mga is the default path configured when using the AAC
Complete the redirect URI configuration as shown in the following image.
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.
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.
To configure the ISAM authentication service for Facebook Login, you need to create a new authentication mechanism and policy.
At a high level, the steps to set up ISAM are:
- Create a new authentication policy that contains the new InfoMap mechanism instance.
- Configure ISAM to allow users that do not exist in the user registry to be able to log in.
- Ensure that Facebook is accessible from the Appliance and that the AAC runtime trusts the signer CA's of Facebook's https://graph.facebook.com endpoint.
- Update the Reverse Proxy instance to pass some additional information to the Advanced Access Control Runtime.
There are two files that are used by the InfoMap mechanism:
- An HTML template page that is used to initiate the login process in the web browser.
the authentication service URL and Facebook Login App ID/Secret. Open the
facebook.js in a text editor and update the values
// Parameters you need to update - the appID and appSecret come from your Facebook application // and the redirectHostAndJunction depends on your ISAM configuration. var appID = "xxxx"; var appSecret = "yyyy"; var redirectHostAndJunction = "https://www.mywebseal.com/mga";
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.
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
Configure the InfoMap authentication mechanism
Navigate to Browse Secure: Access Control > Authentication and select the Mechanisms tab. On this tab, create a new instance of the Info Map Mechanism.
Specify a name (FacebookInfoMap), identifier suffix (facebook), and description for the mechanism on the General tab.
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.
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
graph.facebook.com 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
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.
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.
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:
force-tag-value-prefix = no
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
create-unauth-sessions. Save and deploy the changes, then
restart the Revese Proxy instance as prompted.
You must also modify the junction to the authentication service (typically
/mga to indicate that the
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
Testing Facebook Login
The AAC policy identifier suffix created in this tutorial was
Individual authentication policies can be invoked by URL. To access the
When correctly configured, you will see a Login with Facebook button.
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.
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 developers.facebook.com.
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.
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: https://mywebseal.com/mga/mobile-demo/diag/.
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 developers.facebook.com 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 https://graph.facebook.com. Add the following trace to the
The appliance must be able to resolve and contact the host graph.facebook.com. This can be tested
nslookup utility, which is provided on the admin
Isam-demo> tools nslookup graph.facebook.com Server: 184.108.40.206 Address 1: 220.127.116.11 google-public-dns-a.google.com Name: graph.facebook.com Address 1: 18.104.22.168 edge-star-shv-01-hkg3.facebook.com Address 2: 2a03:2880:f002:109:face:b00c:0:2 edge-star6-shv-01-hkg3.facebook.com
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] eai-auth = https [eai-trigger-urls] 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.
pdweb.snoop.jct trace in the ISAM admin tool with the
server task <instance> trace set pdweb.snoop.jct 9 file path=pdweb.snoop.jct.log
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:
- 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.
- 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.
- 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."
- 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
Other Identity Providers: LinkedIn and Instagram
Due to high demand, we produced assets for LinkedIn and Instagram. Click the buttons below to grab the js files.