 ------
 Redback Rest Support
 ------
 Olivier Lamy
 ------
 2011-08-11
 ------

 ~~ Licensed to the Apache Software Foundation (ASF) under one
 ~~ or more contributor license agreements.  See the NOTICE file
 ~~ distributed with this work for additional information
 ~~ regarding copyright ownership.  The ASF licenses this file
 ~~ to you under the Apache License, Version 2.0 (the
 ~~ "License"); you may not use this file except in compliance
 ~~ with the License.  You may obtain a copy of the License at
 ~~
 ~~   http://www.apache.org/licenses/LICENSE-2.0
 ~~
 ~~ Unless required by applicable law or agreed to in writing,
 ~~ software distributed under the License is distributed on an
 ~~ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
 ~~ KIND, either express or implied.  See the License for the
 ~~ specific language governing permissions and limitations
 ~~ under the License.

 ~~ NOTE: For help with the syntax of this file, see:
 ~~ http://maven.apache.org/doxia/references/apt-format.html

Redback Rest Support

  Starting with version 1.3 some redback services are available trough rest request.

  Starting with version 2.5 we added some filters to prevent CSRF attacks.

  We use JAXRS annotations and authz/karma are verified through cxf interceptors.

%{toc}

* Cross Site Request Forgery ({CSRF}) prevention

  Starting with version 2.5 there has been added an interceptor that tries to check for CSRF attacks. CSRF can be initiated
  by malicious sites that let your browser execute HTTP requests or JavaScript-Code aimed to your redback site. Without
  CSRF prevention only the login cookie is checked for proper authorization and which is sent automatically from your
  browser after login. The redback REST services are not checking if the request is from the same origin as the login request.

  For more information see https://www.owasp.org/index.php/Cross-Site_Request_Forgery_(CSRF)

  Redback uses two mechanisms for checking cross site requests: Header validation and a validation token.

  The behaviour of the filter can be configured, see {{{../configuration.html#REST_security_settings}REST configuration}}

** Header validation

  The header validation uses a base URL where the incoming requests are checked against. Per default the base URL is
  determined dynamically, but can be configured.

  Each client request is checked for the HTTP headers 'Origin' and 'Referer' header.
  If the Origin header is existent and the base URL does not match the header value the request will be denied.
  After that the Referer header is checked and matched against the base URL. If the header is existent and does
  not the base URL the request is denied.
  If neither Origin nor Referer header are presented, the request is denied (can be configured).

** Validation Token

  If the header validation was successful, the request is checked for the X-XSRF-TOKEN header.
  This header must contain a token that is returned from the login REST service together with the user information.
  The token is encrypted by a key that is generated dynamically during startup of the redback service. That means
  that after restart of the redback services all tokens generated before will be invalid.
  Validation tokens have a lifetime of 3 hours. After that you have to login again.


* Maven Module

  You must add the following maven dependency

+--------------------------------------+

    <dependency>
      <groupId>org.codehaus.redback</groupId>
      <artifactId>redback-rest-services</artifactId>
      <version>${redbackVersion}</version>
    </dependency>

+--------------------------------------+


* CXF setup

  The spring file is in the redback-rest-services module.
  You must add META-INF/spring-context.xml in your spring configuration.

  And add cxf servlet in your web.xml :

+--------------------------------------+

    <servlet>
      <servlet-name>CXFServlet</servlet-name>
      <servlet-class>org.apache.cxf.transport.servlet.CXFServlet</servlet-class>
      <load-on-startup>1</load-on-startup>
    </servlet>

    <servlet-mapping>
      <servlet-name>CXFServlet</servlet-name>
      <url-pattern>/services/*</url-pattern>
    </servlet-mapping>

+--------------------------------------+

* CXF interceptors

  Rest services are declared as it in the cxf configuration :

+--------------------------------------+

  <jaxrs:server id="redbackServices" address="/redbackServices">
    <jaxrs:providers>
      <ref bean="authenticationInterceptor#rest"/>
      <ref bean="permissionInterceptor#rest"/>
    </jaxrs:providers>
	  <jaxrs:serviceBeans>
      <ref bean="userService#rest"/>
      ... more coming ...
    </jaxrs:serviceBeans>
   </jaxrs:server>

+--------------------------------------+

** AuthenticationInterceptor

  This interceptor is basic on HTTP BASIC authz with using HttpBasicAuthentication spring component.

** PermissionInterceptor

  This inceptor will use a new created annotation named @RedbackAuthorization which supports attributes : permissions, resource and noRestriction.

   You can use it :

+--------------------------------------+

   @RedbackAuthorization( permissions = "user-management-user-create" )
   public Boolean deleteUser( @PathParam( "userName" ) String username )
+--------------------------------------+

   The interceptor will basically check if the user has one of the required permissions.

   <<Note all exposed services must be marked with this annotation. If not forbidden http response will be returned.>>

   If the service doesn't need special permissions you must do :

+--------------------------------------+

   @RedbackAuthorization(noRestriction = true)
   public Boolean ping()

+--------------------------------------+

** RequestValidationIntercepter

  This is the interceptor used for CSRF prevention. See info {{{CSRF}above}}.

* Client Usage

  Dependencies to add in order to use those REST Services

+-------------------------

    <dependency>
      <groupId>org.codehaus.redback</groupId>
      <artifactId>redback-rest-api</artifactId>
      <version>${redbackVersion}</version>
    </dependency>

    if you use CXF:

    <dependency>
      <groupId>org.apache.cxf</groupId>
      <artifactId>cxf-bundle-jaxrs</artifactId>
      <version>2.6.4</version>
      <exclusions>
        <exclusion>
          <groupId>org.eclipse.jetty</groupId>
          <artifactId>jetty-server</artifactId>
        </exclusion>
      </exclusions>
    </dependency>

+-------------------------

  Sample on how to use

%{snippet|id=create-user|url=http://svn.apache.org/repos/asf/archiva/redback/redback-core/trunk/redback-integrations/redback-rest/redback-rest-services/src/test/java/org/apache/archiva/redback/rest/services/LoginServiceTest.java}

%{snippet|id=get-user-service|url=http://svn.apache.org/repos/asf/archiva/redback/redback-core/trunk/redback-integrations/redback-rest/redback-rest-services/src/test/java/org/apache/archiva/redback/rest/services/AbstractRestServicesTest.java}