7 Delegating authentication to OAuth providers

However, there might be situations where you want to delegate the authentication against a third-party provider, like Google or Facebook. Unfortunately, your pure Javascript front-end application cannot request the providers directly using OAuth, because then the access keys will be made public.

So is this plugin's responsibility to provide endpoints so your Grails backend acts as a proxy for your front-end client.

The flow is something like the following:

1. The client application requests and endpoint that requires authentication, so the server responds with a 401 response (*).
2. The client redirects the user to the login form (*).
3. This time, instead of using username and password, the user clicks on "Login with Google" button.
4. Browser navigates to a Grails URL. Grails will generate a Google Login URL, giving Google a Grails callback URL.
5. Browser navigates to Google Login. User logs in, and Google redirects the browser to the Grails callback URL.
6. Browser navigates to that Grails callback URL. Then, Grails will use OAuth to fetch user information (like email) from Google. Based on that, will generate a REST API token and fetch and store principal information. The response from Grails will be a front-end URL where the token is a parameter.
7. The browser will navigate to that URL, and the Javascript logic will read the token from the URL and store it locally.
8. The client sends again a request to the protected resource, passing the token as an HTTP header (*).

The steps flagged with (*) remain unchanged from the normal flow.

To support OAuth, this plugin uses Profile & Authentication Client for Java. So you can use any OAuth (1.0 and 2.0) provider they support. This includes at the time of writing:

• Dropbox.
• Facebook.
• GitHub.
• Google.
• LinkedIn.
• Twitter.
• Windows Live.
• Wordpress.
• Yahoo.
• Paypal.

To start the OAuth authentication flow, from your frontend application, generate a link to <YOUR_GRAILS_APP>/oauth/authenticate/<provider>. The user clicking on that link represents step 4 in the previous diagram.

Note that you can define the frontend callback URL in Config.groovy under grails.plugin.springsecurity.rest.oauth.frontendCallbackUrl. You need to define a closure that will be called with the token value as parameter:

grails.plugin.springsecurity.rest.oauth.frontendCallbackUrl = { String tokenValue -> "http://my.frontend-app.com/welcome#token=${tokenValue}" }

You can also define the URL as a callback parameter in the original link, eg:

http://your-grails-api.com/oauth/authenticate/google?callback=http://your-frontend-app.com/auth-success.html?token=

In this case, the token will be concatenated to the end of the URL.

Upon successful OAuth authorisation (after step 6.1 in the above diagram), an OauthUser will be stored in the security context. This is done by a bean named oauthUserDetailsService. The default implementation delegates to the configured userDetailsService bean, passing the profile ID as the username:

class DefaultOauthUserDetailsService implements OauthUserDetailsService {
    @Delegate
    UserDetailsService userDetailsService
    OauthUser loadUserByUserProfile(UserProfile userProfile, Collection<GrantedAuthority> defaultRoles) {
        UserDetails userDetails
        OauthUser oauthUser
        try {
            userDetails = userDetailsService.loadUserByUsername userProfile.id
            userDetails.authorities.addAll defaultRoles
            oauthUser = new OauthUser(userDetails.username, userDetails.password, userDetails.authorities, userProfile)
        } catch (exception) {
            oauthUser = new OauthUser(userProfile.id, 'N/A', defaultRoles, userProfile)
        }
        return oauthUser
    }
}

If you want to provide your own implementation, define it in resources.groovy with bean name oauthUserDetailsService. Make sure you implements the interface OauthUserDetailsService

Below are some examples on how to configure it for Google, Facebook and Twitter.

7.1 Google

grails {
    plugin {
        springsecurity {
            rest {
                oauth {
                    frontendCallbackUrl = { String tokenValue -> "http://my.frontend-app.com/welcome#token=${tokenValue}" }
                    google {
                        client = org.pac4j.oauth.client.Google2Client
                        key = 'xxxx.apps.googleusercontent.com'
                        secret = 'xxx'
                        scope = org.pac4j.oauth.client.Google2Client.Google2Scope.EMAIL
                        defaultRoles = ['ROLE_USER', 'ROLE_GOOGLE']
                    }
                }
            }
        }
    }
}

The scope can be from any value of the enum org.pac4j.oauth.client.Google2Client.Google2Scope

7.2 Facebook

grails {
    plugin {
        springsecurity {
            rest {
                oauth {
                    frontendCallbackUrl = { String tokenValue -> "http://my.frontend-app.com/welcome#token=${tokenValue}" }
                    facebook {
                        client = org.pac4j.oauth.client.FacebookClient
                        key = 'xxx'
                        secret = 'yyy'
                        scope = 'email,user_location'
                        fields = 'id,name,first_name,middle_name,last_name,username'
                        defaultRoles = ['ROLE_USER', 'ROLE_FACEBOOK']
                    }
                }
            }
        }
    }
}

The scope is a comma-separated list, without blanks, of Facebook permissions. See the Facebook documentation for more details.

fields may contain a comma-separated list, without blanks, of user fields.

Both scope and fields are optional, but it's highly recommendable to fine tune those lists so you don't ask for information you don't need.

7.3 Twitter

grails {
    plugin {
        springsecurity {
            rest {
                oauth {
                    frontendCallbackUrl = { String tokenValue -> "http://my.frontend-app.com/welcome#token=${tokenValue}" }
                    twitter {
                        client = org.pac4j.oauth.client.TwitterClient
                        key = 'xxx'
                        secret = 'yyy'
                        defaultRoles = ['ROLE_USER', 'ROLE_TWITTER']
                    }
                }
            }
        }
    }
}

There is no additional configuration for Twitter.