1 Introduction

Getting Started

Start by adding the plugin as a dependency to BuildConfig.groovy:

plugins {
    compile ":shiro-oauth:0.2"
}

You can find the dependency declaration for the latest version on the plugin portal page. Next up is a little bit of configuration. Add the OAuth provider configuration to your Config.groovy file:

oauth {
    providers {
        twitter {
            provider = org.scribe.builder.api.TwitterApi
            key = 'consumer key'
            secret = 'consumer secret'
            callback = "${grails.serverURL}/oauth/twitter/callback"
            successUri = '/oauth/success?provider=twitter'
            failureUri = '/unauthorized'
        }
        facebook {
            …
        }
    }
}
security.shiro.oauth.linkAccountUrl = "/oauth/linkaccount"

The first block is the configuration for the OAuth plugin so check its documentation for more details. This plugin allows you to define configuration for 'twitter', 'facebook' and 'google', but you can also define your own (docs to be added).

You can put your own URL in there for successUri, but make sure that it maps to the ShiroOAuthController's onSuccess action and that the provider URL parameter is included. Use whatever you want for the failureUri setting.

For the callback URL, we recommend /oauth/<provider>/callback which automatically maps to the OauthController's callback action (note the different capitalisation of the controller name). Note that it must be an absolute URL. If you want to map your own URL, make sure to include the provider parameter:

"/oauth/success"(controller: "shiroOAuth", action: "onSuccess")
"/oauth/callback/$provider"(controller: "oauth", action: "callback")

The second configuration block, security.shiro.oauth.* is specifically for this plugin. The linkAccountUrl should map to a page that allows users to link their OAuth identities to internal Shiro accounts. You have to code this page yourself, but once you have the username and password for an internal Shiro account, be it a new one or an existing one, then you can forward the request to another action provided by the plugin:

def linkAccount() {
    def user = …
    forward controller: "shiroOAuth", action: "linkAccount", params: [username: params.username, password: params.password]
}

The above will link the OAuth account to the internal Shiro one automatically after using the given credentials to authenticate the internal account. Finally, it will redirect to the URL specified by either the `targetUri` parameter or if that doesn't exist, the `targetUri` session variable.

You can also pre-authenticate the target Shiro user account if for some reason you can't pass in the username and password. For example:

def linkAccount() {
    SecurityUtils.subject.login params.username, params.password
    forward controller: "shiroOAuth", action: "linkAccount"
}

If you choose to handle the linking yourself, note that the Shiro OAuth plugin puts the OAuth authentication token into the session under the key 'shiroAuthToken'. This should be removed from the session after a successful `subject.login()`.

Finally, you need to allow the user to log in via an OAuth provider. The easiest way to do this is to add a link to your login page:

<oauth:connect provider="twitter">Log in with Twitter</oauth:connect>

This tag is provided by the OAuth plugin. When the user clicks on the link, he or she will be redirected to the configured OAuth provider. If the user already has a linked account, he or she will be automatically logged in. Otherwise, he or she will be taken to the "link an account" page.