Table of contents

Created

28 April 2014

Requirements
 
Prerequisite knowledge
Knowledge of ColdFusion programming and OAUTH2
 
User level
All
 
 
 
Required products
Adobe ColdFusion Enterprise Edition (2016 release) (Download trial)
 
Note: If you have questions about this article, use the DPS forum. Please don’t contact technical support with questions about Adobe Developer Connection articles.

 
Introduction

In this article, I will describe how you can integrate third-party OAUTH2 authentication providers and various social plugins in your ColdFusion application.
 

 
CFOAUTH

The <oauth> tag allows you to easily integrate third-party Oauth 2 authentication provider in your application.
 
This ColdFusion tag currently supports Facebook and Google authentication. Also, this tag supports Oauth providers that support the Oauth 2 protocols. For instance, Microsoft and Github.
 
 
Why OAuth
  1. Web sites need not implement login/registration framework on their own.
  2. It is a secure process and hence users visiting your site need not expose their credentials to 3rd party apps/websites, which are not so reliable.
  3. Users need not remember different credentials for different web sites.
  4. Users need not fill long registration forms as all the basic information about the users will be fetched from the Oauth providers.
  5. Most of the users will have their account in atleast one of the OAauth providers like facebook or Gmail.
 
Some facts about OAuth
  1. Most websites now have 'Login Via Facebook' option.
  2. Facebook, Twitter, and Google Plus are the biggest OAuth servers right now.
  3. OAuth1 has been deprecated and everyone is moving to OAuth2.
ColdFusion Syntax
 
<cfoauth type = "" clientid = "" scope = "" state = "" authendpoint = "" secretkey = "" accesstokenendpoint = "" result = "" redirecturi = "" urlparams = "" >
  • type can be either ‘google’ or ‘facebook’.
  • clientid and secretKey are Unique ID and app secret generated while registering your application with the Oauth provider.
  • Authendpoint and accesstokenendpoint are end point URLs to be invoked for user authentication and app authentication in case type is not specified For instance, if the OAUTH provider is other than facebook or google.
  • Redirecturi is the URI where the user will be redirected once user authentication is done.
 
Understanding the ‘scope’ parameter
Scopes are the permissions that a developer seeks from the users. These are usually comma-separated values of permissions. Refer to the Oauth provider's documentations for more information.
 
For example, after the Facebook authentication, if you want to access the email addresses and then the friends list of a user, you will use:
 
scope=email,read_friendlists.
 
The OAuth provider’s popup will inform the user about all the permissions that the app is requesting:
 
1
 
Understanding the ‘state’ attribute
The state variable is used to pass back any information to your web application after the authentication and redirection are completed. Any value passed to this attribute is returned to the web application after authentication.
 
For example, if you have state=’somevalue’ and redirect_uri=’mydomain’, once the user authentication is done,  Oauth provider will redirect to this URI:
 
Mydomain?state=somevalue&accesstoken=……
So the request scope will have this parameter’s value.
 
 
Understanding the flow
  • Once the user clicks the client site login button, the user will be prompted with a popup to grant the permissions.
  • If the user is not logged into the client site, he will be prompted to login.
  • If the user has already authorized your app and has already granted the permissions requested in the scope, he will be immediately redirected to your redirect_uri.
 
Example:
Let the file name be fblogin.cfm.
 
<cfoauth type="facebook" clientid='1836864883*****' secretkey="ac3dfa5aaddc6e7425**********" state="fb" result="r" scope="read_stream,user_location,user_work_history,publish_stream,email" redirecturi="http://localhost:8500/social/facebook/fblogin.cfm"> <cfset Session.fbinfo = #r#> <cflocation url = "oauth.cfm">
Here the result attribute will be a struct which will have login info of the user including the login success/failure, failure reason, user name, and userid. We are keeping this variable into the session scope so that it can be accessed in the same session in other pages. And in the end, we redirect the request to oauth.cfm. This file can have the following code:
 
<cfif isdefined('Session.fbinfo')> <cfset rr = Session.fbinfo> <cfoutput> <b>Facebook Login - Welcome, here is your basic info</b></br> <img class="imageswrapper" width="100" height="100" src = "http://graph.facebook.com/ #rr.id#/picture"/></br> <span class="label">Name</span> : <b>#rr.name#</b></br> <span class="label">Gender</span> : <b>#rr.gender#</b></br> <span class="label">Locale </span>: <b>#rr.locale#</b></br> <span class="label">Facebook Id </span> : <b>#rr.id#</b></br> <span class="label">Email </span> : <b>#rr.other.email#</b></br> <span class="label">Home town</span> : <b>#rr.other.location.name#</b></br> <span class="label">Work</span> : <b>#rr.other.work[1].employer.name#</b></br> <span class="label">Access Token </span>: <b>#Left(rr.access_token,15)#</b> </cfoutput> </cfif>
So, we will first check if the session has the user’s information. If present, it fetches the basic information about the user and displays it.
 
