book

This paint by numbers has used:

Alfresco 4.2

CMIS Workbench 0.9.0-beta-1 & 0.10.0

oAuth Sample webapp

In October 2012, Alfresco announced an open application-programming interface (API) for Alfresco in the cloud.

There are some great resources available to show how to use the cloud api, including:
* video tutorials from Jeff Potts * Alfresco API documentation from the Alfresco Developer Portal

To access Alfresco in the cloud:

an Alfresco application uses the OAuth 2.0 authorization code flow to authenticate itself with Alfresco Cloud and to allow users to authorize the application to access data on their behalf.

oAuth is an open protocol to allow secure authorization in a simple and standard method from web, mobile and desktop applications. The oAuth protocol flow starts with making an authorisation request through to receiving initial and refresh access tokens for using in sessions.

oauth-flow

In addition to the Alfresco API documentation for the cloud showing how to do this, Jeff also highlights on the developer forum Gethin Jame’s oAuth sample application that demonstrates using the oAuth authentication protocol.

To get an access token to use with CMIS Workbench, Allegria has used Gethin’s oAuth sample application:

Steps

  1. Get the Alfresco oAuth application
  2. Register for the Cloud api
  3. Create an API key
  4. Configure oAuth web app
  5. Authorisation request
  6. Access token request

1. Get the Alfresco oAuth application

Gethin’s Alfresco oAuth Sample Application (uses gradle and runs in jetty servlet engine and http server) is easily used with CMIS workbench, so [[fork|Paint-by-numbers:-GitHub]] his alfresco-oauth-sample repository and [[import|Paint-by-numbers:-Eclipse]] it to Eclipse eGit.

The readme has simple instructions to get things running. For now just need to : * Ensure you have an up to date Java VM installed and port 8181 is not in use
* take note of the callback url http://localhost:8181/oauthsample/mycallback.html which will be used when registering the application with Alfresco in later steps

2. Register for the Cloud api

Need to follow a registration process with Alfresco to obtain api access by following the steps on the Alfresco developer portal (click on the ‘register for the cloud api’ button):

portal

3. Create an API key

Register cmis-workbench on the Alfresco Developer site to to get authentication configuration details

action

The application can be called anything, just needs to have a name so can get an ‘API Key’, so have called it ‘cmis-workbench to make things easier.
Edit the API Details and on the ‘Auth’ tab enter the callback url http://localhost:8181/oauthsample/mycallback.html (this comes from Gethin’s repository readme):

action

4. Configure oAuth web app

Follow the next next steps in Gethin’s readme: * Edit src/main/webapp/config.js and put in the client_id, client_secret and callback urls registered at The Alfresco Developer Portal (For this app, the redirect_uri should be http://localhost:8181/oauthsample/mycallback.html)
* Run the Alfresco-oAuth-Sample application:

 # change to the folder holding the imported project  
 ./gradlew  jettyRun

The first time it runs, the following output will appear:

oauth-flow

After the initial build, each subsequent time will output:

oauth-flow

5. Authorisation request

In a web browser go to http://localhost:8181/oauthsample to see the first step in the oAuth protocol flow (authorisation request).

request

The values in this screen should come from the config.js file configured in the previous step so just hit submit.

The authorisation screen from Alfresco Cloud will appear to allow entry of username and password that was set up when registered for api account:

auth-credentials

6. Access token request

Send the authorisation grant - nothing to do here but hit submit (the client secret will have come from config.js - it is blanked out here):

step2

Will get a response from the cloud with the access token:

step2-1

Other oAuth resources:

  • The Alfresco API documentation for the cloud describes a number of tools:
  • Jeff Potts uses Google’s Java oAuth2 client in his Alfresco cloud how-to video tutorials and highlights Jared Ottley’s Spring Social plug-in in the developer forums
  • CPAN oAuth modules:
    • Net::OAuth provides a low-level API for reading and writing OAuth messages (probably should start with Net::OAuth::Client). Net::OAuth provides; classes that encapsulate OAuth messages (requests and responses), message signing, message serialization and parsing, 2-legged requests (aka. tokenless requests, aka. consumer requests)
    • Net::OAuth::Simple - a simple wrapper round the OAuth protocol
    • OAuth::Simple - Simple OAuth authorization on your site
    • OAuth::Consumer - LWP based user agent with OAuth for consumer application
    • OAuth::Lite - OAuth framework (CONSUMER SIDE see OAuth::Lite::Consumer, SERVICE PROVIDER SIDE see OAuth::Lite::ServerUtil or to build server on mod_perl2, see OAuth::Lite::Server::mod_perl2.
    • OAuth::Lite::Util - utility for OAuth