Hi All guys,
As ASF committer, I propose the creation of a new Apache Lab, called
"Amber":
= Abstract =
The following proposal is about Apache Amber, a Java development framework
mainly aimed to build OAuth-aware applications. After a brief explanation
of the OAuth protocol, the following proposal describes how Apache Amber
solves issues related to the implementation of applications that adhere to
such specification. Code and examples are provided in order to show the
potential of the framework.
= Proposal details =
== Basic glossary ==
Service Provider - Is the term used to describe the website or web-service
where the restricted resources are located. It can be a photo sharing site
where
users keep albums, a microblogging site, or any other service where
'user's private stuff' is kept.
User - A user has 'stuff' he doesn't want to make public on the
Service Provider, but he does want to share it with another site. With
OAuth,
no manual interaction is required to the user once the permission to grant
access has been received.
Consumer - Is the term to refer an application trying to access the User's
resources. This can be a website, a desktop program, a mobile device, a
set-top
box, or anything else that has access to the Web.
Tokens - They are the main concept of the OAuth protocol. A Token is
generally
a random string of letters and numbers that is unique, hard to guess, and
paired
with a Secret to protect the Token from being abused.
== Background ==
Roughly, OAuth is a mechanism that allows users to share their private
resources,
like photo, videos or contacts, stored on a site with another site avoiding
giving their username and password credentials.
Hence, from the user point-of-view, OAuth could be the way to improve their
experience across different applications with an enhanced privacy and
security
control.
The main idea behind OAuth is represented by the token concept. Each token
grants
access to a site, for a specific resource (or a group of resources), and for
a
precise time-interval.
Moreover, the total transparency to the user, that is completely unaware of
using the protocol, represents one of the main valuable characteristics of
the
specification.
Apache Amber community aims not just to create a simple low-level library,
but
rather to provide a complete OAuth framework easy to use with Java code, on
top
of which users can build new-generation killer applications.
=== Technology (basics) ===
If you're looking for an answer to the question "What's OAuth?" the official
OAuth website[1] says: "An open protocol to allow secure API authorization
in a simple and standard method from desktop and web applications".
For Consumer developers, it is a simple way to access to users' protected
data
stored in a Service Provider.
For Service Provider developers, it is a safe and secure way to allow
Consumer
access users' protected data without having them to release their account
credentials around the web to give Consumers access.
In the following section a concrete example of the technology is provided by
listing
code lines with some key aspects.
=== Technology (concrete) ===
This is just an example. Imagine that there is an application "someapp" on
the host foo.example.com which needs to implement an OAuth Consumer to
import
users' contacts from different sources like GMail, Plaxo, Yahoo!, etc...
Apache Amber should provide easy to use APIs to facilitate OAuth
interactions
with Service Providers; let's take into consideration a Consumer instance
that knows all the details about the Service Provider, like the OAuth
endpoints,
the HTTP Methods that have to be used, the way to send OAuth and optional
parameters, etc and last, but not least, it owns a Consumer Key and a set of
consumer secrets. [TODO may be terminate]
To obtain a request token, developers should simply call the following
methods:
{{{
Consumer consumer = ...;
RequestToken requestToken;
// just invoke
try {
requestToken = consumer.doRequestToken();
} catch (OAuthException e) {
// a server error/error code, or an HTTP error, ...
e.printStackTrace();
}
}}}
If the Service Provider requires optional parameters, like the Google
Service
Provider does with the 'scope' parameter:
{{{
// aux parameters can optionally send if required, like Google does:
try {
requestToken = consumer.doRequestToken(new Parameter("scope",
"http://www.google.com/m8/feeds/";));
} catch (OAuthException e) {
// a server error/error code, or an HTTP error, ...
e.printStackTrace();
}
}}}
Having obtained the request token, it has to be authorized by the end-user
and
it could be easily implemented as:
{{{
// Obtain the user authorization
UserAuthorizationHandler handler = ...;
try {
requestToken = consumer.requestUserAuthorization(requestToken, handler);
} catch (OAuthException e) {
// a server error/error code, or an HTTP error, ...
e.printStackTrace();
}
}}}
Where the UserAuthorizationHandler is something being able to intercept the
user
authorization page URL: desktop applications may be needed to open a
browser:
{{{
public class OpenBrowserAuthorizationHandler implements
UserAuthorizationHandler {
public void handleURL(URL url) throws OAuthException {
String browser = "firefox";
try {
Runtime.getRuntime().exec(new String[]{ browser, url.toString()
});
} catch (Exception e) {
throw new OAuthException("Impossible to open the browser
window", e);
}
}
}
}}}
Web applications instead need to redirect users to the authorization page,
and
specify a callback url where end users will be redirected once the request
token is authorized:
{{{
public class RedirectAuthorizationHandler implements
UserAuthorizationHandler {
private final HttpServletResponse response;
public RedirectAuthorizationHandler(HttpServletResponse response) {
this.response = response;
}
public void handleURL(URL url) throws OAuthException {
this.response.sendRedirect(redirect);
}
}
try {
requestToken = consumer.requestUserAuthorization(requestToken, handler,
new URL("http://www.myoauthconsumer.com/callback";));
} catch (OAuthException e) {
// a server error/error code, or an HTTP error, ...
e.printStackTrace();
}
}}}
Once the user has authorized the request token, this last can be easily
exchanged with an access token:
{{{
AccessToken accessToken;
try {
accessToken = consumer.doRequestAccessToken(requestToken);
} catch (OAuthException e) {
// a server error/error code, or an HTTP error, ...
e.printStackTrace();
}
}}}
Once having obtained the authorization token, the Consumer is able to access
users' protected resources and read the response feed:
{{{
Object obj;
try {
obj = consumer.accessProtectedResource(accessToken,
new URL("http://www.google.com/m8/feeds/contacts/default/full/
"),
new ObjectInputStreamHandler<Object>() {
Object handle(InputStream input) throws OAuthException {
Object ret;
// process the input and fill map it in the object;
return ret;
}
});
} catch (OAuthException e) {
// a server error/error code, or an HTTP error, ...
e.printStackTrace();
}
}}}
On the other hand, Service Provider developers should also have a set of
out of the box and easy to use APIs; it means that Service Provider APIs
should
be independent from any Container or Application Server to be easily
integrated.
A potential Provider interface could be:
{{{
interface Provider {
RequestToken requestToken(URL requestURL, HTTPMethod method,
String authorizationHeader, List<Parameter> parameterList) throws
OAuthException;
RequestToken authorizeToken(String oauthToken) throws OAuthException;
AccessToken accessToken(URL requestURL, HTTPMethod method,
String authorizationHeader, List<Parameter> parameterList) throws
OAuthException;
boolean canAccessToProtectedResource(URL requestURL, HTTPMethod method,
String authorizationHeader, List<Parameter> parameterList) throws
OAuthException;
}
}}}
We know Service Providers need storage(s) to retrieve Consumers'
information, add/get/update/delete tokens and check received
nonces and timestamps, so the framework could provide the interface APIs and
default 'in-memory' relative implementations, but at the same time Amber
users
are free to give their concrete implementations based on a DBMS for example,
using their preferred ORM/SQLMapper frameworks.
{{{
// replace default implementations with your own
ConsumerStorage consumerStorage = new InMemoryConsumerStorage();
TokenStorage tokenStorage = new InMemoryTokenStorage();
AccessStorage accessStorage = new InMemoryAccessStorage();
}}}
== Rationale: What would you use Apache Amber for? ==
* It could be the foundation framework for Consumer developers;
* It could be the foundation Framework for Service Provider developers;
* It could be integrated into Apache Shindig;
* It could be integrated into Apache Abdera;
* It could be integrated into Apache Wink;
* It could be integrated into Spring Security;
* It could be integrated into Jakarta JMeter;
* Most importantly, it could be a backend for dozens of useful new
innovative
projects that no-one has envisioned yet.
== Apache Amber as an Apache Project ==
The key role played by the OAuth specification, within the overall
Open Stack technologies [2], jointly with its high degree of adoption
[3] and maturity, strongly suggest having an Apache leaded
incubator for suitable reference implementation.
Furthermore, the OAuth specification is currently gaining value
due to its involvement in a standardization process within
the IETF [4], as the actual internet draft shows[5].
Having the Apache Amber as an Apache Lab could be an
opportunity to enforce the actual Apache projects that already
reference other IETF specifications.
Moreover, other Apache Projects, such as Abdera and Shindig,
are currently supporting the OAuth protocol, so having the
OAuth Apache reference implementation should benefit not only the project
and
the related community itself, but also existing and active Apache projects.
Most importantly, I think this project will be useful, innovative, and
fun!
= References =
[1] http://oauth.net/
[2]
http://josephsmarr.com/2008/11/10/a-new-open-stack-greater-than-the-sum-of-its-parts-internet-identity-workshop-2008b/
[3] http://wiki.oauth.net/ServiceProviders
[4] http://www.ietf.org/
[5] http://tools.ietf.org/id/oauth
http://people.apache.org/~simonetripodi/
<rdf:RDF xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#";
xmlns="http://usefulinc.com/ns/doap#"; xmlns:foaf="http://xmlns.com/foaf/0.1/";
xmlns:labs="http://labs.apache.org/doap-ext/1.0#"; xmlns:projects="http://projects.apache.org/ns/asfext#";>
<Project rdf:about="http://labs.apache.org/labs#at-digester";>
<name>Amber</name>
<shortname>at-digester</shortname>
<shortdesc xml:lang="en">OAuth Java framework</shortdesc>
<description xml:lang="en">A Java development framework
mainly aimed to build OAuth-aware applications.</description>
<homepage rdf:resource="http://labs.apache.org/amber/"; />
<license rdf:resource="http://usefulinc.com/doap/licenses/asl20"; />
<created>2010-1-24</created>
<labs:status>active</labs:status>
<maintainer>
<foaf:Person rdf:about="http://people.apache.org/~simonetripodi/";>
<foaf:name>Simone Tripodi</foaf:name>
<foaf:homepage
rdf:resource="http://people.apache.org/~simonetripodi/"; />
<foaf:mbox_sha1sum>a72e039d0a1f7e9d6299fb24dd1e43a9defb0dde</foaf:mbox_sha1sum>
</foaf:Person>
</maintainer>
<repository>
<SVNRepository>
<location
rdf:resource="http://svn.apache.org/repos/asf/labs/amber/"; />
<browse rdf:resource="http://svn.apache.org/viewvc/labs/amber/"; />
</SVNRepository>
</repository>
<programming-language>Java</programming-language>
</Project>
</rdf:RDF>
---------------------------------------------------------------------
To unsubscribe, e-mail: [email protected]
For additional commands, e-mail: [email protected]
