While much has been written on the pros and cons of single sign on, at some point every MODX developer will probably be asked to implement Facebook login on a MODX site. Now with my fbLogin extra, you can get it done with minimal effort.
I have to start this article with an admission; I am not Facebook's greatest fan. Over the years I have watched as they erode the cconcept of user privacy, releasing feature apon feature which, in some cases, seriously impact their users' privacy, only to quickly roll back to a less extreme though advanced position when forced to by privacy advocates. It is now clear to me that Facebook is proactively pushing a culture of 'sharing' while the privacy rights of individuals are progressively eroded - and all this to what end? Yet I run a site msyelf, Lost & Found Pets Ireland, which relies heavily on the facilities and audience Facebook brings for its success - the irony is not lost on me.
Whatever your personal position on the rise of the 'sharing' culture, I am pretty sure that any developer who has worked with the Facebook API will tell you that it is a somewhat less than pleasant experience. There are a couple of reasons for this:
The Facebook 'hacker' culture led to an original session & REST-based implementation of the API which was proprietory, badly documentated and less than robust. While they have now moved to an Open Graph OAuth-based API which is a big improvement, the changeover has been gradual and this process itself introduced a lot of confusion, particularly over continued use of sessions in the API and their impact in authentication and permission provisioning and then there are issues around versioning. A lot of the documentation and tutorial material online is not clearly labelled with version information. In addition, the Faebook developer forum was a lightly moderated mess clogged up with 'newbie' questions on issues that were relatively well documented - developer support has since moved to Stack Overflow and has improved but moderation could still be better IMHO. Add to all that the rapid pace of change in terms of what one can actually do with the API and you can see that working with the API can be a pretty frustrating experience.
When working with the Facebook API, it definitely helps somewhat to understand this historical shift from a session to token based system to make sense of the API when reviewing any sample code.
Versioning Heads Up
Basically, the goal of the fbLogin extra to allow site users to either register directly on our site using the regular MODX login system and subsequently sign in using their chosen credentials OR to create an account by clicking the 'Connect to Facebook' button, authorising the site app thereby allowing login using their Facebook-supplied credentials, simply clicking the 'Connect to Facebook' button again whenever they need to log in. Providing login via Facebook allows a site to leverage Facebook data and the API to provide enhanced site services. This form of Facebook integration was originally dubbed 'Facebook Connect' but is now simply known as 'Facebook for Websites'. As every app has its own requirements, I won't be going into how you might use the Facebook data a user supplies or how the permissions they grant may be utilised beyond brief mentions of possiblities. Due to the nature of what the extra does, it is not really aimed at designers but rather developers looking to accelerate their Facebook integrations.
Plese note first of all that this addon requires friendly URL's to be enabled and functional. It is assumed that you have successfully installed and configured the Login extra before installing this extra. You should, at a minimum, have set up a dedicated login page and a dedicated post-login page where logged in users are directed on successful login. The ID's of these resources will be required during fbLogin setup. Optionally, a resource can be set up to which new Facebook users are directed to on registration - you may want to use this option to have new user's complete their MODX user profile as soon as they register.
It is also assumed that a Facebook app has been set up using the Facebook Developer app and that you have made a note of their App ID and App Secret as assigned by Facebook.
In the simplest implementation, which I envisage most folk with use, after running the install and entering the required options, you will have a chunk (fbLinks), found in the fbLogin category, which is added to each page. It provides links allowing users to manage their site sign-in. Before a user logs in and when exisitng users are logged out, they see a link to a dedicated login page, a link to a dedicated registration page and a 'Connect with Facebook' button. The 'look & feel' can be adjusted via CSS or by duplicating the chunk, editing it and passing the new chunk name to the call to the fbLogin snippet using the fbLoginTpl paramter.
When a user is logged in they see one of two sets of links, depending on whether or not they are logged in via Facebook. Non-Facebook users see:
while users who have logged in via Facebook see:
The anchor and title text, the seperator character between the MODX login & signup links (a '|' in the example above), the separator character between those links and the 'Connct to Facebook' button ('/' above) can all be cusomised with various paramaters to the call to the fbLogin chunk.
By default, fbLogin just requests the 'email' permission. However, permissions are chosen during the installation of the extra by entering them in the appropriate field as a comma delimited list and stored in a system setting so you can easily add your own.
You can specify which usergroup(s) new Facebook signups are added to and even what role they get within those groups. This is done by entering a comma delimited list of usergroups in the appropriate field during setup, for instance:
where 'Facebookers' and 'Customers' are two usergroups we want the users added to and to specify the roles, you would do something like:
where 'Members' and 'FromFacebook' are two roles we have added to those groups which we want those users to have, i.e. append them to the usergroup names separated by a colon.
I should also note that if you enter usergroup names for non-existant groups, they will be automatically created for you, though you will of course have to configure them to associate them with resource groups etc.
Also in this implementation, when a user logs out, if they are registered & logged in via their Facebook credentials, they won't be logged out of Facebook, just the MODX site. This may be at odds with Facebook's own terms of service (I've seen mised optinions on this online but could not find any definitive policy documentation on it from Facebook themselves) but since this is how prominent sites such as Mashable have impmennted their versions, I'm going to roll with it as I think logging a user out of a thrid party site is pretty obnoxious.
Handling De-authorisation & OAuth Errors
During installation the extra adds a special resource hidden from the site tree which has an alias of 'fbd'. The URL, http://yourdomain/fbd needs to be added to the advanced section in your app settings in the Facebook Developer app so that Facebook can ping it when a user de-authorises your site. The installer places a nsippet in this page that basically captures and decodes these pings from Facebook, extracting the account ID of the user and matching that to the corresponding MODX account. It then deactivates that account. We don't want to delete the account as the user may change their mind in the future and we want to persist their associated data for that eventuality.
OAuth errors will arise if, while a user is logged in on your site, they change their password on Facebook, they log out of Facebook or their session expires - note can not happen if you have requested the offline_access permission. In any case, all these errors are gracefully handled by the extra by simply logging the user out when it encounters one of these situations. The user just simply needs to hit the 'Connect with Facebook' button agian to login - they may need to reconfirm their new password depending on how the situation arose.
Finally I should say that the fbLogin snippet outputs a number of useful placeholders when a user is logged in. Items like the user's full name, their first name, their profile pic, their email and their user ID are all accessible. Check the readme file for details.
fbLogin Repository Page
You can find the fbLogin extra for MODX Revolution (2.2+) here.
Developing the fbLogin extra has been a fun process made a lot easier by a great article by Edward A. Webb and the work of the core team at MODX.
The first use I know of - fbLogin in the wild - heavenlypath.info. If you are using it on a site, let me know via the comments below :)