oAuth

1 Overview
2 Provider
- 2.1 Configuration
- 2.2 Servlets
3 Consumer

1 Overview

OAuth allows to grant access to private resources on one site (which is called the Service Provider), to another site (called Consumer). OAuth is giving access to a resource without sharing your identity at all. More about oAuth at the site http://oauth.net/. (OAuth protocol: http://oauth.net/core/1.0/)

This article describes how to configure our implementation of oAuth service and client part. Both parts, service (Provider) and client (Consumer) are based on oAuth core, this code can be found here http://oauth.googlecode.com/svn/code/java/core/.

Our implementation can be found here http://svn.exoplatform.org/svnroot/exoplatform/projects/ws/trunk/security/oauth.

2 Provider

The provider consists of two parts oauthprovider.war and exo.ws.security.oauth.provider.service-trunk.jar. The main part of the provider is OAuthProviderService, currently there is one implementation of this interface org.exoplatform.ws.security.oauth.impl.OAuthProviderServiceMD5Impl; this component has few required configuration parameters.

2.1 Configuration

The configuration is defined in the file configuration.xml.

<component>                                                                                                                
  <type>org.exoplatform.ws.security.oauth.impl.OAuthProviderServiceMD5Impl</type>                                          
  <init-params>                                                                                                            
    <properties-param>                                                                                                     
      <name>exo1</name>                                                                                                    
      <property name="secret" value="81d1b5d080d1" />                                                                      
      <property name="description" value="description" />                                                                  
      <property name="callbackURL" value="http://localhost:8080/ws-examples/callback" />                                   
    </properties-param>                                                                                                    
  </init-params>                                                                                                           
</component>

Properties:

name: the name of provider, the client will send the name of provider that it wants to use.
secret: this property is used for subscribe requests, this property must be known to the provider and the consumer.
description: any description of the provider. Optional.
callbackURL: this is URL where the client will be redirected after successful authentication by the provider.

That is all what is needed for the configuration of the provider service. The next part of configuration is about web, such as servlets.

2.2 Servlets

The web part of the provider consists of 3 servlets:

OAuthRequestTokenServlet,
OAuthAccessTokenServlet, and
OAuthAuthorizationServlet.

