1 Introduction

Introduction

Sources: https://github.com/splix/grails-spring-security-facebook

Requirements:

• grails 2.4
• spring-security-core plugin 2.0-RC4

Examples:

• https://github.com/splix/grails-facebook-authentication-example - Example app

Support

• if you found a bug - please submit it into GitHub Issues

2 Intallation

2.1 Installation

Install plugin

Basically it's just adding dependency into `BuildConfig.groovy`:

plugins {
    compile ">>
}

Or, if you're using a new Spring Security Core 2.x, you have to use following dependency instead:

plugins {
    compile ">>
}

and calling (optional) configuration wizards by:

grails s2-quickstart //configure Spring Security Core
grails s2-init-facebook //configure Spring Security Facebook

Or you can edit `Config.groovy` instead, see Configuration section.

Follow Basic Usage guide for next steps.

2.2 Upgrade Notice

Upgrading from version 0.9

Since version 0.10 plugin have started to use Server Side authentication by default, instead of Client Side authentication (based on Facebook JS SDK) that was default implementation for version 0.9 and earlier.

If you want to continue using Client Side authentication, you should add following configuration into Config.groovy:

grails.plugin.springsecurity.facebook.filter.type='transparent,cookieDirect'

Upgrading from version 0.15.x

Version 0.16 requires a Spring Security Core 2.0, you need to upgrade to it first.

See Filters guide for details.

3 Usage

3.1 Basic Usage

Example app

You can take a look at Example Application, it's very basic app, that have only one page, with 'Facebook Connect' button. Just clone it, put your FB App credentials, and play with it.

How to add Facebook Authentication into your existing application

Initial plugin config

Domain Class

Create domain class for your facebook user:

class FacebookUser {
  Long uid
  String accessToken
  Date accessTokenExpires
  static belongsTo = [user: User] //connected to main Spring Security domain
  static constraints = {
    uid unique: true
  }
}

At Config.groovy setup full name (including package name, if used) of just created Facebook user domain, like:

grails.plugin.springsecurity.facebook.domain.classname='FacebookUser'

Add FB App credentials

You should create a Facebook App and copy App ID and Secret:

into Config.groovy:

grails.plugin.springsecurity.facebook.appId=12345678900000
grails.plugin.springsecurity.facebook.secret=76c2279743c99da3715e3d00f29a1234

PS it's just example, you should use your own `appId` and `secret`.

Add Facebook Connect button

There is special taglib (<facebookAuth:) that can be used at your view (any GSP page) to add Facebook Connect button.

Following code displays connect button for not authorized user, or show a welcome message to logged in user:

<sec:ifNotGranted roles="ROLE_USER">
  <facebookAuth:connect />
</sec:ifNotGranted>
<sec:ifAllGranted roles="ROLE_USER">
  Welcome <sec:username/>! (<g:link uri="/j_spring_security_logout">Logout</g:link>)
</sec:ifAllGranted>

Run

That's it! Run your application, and test that everything is working.

3.2 Filters

How it works

Plugin is based on Spring Security and uses web filters for authorization, for more details see Spring Security docs

Available filters

There are 4 types of filter:

• FacebookAuthRedirectFilter - server-side authorization (used by default)
• FacebookAuthCookieTransparentFilter - automatic client-side authorization
• FacebookAuthCookieDirectFilter - manual client-side authorization
• FacebookAuthJsonFilter - for external clients (like Android/iOS app)

Server-Side authentication (FacebookAuthRedirectFilter)

It's a standard Login for Server-side Apps. After clicking on 'connect button' user gets redirected to special Facebook page, for authentication, and then redirected back to your app.

Client-Side authentication

Transparent cookie based authorization (FacebookAuthCookieTransparentFilter)

Based on Facebook Javascript SDK authorization. On client side it makes Facebook authorization and put Facebook Cookie (it's made by Facebook Javascript, you don't need anything special)

After successful authorization on client side, the browser should reload current page. Or open any other page.

This filter will process each request, and if it sees valid Facebook cookie, it makes authorization for current user. If it's a new user, it creates a new one for application, with provided Facebook credentials.

It's per-request authorization. That means that this filter will try to authorize user on each page request.

