Authentication

HTTPBuilder supports a number of authentication mechanisms natively, to make working with protected sites as simple as possible.

Basic Authentication

Basic auth isn't terribly complicated in Apache HttpClient, but it's dead-simple in HTTPBuilder:

def authSite = new HTTPBuilder( 'https://some-protected-site.com/' )
authSite.auth.basic 'myUserName', 'myPassword'
 
secrets = authSite.get( path:'secret-info.txt' )

When a request is made, the server will respond with a 401 status and a WWW-Authenticate header, indicating that authorization is required. HTTPBuilder will then re-request with the proper Authorization header containing your credentials. This is all transparent to the developer, as it simply appears that the first request completed successfully.

See the HTTPClient authentication doc for more details.

Pre-emptive authentication

If you want to send the authorization header without waiting for the server to ask for it, you need currently to do it manually (see #61):

http.setHeaders([Authorization: "Basic dG90dTI2Nzg6dG90dTI2Nzg="])

(where dG90dTI2Nzg6dG90dTI2Nzg= is typically base64-encoded "user:password")

OAuth Support

OAuth is supported in HTTPBuilder since version 0.5.1. Support is provided by the Signpost framework in HTTPBuilder, RESTClient and HttpURLClient.

Obtaining an Access Token Pair

The Signpost documentation contains an example of how to obtain access tokens out-of-band. It's not completely straightforward, but it can be made significantly easier by using an interactive Groovy shell session. This allows execution to pause while you switch to your browser to access the validation URL. Below is an example:

groovy:000> groovy.grape.Grape.grab(group: 'oauth.signpost', module: 'signpost-core', version: '1.2.1.2')
===> null
groovy:000> import oauth.signpost.basic.*
===> import oauth.signpost.*
groovy:000> import oauth.signpost.basic.*
===> [import oauth.signpost.*, import oauth.signpost.basic.*]
groovy:000> consumer = new DefaultOAuthConsumer('<YOUR CONSUMER KEY HERE>', '<YOUR CONSUMER SECRET HERE>')
===> oauth.signpost.basic.DefaultOAuthConsumer@67f6dc61
groovy:000> provider = new DefaultOAuthProvider(
groovy:001>                 "http://twitter.com/oauth/request_token",
groovy:002>                 "http://twitter.com/oauth/access_token",
groovy:003>                 "http://twitter.com/oauth/authorize");
===> oauth.signpost.basic.DefaultOAuthProvider@1b2dd1b8
groovy:000> provider.retrieveRequestToken(consumer, OAuth.OUT_OF_BAND);
===> 'http://twitter.com/oauth/authorize?oauth_token=t66pPODPkOxnfEPZqziXp4xU7X4ByplHUFiFN5ylIA'
groovy:000> // copy the above line, paste it in your browser; Twitter will ask you to authorize...
groovy:000> provider.retrieveAccessToken(consumer, '<PIN NUMBER FROM BROWSER>')
===> null
groovy:000> println consumer.token
<YOUR ACCESS TOKEN>
===> null
groovy:000> println consumer.tokenSecret
<YOUR SECRET TOKEN>
===> null

Your app will now be authorized to make requests on behalf of the user that was logged in when you accessed the given URL in your browser. Now that you have your consumer key, consumer secret, access token an access key, give all four values to HTTPBuilder like so:

def twitter = new RESTClient( 'https://api.twitter.com/1.1/statuses/' )
twitter.auth.oauth consumerKey, consumerSecret, accessToken, secretToken
 
assert twitter.get( path : 'home_timeline.json' ).status == 200
 
// in HttpURLClient:
def twitter = new HttpURLClient(url:'https://api.twitter.com/1.1/statuses/')
 
http.setOAuth consumerKey, consumerSecret, accessToken, secretToken
assert twitter.request( path : 'home_timeline.json' ).status == 200

A final note about OAuth

Unlike basic auth and other schemes supported natively by HttpClient, OAuth does not wait for a WWW-Authenticate challenge from the server before signing a request, and OAuth cannot be configured for multiple domains in a single HTTPBuilder client. The means that once you call http.auth.oauth(), request signing is effectively 'turned on' for every request you make with that HTTPBuilder instance. If you want to stop signing requests, call http.auth.oauth(null,'','','').

Other Auth Mechanisms

HTTPBuilder and RESTClient also support 'Digest' and certificate authentication out-of-the-box, which simply exposes the underlying features present in Apache HttpClient. See the AuthConfig javadoc for a list of all authentication schemes supported. Currently HttpURLClient only supports 'Basic' and 'OAuth' authentication.