oAuth

OAuth protocol is described here http://oauth.net/core/1.0/. What OAuth does, it 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 resourse without sharing your identity at all. More about oAuth at site http://oauth.net/. This article describes how-to configure our implementation of oAuth service and client part. The both part service (Provider) and client (Consumer) 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.

Provider.

Provider consists from two part oauthprovider.war and exo.ws.security.oauth.provider.service-trunk.jar . The main part of Provider is OAuthProviderService, currently there is one implementation of this interface org.exoplatform.ws.security.oauth.impl.OAuthProviderServiceMD5Impl this component of container has few required configuration parameters. This is the part of 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:

  1. name the name of provider, client will send the name of provider what it wants to use.
  2. secret this property is used for subscribe requests, this property must be known for Provider and Consumer.
  3. description this is optional, any description of Provider can be present here.
  4. callbackURL this is URL where client will be redirected after successful authentication on Provider.
That is all what needed for configuration provider service. The next part of configuration is about web, such as servlets. The web part of provider consists of 3 servlets: OAuthRequestTokenServlet, OAuthAccessTokenServlet, 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>

Consumer.

Consumer consists of OAuthConsumerService and web part (servlets, and filters). How it works, OAuthConsumerFilter checks cookies in client's request. Cookie must have name _consumer_name_.oauth_token and _consumer_name_.oauth_token_secret. Then this filter try to find request/access token this at OAuthConsumerService. If token from request is access token then it minds client already authenticated then client gets access to requested resource. Otherwise client will be redirected to Provider for authentication (see below, property "provider.authorizationURL"). This is part of configuration.xml for 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>

Client redirected for authentication to provider with required parameters (request and secret token), before this token OAuthClinet got from Provider (see configuration, property "provider.tokenRequestURL"). On Provider side User (if authentication successful and has valid request parameters) will be redirected to Consumer again (see property "callbackURL" in Provider configuration). Than Consumer (this is, the same as receiving request token, invisible for Client) receive access token, and redirect Client to original URL. Then filter checks token from request and gives access to requested resource. This is the file we.xml for Consumer application, this is example of web.xml where 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, just web.xml must be configured to set required for OAuthConsumerFilter. Client must save given access and secret token in cookie.

oAuth.png

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

  1. green - stage 1 (receiving request token)
  2. yellow - stage 2 (authentication)
  3. blue - stage 3 (receiving access token)
  4. red - stage 4 (get protected resource)
Alive time for tokens can be set in configuration.
<value-param>
  <!-- this parameter MUST be set in minutes -->
  <name>tokenAliveTime</name>
  <value>300</value>
</value-param>

There is special component Cleaner on consumer side, it starts, by default, every 5 minutes and checks all tokens. If it found token with expired time it removes it from the storage. Token cleaner timeout (how often it must run) can be also set in 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>

Creator: Andrey Parfonov on 2008/04/29 08:44
Copyright (c) 2000-2009. Allright reserved - eXo platform SAS
1.6.13286