Manual cookie based authentication (FacebookAuthCookieDirectFilter)

Based on Facebook Javascript SDK authorization. On client side it makes Facebook authorization and put Facebook Cookie (it's made by Facebook Javascript, you don't need anything special)

Same as FacebookAuthCookieTransparentFilter, it parse Facebook cookie, but only for specified url. Like username/password filter from spring-security-core or similar. After successful authorization it can redirect user to specified url.

JSON or Android/iOS/desktop authorization (FacebookAuthJsonFilter)

Client should send Access Token or Signed Request as parameter, and will get JSON response with user details.

See filter docs

Filter configuration

You can use config parameter grails.plugin.springsecurity.facebook.filter.type to configure which filters you want to use in your application.

It's not a Spring Security configuration, not a configuration for Spring filters. Just a extra configuration, that used only by this plugin.

By default it uses only one 'redirect' filter:

grails.plugin.springsecurity.facebook.filter.type='redirect'

You can use more that one filter at same time:

grails.plugin.springsecurity.facebook.filter.type='transparent,cookieDirect'

Value types:

• redirect - use standard server side authorization
• transparent - use transparent cookie based authorization
• cookieDirect - use manual cookie based authorization
• json - use JSON authorization

3.3 Server Side Authentication

It's preferred and a standard Login for Server-side Apps. After clicking on 'connect button' user gets redirected to special Facebook page, for authentication, and then redirected back to your app.

User going to see Facebook Authentication screen only at the first time. Next time user will be redirected back from Facebook to your application immediately.

How to process failed login

When user declines Facebook Authentication (click Cancel, for example), you'll '401 Authentication Failed' by default. It's default configuration of Spring Security failure handler, but for most cases it's not what you really want.

To handle this situation you have to create your own Failure Handler, a bean implementing org.springframework.security.web.authentication.AuthenticationFailureHandler. If you just need to show a page (a GSP view), you can use standard SimpleUrlAuthenticationFailureHandler, that could redirect failed authentication to specified URL.

For example you can create bean at resources.groovy:

import org.springframework.security.web.authentication.SimpleUrlAuthenticationFailureHandler
// Place your Spring DSL code here
beans = {
    redirectFailureHandlerExample(SimpleUrlAuthenticationFailureHandler) {
        defaultFailureUrl = '/failed' //redirect to this URL when authentication fails
    }
}

and setup this bean for 'redirect' filter at Config.groovy:

grails.plugin.springsecurity.facebook.filter.redirect.failureHandler='redirectFailureHandlerExample'

Same way for configuring Success Handler.

3.4 Client Side Authentication

And there are two ways:

• try authenticate user on each request, to any page - it's transparent filter
• authenticate only when user redirected to specified page, like a standard username/password authentication - it's cookieDirect filter

Transparent filter

If you're using first way (transparent filter), your user will be automatically authenticated whenever he has Facebook cookie. Btw, don't forget that you should reload current page after you have successfully authenticated user on client side. Like:

<facebookAuth:init>
   FB.Event.subscribe('auth.login', function() {
      window.location.reload();
   });
</facebookAuth:init>

To logout user, simply call FB.logout() (using Javascript) on client side.

CookieDirect filter

If you're using second way (cookieDirect filter), you could configure URL that will be used for authentication at Config.groovy:

grails.plugin.springsecurity.facebook.filter.processUrl = '/j_spring_security_facebook_check' //it's default value

And after authorization redirect user to /j_spring_security_facebook_check, like:

<facebookAuth:init>
   FB.Event.subscribe('auth.login', function() {
      window.location.href = '/j_spring_security_facebook_check'
   });
</facebookAuth:init>
<g:javascript>
   $('#fbloginbutton').click(function() {
       FB.login();
   });
</g:javascript>

3.5 Json Authentication

JSON filter just returns an object with user details, nothing else. For authentication of other requests, you still have to use different filter. If you have a RESTful client, take a look at spring-security-oauth2-provider plugin

How it works:

> GET /j_spring_security_facebook_json?access_token=<ACCESS_TOKEN>

For successful authorization you'll get:

< HTTP/1.1 200 OK
< Content-Type: application/json;charset=UTF-8
<
{
  "authenticated": true,
  "uid": 12345612345,   # Facebook User Id
  "roles":[
     "ROLE_FACEBOOK",
     "ROLE_USER"
  ],
  "username": "facebook_12345612345", # Grails Application User Id/Username
  "enabled": true # Grails Application User status
}

For unsuccessful:

< HTTP/1.1 401 Unauthorized
< Content-Type: application/json;charset=UTF-8
<
{
  "authenticated": false,
  "message": "Expired token" # Authentication Failure reason
}

How to extend JSON response

The plugin going to call Map onJsonSuccess(Map input, FacebookAuthToken token) or Map onJsonFailure(Map input, AuthenticationException exception) methods of FacebookAuthService (if exists).

There you can update input data with any other values, introduce new fields/keys, or even return your own structure. This structure will be transformed to JSON and sent to client.

Configuration

See authentication configuration page

4 Configuration

Basic Configuration

Make sure that you have installed and configured spring-security-core plugin before this step.

Calling `grails s2-init-facebook` will make default configuration of plugin for you, make sure that you have configuration in your `Config.groovy` like:

grails.plugin.springsecurity.facebook.domain.classname='<your FacebookUser domain>'
grails.plugin.springsecurity.facebook.secret = '<Facebook secret for your app>'
grails.plugin.springsecurity.facebook.appId = '<Facebooks's app ID>'

Or you can skip `grails s2-init-facebook` step, and make such configuration by yourself.

When you have valid configuration you can put Facebook Connect button in you GSP:

<facebookAuth:connect permissions="email,user_about_me"/>

You don't need to add anything else.

4.1 Facebook App Config

For a list of all possible permissions see https://developers.facebook.com/docs/reference/login/#permissions

4.2 Domains

• domain.classname - name of your domain class, used to store Facebook User details (uid, access_token, etc). Could be same as configured for Spring Security Core, or a own domain, just for Facebook User details.

If you're using own domain for Facebook user (a joined to main User) you should specify domain.appUserConnectionPropertyName: it's how your domain class is related to main (used by Spring Security Core) user domain. It's the name of the property, usually defined as static belongsTo = user: User in your Facebook User domain class.

User creation/initialization

List of roles for user created by the plugin.

4.3 Login Button

Button configuration

Button for Server Side authentication (default)

Standard <img … /> will be used for button, with following extra configuration options:

• img - url of a default image to use for button

Button for Client Side authentication

At this case a HTML button, provided by Facebook JS SDK, will be user.

• language - language for Facebook Javascript SDK. You could also pass this option as a lang attribute for :connect or :init tags

4.4 Plugin Internals

• autoCreate.enabled - enable/disabled automatic creation of Application User for a new Facebook user (when FB user first time authenticates)
• autoCreate.roles - list of roles to set to a newly created user (if enabled)

Set a hostname of current app, could be used when user logged out, but FB didn't clear all cookies for domain. Note: it's host name, not url. Like `example.com`

4.5 Authentication Types

• type - type of authentication, can be transparent, cookieDirect, redirect or json.

You can specify list of filters as a list 'redirect', 'json' or comma-separated string:

grails.plugin.springsecurity.facebook.filter.type='redirect,json'

Configuration for REDIRECT filter

• redirectFromUrl - it's the url that will redirect user to special Facebook Authentication URL. You can put link to/redirect user to redirectFromUrl when you want to use Facebook authentication. This url is used by default <facebook:connect /> button.
• if filter.redirect.processUrl is not then, then default filter.processUrl will be used
• failureHandler - a name of the bean that implements AuthenticationFailureHandler
• successHandler - a name of the bean that implements AuthenticationSuccessHandler

Configuration for TRANSPARENT filter

NA

Configuration for COOKIEDIRECT filter

• if filter.cookieDirect.processUrl is not set, then default filter.processUrl will be used
• failureHandler - a name of the bean that implements AuthenticationFailureHandler
• successHandler - a name of the bean that implements AuthenticationSuccessHandler

Configuration for JSON filter

• type could be json (default) or jsonp
• methods - allowed HTTP methods. Notice that it's used only for JSON, for JSONP it will be forced to 'GET'

5 Customization

5.1 Using FacebookAuthService

How it works

