Installation

• Install command
• Upgrading from a previous release
• Configuration
• OAuth authorization workflow with the OAuth plug-in
• Asking for authorization
• The callback and the access token
• Accessing OAuth protected resource
• Error handling
• Reference
• OauthService
• OauthController
• OauthTagLib
• Further documentation
• Example usage
• Contribute

Install command

Under your Grails application's root directory, type this command to install the OAuth Plugin

grails install-plugin oauth

Upgrading from a previous release

Since 0.4 the getAuthUrl methods on the OauthService have been removed. Instead the service returns the authorization URL as part of the request access token call. This allows less calls to be made to the service, and for the service to become a stateless session bean.

Configuration

Before using the OAuth plug-in, the required OAuth parameters should be defined in the grails-app/conf/Config.groovy file of your application.

e.g. One consumer identity for each OAuth service provider:

oauth {
	provider_name {
		requestTokenUrl = 'http://example.com/oauth/request_token'
		accessTokenUrl = 'http://example.com/oauth/access_token'
		authUrl = 'http://example.com/oauth/authorize'
                scope = 'http://example.com/oauth/feed/api/' // Optional - currently required by the Google GData APIs
		consumer.key = 'key'
		consumer.secret = 'secret'
	}
}

You can also specify multiple consumer identities for each OAuth service provider. e.g.:

oauth {
	provider_name {
		requestTokenUrl = 'http://example.com/oauth/request_token'
		accessTokenUrl = 'http://example.com/oauth/access_token'
		authUrl = 'http://example.com/oauth/authorize'
                scope = 'http://example.com/oauth/feed/api/' // Optional - currently required by the Google GData APIs
		consumers {
			consumer_a {
				key = 'key'
				secret = 'secret'
			}
			consumer_b {
				key = 'key'
				secret = 'secret'
			}
		}
	}
}

In addition to defining your OAuth providers, you also need to ensure your grails-app/conf/Config.groovy file defines your grails.serverURL. This will be used by the plug-in when generating your callback URL:

// Set per-environment serverURL stem for creating absolute links
environments {
    production {
        grails.serverURL = "http://www.changeme.com"
    }
    development {
        grails.serverURL = "http://localhost:8080/${appName}"
    }
    test {
        grails.serverURL = "http://localhost:8080/${appName}"
    }
}

OAuth authorization workflow with the OAuth plugin

Asking for authorization

To initiate the OAuth authentication process, first call the "auth" action of the plugin's OauthController with the consumer name and other optional parameters. The taglib shipped with the plugin provides convenient tags to help you create the link to the action with the parameters. Refer to the OauthTagLib section below for information about the taglib. The "auth" action will perform the perparation work and redirect to the user authorization URL.

For example, the following code creates a link to the "auth" action. "myConsumer" should be specified in the config. When the user clicks the link, the plugin will collect and prepare the required data and redirect to the user authorization URL of the service provider which the specified consumer belongs to. Then the user will be asked by the service provider whether to allow your application to access the user resources or not.

<g:oauthLink consumer='myConsumer'
             returnTo="[controller: 'myController', action: 'oauthComplete']">Authorize</g:oauthLink>

The callback and the access token

OAuth plugin provides a predefined callback action. It also handles exchanging the authorized token with the access token. So the only thing you need to take care of is to define your own action to handle the access token stored in the session by the callback.

After the user has chosen to allow or disallow the access, the service provider redirects back to "callback" action of the OauthController. The "callback" action will do the more homework and finally store the access token in the session object "oauthToken". "oauthToken" is a map with entries "key" and "secret", which contains the token key and secret of the access token.

Then your application's "returnTo" controller action will be called. You can then have your own code handle the access token any way you want (e.g. store the access token in the database).

However, depending on the implementation of the service provider, you may have to specify a hard coded callback URL on the service provider's website. In that case, specify the callback URL at the service provider to the URL of the "callback" action of the OauthController. e.g.:

http://your.server/your-app/oauth/callback

Accessing OAuth protected resource

After the completion of OAuth authorization by obtaining the authorized access token, your application is now qualified to access the protected user resource. The OauthService#accessResource method provides a convenient way for doing this.

Accessing a read-only resource. The "GET" method is used by default. The response returned is an OAuthResponse object containing the http response body, and the http response status:

OAuthResponse response = oauthService.accessResource('http://api.url', 'consumer_name',
    [key:'accesskey',secret:'accesssecret'])

Posting data to API resource:

def response = oauthService.accessResource('http://api.url',
					'consumer_name',
					[key:'accesskey',secret:'accesssecret'],
					'POST',
					[param1:'additional parameter']
					)

You can also use named parameters. Note that "consumer", "url", and "token" are required parameters:

def response = oauthService.accessResource(url: 'http://api.url', consumer: 'consumer_name',
    token:[key: 'accesskey', secret: 'accesssecret'], method: 'POST')

Error handling

