Introduction

Eric Woods and Matthew Marum are implementing support for an OAuth 2.0 Service Provider in Apache Shindig.  This article provides an overview of the implementation including high level design, supported flows, common How-Tos, and future considerations.

...

Note that the implementation is still evolving, so consider this design document to be a draft.

High Level Design

All OAuth 2.0 requests are received by the OAuth2Servlet.  Per the spec, there are two OAuth 2.0 related endpoints: /oauth/authorize and /oauth/token.  The request is quickly delegated to either the OAuth2AuthorizationHandler or the OAuth2Token handler accordingly.

...

We provide "poor-man" implementations of the two service interfaces; the OAuth2ServiceImpl uses in-memory data structures, and the OAuth2DataServiceImpl uses canonical.json.

OAuth 2.0 Flow Support

• Authorization Code Flow (done)
• Implicit Grant Flow (in progress)
• Client Credential Flow (in progress)

How-Tos

How to Register a Client

Clients are pre-registered in canonicaldb.json.  Client registration, authorization codes, access tokens, and refresh tokens are keyed by client.  Here's the current structure (subject to change):

 // Registry of OAuth 2.0 clients with Shindig's service provider.
 "oauth2" : {
     "advancedOpenSocialClient" : {
         "registration" : {
             "id" : "advancedOpenSocialClient",
             "secret": "advancedOpenSocialClient_secret",
             "title": "Most Advanced OpenSocial Client Ever!",
             "redirectUri" : "http://localhost:8080/oauthclients/OpenSocialClient",
             "type" : "confidential"
         },
         "authorizationCodes" : {
             "advancedClient_authcode_1" : {
                 // Authentication code has been consumed since associatedSignature exists
                 "redirectUri" : "http://localhost:8080/oauthclients/OpenSocialClient",
                 "associatedSignature" : "advancedClientOS_accesstoken_1"
             },
             "advancedClient_authcode_2" : {
                 "redirectUri" : "http://localhost:8080/oauthclients/OpenSocialClient"
             }
         },
         "accessTokens" : {
             "advancedClient_accesstoken_1" : {
                 "redirectUri" : "http://localhost:8080/oauthclients/OpenSocialClient"
             }
         }
     },
    "testClient" : {
         "registration" : {
             "id" : "testClient",
             "redirectUri" : "http://localhost:8080/oauthclients/OpenSocialClient",
             "type" : "public"
         }
     }
 }

How to Add a Custom Grant Handler

Per the OAuth 2.0 specification, grant types are extensible beyond the 4 pre-defined types (authorization_code, client_credentials, refresh_token, and password).  To accommodate, validation of new grant types, grant handlers are registered with the OAuth2Service.  The appropriate grant handler is identified by its registered "grant_type" and invoked within OAuth2Service.validateRequestForAccessToken(...) to validate requests.

TODO: where and how are grant handlers registered?

How to Enable/Disable OAuth 2.0 Security

You can add OAuth2 support to protect your Social APIs by using an AuthenticationHandlerProvider that provides the OAuth2Authenticationhandler.

...

If your AuthenticationHandlerProvider doesn't return the OAuth2AuthenticationHandler, your resources won't be protected by OAuth2.

Future Considerations

Currently, the entire OAuth 2.0 implementation is located in a single package within Shindig's social-api module.  We need to determine the most appropriate way to integrate this package into shindig.  We could integrate this package into social-api following the existing patterns, or it may even be broken out as an entirely new module within Shindig.  To be determined...

...