If you need to add some specific logic to default plugin behaviour you have to create your own service called `FacebookAuthService`. Plugin will check for know methods of this service, and if they're exist - use them instead of own.

It's some kind of extending an abstract class. You don't need to create all methods, just what you need.

Used objects:

• <FacebookUser> - domain class for your facebook user. It's your own class, can have other name, it's just a example
• <Person> - general user, used by Spring Security. It's your own class, can have other name, it's just a example
• FacebookAuthToken - token provided by plugin

<FacebookUser> and <Person> can be same object, or can be two different object (with a relation), depends on your architecture.

Take a look at sources

Please, take a look at sources of DefaultFacebookAuthDao to understand how it works, and which methods you can use for customization

List of possible methods:

void onCreate(<FacebookUser> user, FacebookAuthToken token)

Called after user was created by plugin, just before saving into database. You can fill user object with some extra values.

Not called if you have implemented method create(..)

Where:

• user - your domain for Facebook User
• token - com.the6hours.grails.springsecurity.facebook.FacebookAuthToken

void afterCreate(<FacebookUser> user, FacebookAuthToken token)

Called after user was created by plugin, and when it's already saved into database.

Not called if you have implemented method create(..)

Where:

• user - your domain for Facebook User
• token - com.the6hours.grails.springsecurity.facebook.FacebookAuthToken

<FacebookUser> findUser(long uid)

Called when facebook user is authenticated (on every request), must return existing instance for specified facebook uid, if exits. If doesn't - return null

Where:

• uid - facebook user id

<FacebookUser> create(FacebookAuthToken token)

Called when we have a new facebook user, called on first login to create all required data structures.

Where:

• token - com.the6hours.grails.springsecurity.facebook.FacebookAuthToken

Notice, that if you have such method, all other method for user creation will no be called:

• createAppUser
• prepopulateAppUser
• onCreate
• afterCreate
• createRoles

<Person> createAppUser(<FacebookUser> user, FacebookAuthToken token)

Called when we have a new facebook user, called on first login to create main app User domain (when we store Facebook User details in different domain).

Not called if you have implemented method create(..)

Where:

• user - your domain for Facebook User
• token - com.the6hours.grails.springsecurity.facebook.FacebookAuthToken

void createRoles(<FacebookUser> user)

Called when we have a new facebook user, called on first login to create roles list for new user

Where:

• user - your domain for Facebook User

def getPrincipal(<FacebookUser> user)

Must return object to store in security context for specified facebook user (can return itself)

Where:

• user - your domain for Facebook User

<FacebookUser> getFacebookUser(<Person> person)

Must return instance of your domain object for facebook user for specified person (if it's not a same object)

Where:

• person - your domain for <Person>

Collection<GrantedAuthority> getRoles(<Person> user)

Must return roles list for specified user

Where:

• user - your domain for Facebook User

void prepopulateAppUser(<Person> person, FacebookAuthToken token)

Must return roles list for specified facebook user

Where:

• person - your domain for <Person>
• token - com.the6hours.grails.springsecurity.facebook.FacebookAuthToken

How to use

6 Common Issues

Please enable logging

If you have troubles with plugin, please enabled logging, so you can see what's happening:

log4j = {
  debug 'com.the6hours', 'grails.app.taglib.com.the6hours'
}

Client side authentication don't work on dev server

Make sure that you're using a real domain name for your application. Not a localhost, because Facebook can't setup cookie for localhost, and avoid .local domains as well.

You can make a fake domain like myapp.dev, by putting into /etc/hosts the following line:

127.0.0.1  myapp.dev

See more details about hosts file, and location of the file for different operation systems see: http://en.wikipedia.org/wiki/Hosts_(file)

After that, you should configure your Grails app to use this domain, by adding following line into Config.groovy:

grails.serverURL = "http://myapp.dev:8080/${appName}"

Of course, you need to use this domain only for development, so put this configuration into development environment config:

environments {
    development {
      grails.serverURL = "http://myapp.dev:8080/${appName}"
    }
}

Logout doesn't work for Transparent filter

"transparent" filter always authorize request that contains FB cookie. If you need to log out current user when using this type of filter, you need to log out user on client side, call FB.logout() (will logout user from Facebook as well) and reload the page.