When problems occur, the [OauthService|http://www.grails.org/plugin/oauth#OauthService" class="pageLink">UrlMappings will throw an OauthServiceException. You may catch the exception in your own code.

The OauthController makes use of the following i18n codes whenever an OauthServiceExceptioin is caught from the service:

• oauth.unknown
• oauth.requesttoken.missing
• oauth.accesstoken.missing
• oauth.400badrequest
• oauth.oauth.401unauthorized
• oauth.invalid.consumer
• oauth.invalid.token

Reference

OauthService

fetchRequestToken(java.lang.String consumerName)

• Used to fetch the authorization request token from the provided consumer.

• Used to return the access token returned from the provided consumer.

• Helper function with default parameters to access an OAuth protected resource. "url", "consumer", and "token" are required. "token" should be a map containing two entries; "key" and "secret". Returns the response body from the service as a String.

• Overloaded helper function with named parameters to access an OAuth protected resource. Returns the response body from the service as a String.

• Returns the consumer instance by name.

• Returns the OAuth service provider instance by name.

OauthController

auth

• The action to call to start the OAuth authorization sequence

• This action will be called when the OAuth service provider returns from user authorization

OauthResponse

status

• The http response status as an integer.

• The http payload as a String

OauthTagLib

oauthLink

• Renders an OAuth user authorization request link to the service provider. "returnTo" and "error" are optional. If none specified, the current controller and action will be used by default. The "returnTo" controller action will be called by OauthController#callback when the authorization process completes successfully. "error" controller and action will be called in case of any problem occurs.

<g:oauthLink consumer='myConsumer'>Authorize</g:oauthLink>
<g:oauthLink consumer='myConsumer' returnTo="[controller: 'myController']">Authorize</g:oauthLink>
<g:oauthLink consumer='myConsumer' returnTo="[controller: 'myController', action: 'oauthComplete']">Authorize</g:oauthLink>
<g:oauthLink consumer='myConsumer' returnTo="[controller: 'myController', action: 'oauthComplete']"
             error="[controller: 'errorController', action: 'errorAction']">Authorize</g:oauthLink>

• Construct the URL string for OAuth authorization action

• Renders the body of the tag when there's an OAuth error

<g:hasOauthError>
     <div class="errors">
           <g:renderOauthError />
     </div>
</g:hasLoginError>

• Renders the OAuth error. You should define messages for the error code. Refer to the "Error handling" section above.

<g:renderOauthError />

[Full source]

Further documentation

• http://oauth.net
• http://code.google.com/p/oauth-signpost
• http://hc.apache.org/httpcomponents-client/index.html

Example usage

• http://www.grails.org/plugin/picasa

Contribute

• http://wiki.github.com/dhou/grails-oauth

There is a known issue with version 0.12 of the OAuth plugin which is resolved in the forthcoming 0.13 version. Please see the FAQ (tab above) for a simple workaround.

Description

This is a Grails plugin to provide easy interaction with OAuth service providers. OAuth is an open standard for secure API authentication. Using OAuth, users can securely and easily allow third party applications to access their private data maintained by OAuth provider services through web service API. Refer to the OAuth 1.0 spec for complete details.

If you find any issues, please submit a bug on JIRA: http://jira.grails.org/browse/GPOAUTH

Please look at the CHANGES file to see what has changed since the last official release.

Configuration

Before using the OAuth plug-in, the required OAuth parameters should be defined in the grails-app/conf/Config.groovy file of your application.

e.g. One consumer identity for each OAuth service provider:

oauth {
	provider_name {
		requestTokenUrl = 'http://example.com/oauth/request_token'
		accessTokenUrl = 'http://example.com/oauth/access_token'
		authUrl = 'http://example.com/oauth/authorize'
                scope = 'http://example.com/oauth/feed/api/' // Optional - currently required by the Google GData APIs
		consumer.key = 'key'
		consumer.secret = 'secret'
	}
}

You can also specify multiple consumer identities for each OAuth service provider. e.g.:

oauth {
	provider_name {
		requestTokenUrl = 'http://example.com/oauth/request_token'
		accessTokenUrl = 'http://example.com/oauth/access_token'
		authUrl = 'http://example.com/oauth/authorize'
                scope = 'http://example.com/oauth/feed/api/' // Optional - currently required by the Google GData APIs
		consumers {
			consumer_a {
				key = 'key'
				secret = 'secret'
			}
			consumer_b {
				key = 'key'
				secret = 'secret'
			}
		}
	}
}

In addition to defining your OAuth providers, you also need to ensure your grails-app/conf/Config.groovy defines your grails.serverURL. This will be used by the plug-in when generating your callback URL:

// Set per-environment serverURL stem for creating absolute links
environments {
    production {
        grails.serverURL = "http://www.changeme.com"
    }
    development {
        grails.serverURL = "http://localhost:8080/${appName}"
    }
    test {
        grails.serverURL = "http://localhost:8080/${appName}"
    }
}

For more detailed information on how to integration OAuth into your application's workflow please view the installation tab.

FAQ

Where is the source repository located?

• http://github.com/acampbell3000/grails-oauth

• http://jira.codehaus.org/browse/GRAILSPLUGINS

• http://github.com/acampbell3000/grails-oauth/blob/master/oauth-plugin/CHANGES.txt

• http://github.com/acampbell3000/grails-oauth/blob/master/oauth-plugin/LICENSE.txt

• http://github.com/acampbell3000/grails-oauth/blob/master/oauth-plugin/README.txt

• http://www.grails.org/plugin/picasa

• http://wiki.github.com/acampbell3000/grails-oauth

The plugin currently has a configuration bug which means that you need to insert the following into your configuration file before the plugin will work. This will be fixed in version 0.13

httpClient {
    timeout {
        socket = 5000
        connection = 5000
    }
}

• This plugin does not play nicely with Geb/Spock, or HttpBuilder (as signpost pulls in old libraries, and is now deprecated), you can fix it as follows: *

runtime ('org.codehaus.groovy.modules.http-builder:http-builder:0.5.1') {
            excludes 'xml-apis', 'httpclient'
}
test    ('org.seleniumhq.selenium:selenium-firefox-driver:2.4.0') {
            excludes 'xml-apis', 'httpclient'
}

Screenshots

The following section shows the Google accounts screen after clicking the OAuth link provided by Grails Picasa Plug-in.

Google Accounts