| ------ |
| 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} |
| |
| |
| |
| |
| |
| |