Hi Simone, While I think having an OAuth implementation here is a fine idea, I wonder if you're perhaps confusing Labs with Incubator. In your comments near the end of your message, you refer to other projects potentially using Amber to provide OAuth support. However, Labs are prohibited from making releases, so they would not be able to do that while Amber is still in Labs. Could you perhaps say more about what you have in mind with regard to collaboration and releasing of this project?
-- Martin Cooper On Sun, Jan 24, 2010 at 9:04 AM, Simone Tripodi <[email protected]> wrote: > 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/ > > > --------------------------------------------------------------------- > To unsubscribe, e-mail: [email protected] > For additional commands, e-mail: [email protected] > --------------------------------------------------------------------- To unsubscribe, e-mail: [email protected] For additional commands, e-mail: [email protected]