<?xml version="1.0" encoding="UTF-8"?>                                                                                                                                                                         
<web-app version="2.4" xmlns="http://java.sun.com/xml/ns/j2ee" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://java.sun.com/xml/ns/j2ee                                       
        http://java.sun.com/xml/ns/j2ee/web-app_2_4.xsd">                                                                                                                                                      
  <display-name>oAuth provider</display-name>                                                                                                                                                                  
  <context-param>                                                                                                                                                                                              
    <description>Login page name</description>                                                                                                                                                                 
    <param-name>login-page</param-name>                                                                                                                                                                        
    <param-value>login/jsp/login.jsp</param-value>                                                                                                                                                             
  </context-param>                                                                                                                                                                                             
  <servlet>                                                                                                                                                                                                    
    <servlet-name>OAuthAuthenticationServlet</servlet-name>                                                                                                                                                    
    <servlet-class>org.exoplatform.ws.security.oauth.http.OAuthAuthenticationServlet</servlet-class>                                                                                                           
  </servlet>                                                                                                                                                                                                   
  <servlet>                                                                                                                                                                                                    
    <servlet-name>OAuthRequestTokenServlet</servlet-name>                                                                                                                                                      
    <servlet-class>org.exoplatform.ws.security.oauth.http.OAuthRequestTokenServlet</servlet-class>                                                                                                             
  </servlet>                                                                                                                                                                                                   
  <servlet>                                                                                                                                                                                                    
    <servlet-name>OAuthAccessTokenServlet</servlet-name>                                                                                                                                                       
    <servlet-class>org.exoplatform.ws.security.oauth.http.OAuthAccessTokenServlet</servlet-class>                                                                                                              
  </servlet>                                                                                                                                                                                                   
  <servlet-mapping>                                                                                                                                                                                            
    <servlet-name>OAuthAuthenticationServlet</servlet-name>                                                                                                                                                    
    <url-pattern>/authorize/*</url-pattern>                                                                                                                                                                    
  </servlet-mapping>                                                                                                                                                                                           
  <servlet-mapping>                                                                                                                                                                                            
    <servlet-name>OAuthRequestTokenServlet</servlet-name>                                                                                                                                                      
    <url-pattern>/request_token/*</url-pattern>                                                                                                                                                                
  </servlet-mapping>                                                                                                                                                                                           
  <servlet-mapping>                                                                                                                                                                                            
    <servlet-name>OAuthAccessTokenServlet</servlet-name>                                                                                                                                                       
    <url-pattern>/access_token/*</url-pattern>                                                                                                                                                                 
  </servlet-mapping>                                                                                                                                                                                           
</web-app>

3 Consumer

The consumer consists of OAuthConsumerService and web part (servlets and filters).

3.1 How it works

OAuthConsumerFilter checks cookies in client's request. The cookie must have the name _consumer_name_.oauth_token and _consumer_name_.oauth_token_secret. Then this filter try to find the request/access token this at OAuthConsumerService. If the token from the request is an access token then the client is already authenticated and gets access to requested resource.

Otherwise the client will be redirected to the provider for authentication (see below, property "provider.authorizationURL"). This is the part of configuration.xml for the consumer:

<component>                                                                                                                                                                                                  
  <type>org.exoplatform.ws.security.oauth.impl.OAuthConsumerServiceImpl</type>                                                                                                                               
  <init-params>                                                                                                                                                                                              
    <value-param>                                                                                                                                                                                            
      <!-- this parameter MUST be set in minutes -->                                                                                                                                                         
      <name>tokenAliveTime</name>                                                                                                                                                                            
      <value>300</value>                                                                                                                                                                                     
    </value-param>                                                                                                                                                                                           
    <properties-param>                                                                                                                                                                                       
      <name>exo1</name>                                                                                                                                                                                      
      <property name="secret" value="81d1b5d080d1" />                                                                                                                                                        
      <property name="description" value="description" />                                                                                                                                                    
      <property name="provider.tokenRequestURL" value="http://localhost:8080/oauthprovider/request_token" />                                                                                                 
      <property name="provider.authorizationURL" value="http://localhost:8080/oauthprovider/authorize" />                                                                                                    
      <property name="provider.accessTokenURL" value="http://localhost:8080/oauthprovider/access_token" />                                                                                                   
    </properties-param>                                                                                                                                                                                      
  </init-params>                                                                                                                                                                                             
</component>                                                                                                                                                                                                 
<component>                                                                                                                                                                                                  
  <type>org.exoplatform.ws.security.oauth.impl.OAuthClientHttpImpl</type>                                                                                                                                    
</component>                                                                                                                                                                                                 
<component>                                                                                                                                                                                                  
  <type>org.exoplatform.ws.security.oauth.impl.OAuthTokenCleanerImpl</type>                                                                                                                                  
  <init-params>                                                                                                                                                                                              
  <value-param>                                                                                                                                                                                              
    <!-- this parameter MUST be set in minutes -->                                                                                                                                                           
    <name>tokenCleanerTimeout</name>                                                                                                                                                                         
    <value>3</value>                                                                                                                                                                                         
  </value-param>                                                                                                                                                                                             
  </init-params>                                                                                                                                                                                             
</component>

The client is redirected for authentication to the provider with the required parameters (request and secret token), before this token OAuthClient got from the provider (see configuration, property "provider.tokenRequestURL"). On the provider side, the user (if the authentication is successful and has valid request parameters) will be redirected to the consumer again (see property "callbackURL" in the provider configuration). Then the consumer (this is, the same as receiving request token, invisible for the client) receives the access token, and redirects the client to the original URL. Then the filter checks the token from the request and gives access to the requested resource.

3.2 web.xml

This is the file web.xml for consumer application, in this example the resource http://localhost:8080/ws-examples/oauth/protected/ is under oAuth protect :

<filter>
<filter-name>OAuthConsumerFilter</filter-name>     
  <filter-class>org.exoplatform.ws.security.oauth.http.OAuthConsumerFilter</filter-class> 
 <init-param>
 <param-name>consumer</param-name>
 <param-value>exo1</param-value> 
</init-param> </filter>                                                                                                                                                                                                    <filter>
<filter-name>OAuthRequestWrapperFilter</filter-name> 
<filter-class>org.exoplatform.ws.security.oauth.http.OAuthRequestWrapperFilter</filter-class> </filter>                                                                                                                                                                                                    
                                                                                                                                                                                                              <filter-mapping>
<filter-name>OAuthConsumerFilter</filter-name>   
<url-pattern>/oauth/protected/*</url-pattern>  
</filter-mapping>
<filter-mapping>
<filter-name>OAuthRequestWrapperFilter</filter-name> 
<url-pattern>/oauth/protected/*</url-pattern>   
</filter-mapping>

Any resource can be protected by this mechanism under the condition that web.xml is configured to use OAuthConsumerFilter. Client must save the given access and the secret token in a cookie.

3.3 Stages

continuous line - client's redirections
fine dashed line - internal oAuth schema requests and responses.

Stages:

green - stage 1 (receiving request token)
yellow - stage 2 (authentication)
blue - stage 3 (receiving access token)
red - stage 4 (get protected resource)

3.4 Token Alive Time

Alive time for tokens can be set using the parameter tokenAliveTime.

<value-param>
  <!-- this parameter MUST be set in minutes -->
  <name>tokenAliveTime</name>
  <value>300</value>
</value-param>

3.5 Token Cleaner Timeout

There is special component cleaner on consumer side, it starts, by default, every 5 minutes and checks all tokens. If it finds token with expired time it removes it from the storage. Token cleaner timeout (how often it must run) can be also set in the configuration:

<component>
    <type>org.exoplatform.ws.security.oauth.impl.OAuthTokenCleanerImpl</type>
    <init-params>
    <value-param>
      <!-- this parameter MUST be set in minutes -->
      <name>tokenCleanerTimeout</name>
      <value&#623;</value>
    </value-param>
    </init-params>
  </component>

last modified by Sören Schmidt on 12/05/2009 at 20:14

oAuth

Top Menu

oAuth

1 Overview

2 Provider

2.1 Configuration

2.2 Servlets

3 Consumer

3.1 How it works

3.2 web.xml

3.3 Stages

3.4 Token Alive Time

3.5 Token Cleaner Timeout

Search

Products

eXo Optional Modules

eXo Core Foundations

Recently Modified