<cfif (not isdefined('Session.fbinfo'))> <div class="commentbox" style="height:80"> <input type="button" value="Login with Facebook" onclick="window.top.location='fblogin.cfm'" style="cursor: pointer;" class="button blue morph"> </cfif>
Obviously, if the session does not have that the information, show the facebook login button.
 
 
How to invalidate the access token
Once the user logs out, it becomes the esponsibility of the website to kill any access token present in the session. ColdFusion exposes the utility function to do so:
 
InvalidateOauthAccesstoken(String token, String type)
‘Type’ can be either google or facebook.
 
 
How to check if access token is valid or not
Sometimes user might revoke the app permissions which will invalidate the old accesstoken which the app/website will be using. ColdFusion exposes a utility function to check the validity of the access token:
 
IsValidOauthAccesstoken (String token, String type)
‘Type’ can be either google or facebook.
 
 
What if our OAuth provider is other then Facebook or Google
Our implementation supports any OAuth2 provider but if it is other than Facebook or Google, users themselves need to provide the endpoint URLs.
 
In this scenario, do not provide any ‘type’. Just specify  the authendpoint and accesstokenendpoint.
 
<cfoauth clientid = "" scope = "" state = "" authendpoint = "http://github/....." secretkey = "" accesstokenendpoint = "http://github/....." result = "" redirecturi = "" urlparams = "" >
 
Can we go beyond login and make social apps
Surely you can. Our implementation will give you the access token. But once you have this token you can query anything from the OAuth provider depending on the scope you had given initially.
 
Let's explore the facebook’s graph API.
 
 
Example 1:
If you want to fetch email and birthday of the given user, you need to hit this graph API endpoint along with the access token which you would have already generated following the previously mentioned steps.
 
Response will be like this:
 
{ "id": "611784347", "name": "Uday Ogra", "birthday": "08/27/1985", "email": "udayogra\u0040gmail.com" }
 
Example 2:
If you want to fetch all the Facebook pages for which the current user is an administratoror, access this URL.
 
Here, we are executing the FQL query select page_id from page_admin where uid = me().
 
Response will be like this:
 
{ "data": [ { "page_id": "1486787401546371" }, { "page_id": "427500974042115" }, { "page_id": "172747212912289" }, . . . . }
So once we have this access token , we can build any application by hitting the APIs exposed by the OAuth providers.
 
 
How to generate the clientid and secretKey
Each provider will have its own procedure. For Facebook.
 
  1. Go to https://developers.facebook.com/.
  2. Click on Apps > Create a New App.
2
  1. Give any name and unique namespace.
  2. Enter Canvas URL. Redirecturi should be part of this canvas URL. For the initial testing, keep it to localhost/YOURAPPNAME.
3
  1. At the top, you can find the clientid and secretkey of your app.
4

 
Social Plugins

These days, almost all the websites are using atleast one of these social plugins:
 
Like, CommentBox, Live Stream, Tweet, PlusOne, Send, Subscribe, ActivityFeed etc.
 
We have implemented custom tags to create these social plugins.
 
Benefits of ColdFusion’s implementation:
 
  1. Reaching vast segment of audience.
  2. User need not manually generate them.
  3. Code will become clean and readable (generated code is very verbose).
ColdFusion has introduced the support for dynamically generating Like button, Tweet button, and Comment  box for social media sites. The supported widgets are:
 
  1. Like button
  2. Tweet button
  3. Facebook comment box
  4. Google Plus button
  5. Facebook subscribe button
  6. Like box
  7. Activity feed
  8. Follow
Minimum syntax would be like this:
 
<cf_socialplugin type = ‘like’>
Behind the scene, it would generate a verbose code like this:
 
<iframe src="//www.facebook.com/plugins/like.php?href=https%3A%2F%2FDOMAINNAME&amp;width&amp;layout=standard&amp;action=like&amp;show_faces=true&amp;share=true&amp;height=80&amp;appId=152892348232778" scrolling="no" frameborder="0" style="border:none; overflow:hidden; height:80px;" allowTransparency="true"></iframe>
All possible settings can be passed to this syntax.
 
For example, here is the syntax for implementing the Tweet button:
 
<cf_socialplugin type = "tweet" url = "url to share" tweettext = "default tweet text" language = "en|fr|.........." count = "none|vertical|horizontal" hashtag = "comma separated hash tags appended to tweet text" buttonsize = "small|large" via = "" recommend = "" style = "" extraoptions = "" >

 
Where to go from here

This tutorial described the ways to integrate the social logins and plugins in your websites/apps using ColdFusion 11. It has become absolutely necessary for all the web sites to do the social integration.
 
You can read more about the Facebook social plugins here: https://developers.facebook.com/docs/plugins/.