1 Introduction

Requirements:

• grails 2.0+
• spring-security-core plugin 2.0-RC2

Links:

• Sources - https://github.com/splix/grails-spring-security-twitter
• Example app - https://github.com/splix/grails-twitter-authentication-example
• Submit a bug - GitHub Issues

2 Installation

Install plugin

Add dependency into `BuildConfig.groovy`:

plugins {
        compile "org.grails.plugins:spring-security-twitter:0.6"
        // …
        // you need to have spring-security-core plugin installed
        // …
    }

and put your Twitter API Consumer Key/Secret into Config.groovy:

grails.plugin.springsecurity.twitter.consumerKey= ..
grails.plugin.springsecurity.twitter.consumerSecret= ..

It's very basic configuration, for other options (see Configuration section)

Follow Basic Usage guide for full example.

Upgrading from versions prior to 0.5

Version 0.5 was completely rewritten, so you could expect some inconsistency after upgrade. Just follow this guide and Configuration section if you have any troubles.

Upgrading from versions prior to 0.6

Version 0.6 is based on Spring Security Core 2 plugin. Follow upgrade notes from http://grails-plugins.github.io/grails-spring-security-core/docs/manual/guide/newInV2.html

3 Usage

Example app

You can take a look at Example Application , it's very basic app, that shows how to use the plugin. Just clone it, put your Twitter App credentials, and play with the code.

Usage

Install plugin

Add dependencies into BuildConfig.groovy:

plugins {
    runtime "org.grails.plugins:resources:1.1.6"
    compile "org.grails.plugins:spring-security-core:2.0-RC2"
    compile "org.grails.plugins:spring-security-twitter:0.6"
}

Setup Twitter credentials

Put your Twitter API Consumer Key/Secret into Config.groovy:

grails.plugin.springsecurity.twitter.consumerKey=..
grails.plugin.springsecurity.twitter.consumerSecret=..

Create domain class for your user

Like domain/TwitterUser.groovy:

class TwitterUser  {
    /**
     * Twitter Username (notice that it could be modified by user, Twitter allows that)
     */
    String username
    /**
     * Twitter User Id
     */
    Long twitterId
    /**
     * Twitter API token
     */
    String token
    /**
     * Twitter API secret
     */
    String tokenSecret
    /**
     * Related to main App User
     */
    static belongsTo = [user: User]
    static constraints = {
        twitterId(unique: true, nullable: false)
        username(nullable: false, blank: false)
    }
}

The plugin is configured for TwitterUser class name by default. But you could use different name (or use package) for domain class, for example com.company.UserWithTwitter, that you should configure at Config.groovy at this case:

grails.plugin.springsecurity.twitter.domain.classname='com.company.UserWithTwitter'

Put SignIn with Twitter button:

Add into your GSP:

<twitterAuth:button />

Use Spring Security

Now you could use all security tools provided by Spring Security Core.

For example, you could use taglib for checking user state:

<sec:ifLoggedIn>
    <div class="message">Authenticated</div>
    Hello <sec:username/>!
</sec:ifLoggedIn>
<sec:ifNotLoggedIn>
    <div class="message">Not authenticated</div>
    <twitterAuth:button />
</sec:ifNotLoggedIn>

4 Configuration

Twitter configuration

Domain configuration

Where:

• .classname - domain class name that will be used for authentication
• .connectionPropertyName - name of property that connects (`belongsTo`) to main app user (if you have two different domains, one for app user, one for twitter user)

Authentication configuration

Where:

• .autoCreate.active - plugin will automatically create corresponding user for each new visitor authentication using Twitter
• .autoCreate.roles - default list of roles that will be assigned to create user
• .filter.processUrl - url that will be used for authentication

5 Using TwitterAuthService

How it works

If you want to add some specific logic to default plugin behaviour, you have to create your own service called `TwitterAuthService`. Then the plugin will check for known methods of this service, and if they're exist - use them instead of or in additional to own method.

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

Used objects:

• <TwitterUser> - domain class for your twitter 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
• TwitterAuthToken - token provided by plugin (instance of com.the6hours.grails.springsecurity.facebook.TwitterAuthToken)

TwitterAuthToken contains:

• String token
• String tokenSecret
• long userId
• String screenName

Notice that <TwitterUser> 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 DefaultTwitterAuthDao to understand how it works, and which methods you can use for customization. It's much easier to read from the sources, that from the docs :)

List of possible methods:

<TwitterUser> findUser(TwitterAuthToken token)

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

<TwitterUser> create(TwitterAuthToken token)

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

Notice, that if you have such method, it replaces all other methods for user creation, like:

• generateUsername
• createUser, createAppUser and createTwitterUser
• afterCreate
• createRoles

<Person> createUser(<TwitterUser> user, TwitterAuthToken token)

Called if you have configured same domain for Twitter User and App User. Should create <Person> object and fill with all required details.

<TwitterUser> createTwitterUser(TwitterAuthToken token)

Called if you have configured two domains, one for main user, one for twitter user.

<Person> createAppUser(<TwitterUser> user, TwitterAuthToken token)

Called if you have configured two domains, one for main user, one for twitter user.

String generateUsername(<Person> user, TwitterAuthToken token)

Should generate a new unique username on a new user creation. If method doesn't exist, Twitter User Screen Name will be used.

Not called if you have implemented createAppUser() method

void afterCreate(<TwitterUser> user, TwitterAuthToken token)

Called after user was created by plugin, just after saving into database, but before roles are assigned to user. You can setup user object with some extra values. If you need to access Twitter API, you could use token, it contains `token` and `tokenSecret` for current user.

void createRoles(<TwitterUser> user)

Called when we have a new Twitter user, called on first login to create roles list for new user. If method doesn't exist, user will be created with default roles (configured at 'grails.plugins.springsecurity.twitter.autoCreate.roles')

void updateIfNeeded(<TwitterUser> user, TwitterAuthToken token)

Called on each login, you could update user details if needed.

<Person> getAppUser(<TwitterUser> user)

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

Object getPrincipal(<Person> person)

Principal to use with Spring Security. It's very useful if it will be instance of UserDetails class.

Collection<GrantedAuthority> getRoles(<Person> user)

Must return roles list for specified facebook user