Tutorial-OAuth

Camel OAuth Tutorial

Overview

Goal of this tutorial is to demonstrate how to implement an OAuth consumer with Apache Camel. In this tutorial, the OAuth consumer is a simple web application running on Google App Engine. It reads data from a user's Google Calendar i.e. it displays the names of the user's public and private calendars. The OAuth-based authorization process that allows the application to access a user's calendars is implemented using Camel's gauth component. The application is accessible online at http://gauthcloud.appspot.com/oauth/calendar (later, it will be explained how to build and deploy the application yourself). Play with it by following these steps:

• Goto the application's main page at http://gauthcloud.appspot.com/oauth/calendar. If you haven't used the application before, you'll see a message that no OAuth access token is available.
  
  
  
  

• Follow the link next to this message to start the OAuth authorization process. You will be redirected to Google Accounts. A message is shown that a third party application is requesting access permissions. In order to grant (or deny) access, login to your Google account. This step may be skipped by Google if you already logged into Google Accounts before.
  
  
  
  

• After login, Google displays a message that gauthcloud.appspot.com wants to access your Google Calendar. Press the Grant access button to continue. No worries, the sample application will only read the names of your public and private Google calendars. No further reads or updates are made to your calendars. If you don't want gauthcloud.appspot.com to access your calendar, press Deny access.
  
  
  
  

• If you presses Grant access, Google redirects you back to the application that now displays the names of your public and private calendars. The following screenshot shows the list of my calendars (some of them have German names). Using OAUth, the web application gained access to your calendar data without ever having seen your Google username and password. These have been entered at a Google site directly.
  
  
  
  

• The result of a successful OAuth authorization process is an OAuth access token that is issued to the web application. The application stores this token for the duration of one hour. However, you can invalidate the access token at any time by either following the link below the calendar list or by going directly to https://www.google.com/accounts/IssuedAuthSubTokens. This will display a list of applications for which you granted access to your Google account. Among these, there's also an entry for gauthcloud.appspot.com. Click Revoke Access to invalidate the access token immediately.
  
  
  
  

• If you go back to the application or reload the page with the calendar list, a message is shown that the OAuth access token is invalid. Follow the OAuth authorization process again to renew the token.
  
  
  
  

Architecture

The following figure sketches the architcture of the distributed web application and an example sequence of interactions.

Application components

Sequence of actions

Deployment

This section explains how to build and deploy the web application yourself.

Prerequisites

• Sign up for a Google App Engine account if you don't have one.
• Create a new application via the admin console or reuse an existing one for uploading the example.
• Optional: register the application for use with Google's OAuth. After registration you should have access to a consumer key and a consumer secret. If you decide not to registere your application, use anonymous for the consumer key and the consumer secret. In this case Google will display a warning message on the authorization page which is acceptable for testing-purposes.
• Install the Google App Engine SDK for Java. This tutorial has been tested with version 1.3.2.

Build from sources

Checkout the sources with

svn co http://svn.apache.org/repos/asf/camel/trunk/examples/camel-example-gauth camel-example-gauth

Open camel-example-gauth/pom.xml file and define values for the application properties e.g.

<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/maven-v4_0_0.xsd">

    ...
    <properties>
        <!-- application properties -->
        <gae.application.name>gauthclaud</gae.application.name>
        <gae.consumer.key>gauthcloud.appspot.com</gae.consumer.key>
        <gae.consumer.secret>g2e...ue</gae.consumer.secret>
        ...
    </properties>
    ...

</project>

or

<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/maven-v4_0_0.xsd">

    ...
    <properties>
        <!-- application properties -->
        <gae.application.name>gauthclaud</gae.application.name>
        <gae.consumer.key>anonymous</gae.consumer.key>
        <gae.consumer.secret>anonymous</gae.consumer.secret>
        ...
    </properties>
    ...

</project>

if you don't want to register your application. Then go to the camel-example-gauth directory and enter

mvn install

This will create the application war file in the target directory.

Deploy to Appengine

Finally use the appcfg command-line tool of the App Engine SDK to deploy the application.

appcfg update target/camel-example-gauth-<version>

where version needs to be replaced with the version of Camel you're using. You will be prompted for the email address and password of your Google App Engine account. After deployment the example application is ready to use.

Code walkthrough

... work in progress ...