| <!DOCTYPE html> |
| <!-- |
| | Generated by Apache Maven Doxia |
| | Rendered using Apache Maven Fluido Skin 1.3.1 |
| --> |
| <html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en"> |
| <head> |
| <meta charset="UTF-8" /> |
| <meta name="viewport" content="width=device-width, initial-scale=1.0" /> |
| <meta name="author" content="Olivier Lamy" /> |
| <meta name="Date-Creation-yyyymmdd" content="20110811" /> |
| <meta name="Date-Revision-yyyymmdd" content="20170517" /> |
| <meta http-equiv="Content-Language" content="en" /> |
| <title>Apache Redback – Redback Rest Support</title> |
| <link rel="stylesheet" href="../css/apache-maven-fluido-1.3.1.min.css" /> |
| <link rel="stylesheet" href="../css/site.css" /> |
| <link rel="stylesheet" href="../css/print.css" media="print" /> |
| |
| |
| <script type="text/javascript" src="../js/apache-maven-fluido-1.3.1.min.js"></script> |
| |
| |
| <!-- Google Analytics --> |
| <script type="text/javascript"> |
| |
| var _gaq = _gaq || []; |
| _gaq.push(['_setAccount', 'UA-140879-5']); |
| _gaq.push(['_trackPageview']); |
| |
| (function() { |
| var ga = document.createElement('script'); ga.type = 'text/javascript'; ga.async = true; |
| ga.src = ('https:' == document.location.protocol ? 'https://ssl' : 'http://www') + '.google-analytics.com/ga.js'; |
| var s = document.getElementsByTagName('script')[0]; s.parentNode.insertBefore(ga, s); |
| })(); |
| |
| </script> |
| </head> |
| <body class="topBarEnabled"> |
| |
| |
| |
| |
| |
| <div id="topbar" class="navbar navbar-fixed-top "> |
| <div class="navbar-inner"> |
| <div class="container"><div class="nav-collapse"> |
| |
| |
| <ul class="nav"> |
| <li class="dropdown"> |
| <a href="#" class="dropdown-toggle" data-toggle="dropdown">Overview <b class="caret"></b></a> |
| <ul class="dropdown-menu"> |
| |
| <li> <a href="../index.html" title="Introduction">Introduction</a> |
| </li> |
| |
| <li> <a href="../authentication.html" title="Authentication">Authentication</a> |
| </li> |
| |
| <li> <a href="../authorization.html" title="Authorization">Authorization</a> |
| </li> |
| |
| <li> <a href="../user-management.html" title="User Management">User Management</a> |
| </li> |
| |
| <li> <a href="../key-store.html" title="Key Stores">Key Stores</a> |
| </li> |
| |
| <li> <a href="../configuration.html" title="Configuration">Configuration</a> |
| </li> |
| |
| <li class="dropdown-submenu"> |
| <a href="../rbac/introduction.html" title="Role Based Access Control">Role Based Access Control</a> |
| <ul class="dropdown-menu"> |
| <li> <a href="../rbac/role-management.html" title="Role Management">Role Management</a> |
| </li> |
| </ul> |
| </li> |
| |
| <li> <a href="../integration/ldap.html" title="Ldap">Ldap</a> |
| </li> |
| |
| <li> <a href="../integration/rest.html" title="Rest">Rest</a> |
| </li> |
| </ul> |
| </li> |
| <li class="dropdown"> |
| <a href="#" class="dropdown-toggle" data-toggle="dropdown">Development <b class="caret"></b></a> |
| <ul class="dropdown-menu"> |
| |
| <li> <a href="../development/extending-authn.html" title="Extending Redback Authentication">Extending Redback Authentication</a> |
| </li> |
| |
| <li> <a href="../../redback/components" title="Redback Components">Redback Components</a> |
| </li> |
| |
| <li> <a href="../../redback/core" title="Redback Core">Redback Core</a> |
| </li> |
| </ul> |
| </li> |
| <li class="dropdown"> |
| <a href="#" class="dropdown-toggle" data-toggle="dropdown">ASF <b class="caret"></b></a> |
| <ul class="dropdown-menu"> |
| |
| <li> <a href="http://www.apache.org/foundation/how-it-works.html" title="How Apache Works">How Apache Works</a> |
| </li> |
| |
| <li> <a href="http://www.apache.org/foundation/" title="Foundation">Foundation</a> |
| </li> |
| |
| <li> <a href="http://www.apache.org/foundation/sponsorship.html" title="Sponsoring Apache">Sponsoring Apache</a> |
| </li> |
| |
| <li> <a href="http://www.apache.org/foundation/thanks.html" title="Thanks">Thanks</a> |
| </li> |
| </ul> |
| </li> |
| <li class="dropdown"> |
| <a href="#" class="dropdown-toggle" data-toggle="dropdown">Project Documentation <b class="caret"></b></a> |
| <ul class="dropdown-menu"> |
| |
| <li class="dropdown-submenu"> |
| <a href="../project-info.html" title="Project Information">Project Information</a> |
| <ul class="dropdown-menu"> |
| <li> <a href="../integration.html" title="Continuous Integration">Continuous Integration</a> |
| </li> |
| <li> <a href="../issue-tracking.html" title="Issue Tracking">Issue Tracking</a> |
| </li> |
| <li> <a href="../mail-lists.html" title="Mailing Lists">Mailing Lists</a> |
| </li> |
| <li> <a href="../license.html" title="Project License">Project License</a> |
| </li> |
| <li> <a href="../team-list.html" title="Project Team">Project Team</a> |
| </li> |
| <li> <a href="../source-repository.html" title="Source Repository">Source Repository</a> |
| </li> |
| </ul> |
| </li> |
| </ul> |
| </li> |
| </ul> |
| |
| <form id="search-form" action="http://www.google.com/search" method="get" class="navbar-search pull-right" > |
| |
| <input value="http://archiva.apache.org/redback" name="sitesearch" type="hidden"/> |
| <input class="search-query" name="q" id="query" type="text" /> |
| </form> |
| <script type="text/javascript" src="http://www.google.com/coop/cse/brand?form=search-form"></script> |
| |
| |
| |
| |
| <ul class="nav pull-right"><li> |
| |
| <a href="https://twitter.com/archiva" class="twitter-follow-button" data-show-count="false" data-align="right" data-size="large" data-show-screen-name="true" data-lang="en">Follow archiva</a> |
| <script type="text/javascript">!function(d,s,id){var js,fjs=d.getElementsByTagName(s)[0];if(!d.getElementById(id)){js=d.createElement(s);js.id=id;js.src="//platform.twitter.com/widgets.js";fjs.parentNode.insertBefore(js,fjs);}}(document,"script","twitter-wjs");</script> |
| |
| </li></ul> |
| |
| |
| </div> |
| |
| </div> |
| </div> |
| </div> |
| |
| <div class="container"> |
| <div id="banner"> |
| <div class="pull-left"> |
| <a href="../../redback" id="bannerLeft"> |
| <img src="../images/redback.jpg" alt="Redback"/> |
| </a> |
| </div> |
| <div class="pull-right"> <a href="http://www.apache.org/" id="bannerRight"> |
| <img src="https://www.apache.org/images/asf_logo_wide_2016.png" alt="Apache Software Foundation"/> |
| </a> |
| </div> |
| <div class="clear"><hr/></div> |
| </div> |
| |
| <div id="breadcrumbs"> |
| <ul class="breadcrumb"> |
| |
| |
| <li id="publishDate">Last Published: 2017-05-17 |
| <span class="divider">|</span> |
| </li> |
| <li class=""> |
| <a href="http://www.apache.org/" class="externalLink" title="Apache"> |
| Apache</a> |
| <span class="divider">/</span> |
| </li> |
| <li class=""> |
| <a href="../" title="Apache Redback"> |
| Apache Redback</a> |
| <span class="divider">/</span> |
| </li> |
| <li class="active ">Redback Rest Support</li> |
| |
| |
| |
| |
| </ul> |
| </div> |
| |
| |
| |
| <div id="bodyColumn" > |
| |
| <!-- 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 --><div class="section"> |
| <h2><a name="Redback_Rest_Support"></a>Redback Rest Support</h2> |
| <p>Starting with version 1.3 some redback services are available trough rest request.</p> |
| <p>Starting with version 2.5 we added some filters to prevent CSRF attacks.</p> |
| <p>We use JAXRS annotations and authz/karma are verified through cxf interceptors.</p> |
| <ul> |
| <li><a href="#Redback_Rest_Support">Redback Rest Support</a> |
| <ul> |
| <li><a href="#Cross_Site_Request_Forgery_CSRF_prevention">Cross Site Request Forgery (CSRF) prevention</a> |
| <ul> |
| <li><a href="#Header_validation">Header validation</a></li> |
| <li><a href="#Validation_Token">Validation Token</a></li></ul></li> |
| <li><a href="#Maven_Module">Maven Module</a></li> |
| <li><a href="#CXF_setup">CXF setup</a></li> |
| <li><a href="#CXF_interceptors">CXF interceptors</a> |
| <ul> |
| <li><a href="#AuthenticationInterceptor">AuthenticationInterceptor</a></li> |
| <li><a href="#PermissionInterceptor">PermissionInterceptor</a></li> |
| <li><a href="#RequestValidationIntercepter">RequestValidationIntercepter</a></li></ul></li> |
| <li><a href="#Client_Usage">Client Usage</a></li></ul></li></ul> |
| <div class="section"> |
| <h3><a name="Cross_Site_Request_Forgery_CSRF_prevention"></a>Cross Site Request Forgery (<a name="CSRF">CSRF</a>) prevention</h3> |
| <p>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.</p> |
| <p>For more information see <a class="externalLink" href="https://www.owasp.org/index.php/Cross-Site_Request_Forgery_(CSRF)">the OWASP info</a> .</p> |
| <p>Redback uses two mechanisms for checking cross site requests: Header validation and a validation token.</p> |
| <p>The behaviour of the filter can be configured, see <a href="../configuration.html#REST_security_settings">REST configuration</a> .</p> |
| <div class="section"> |
| <h4><a name="Header_validation"></a>Header validation</h4> |
| <p>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.</p> |
| <p>Each client request is checked for the HTTP headers <tt>Origin</tt> and <tt>Referer</tt> 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).</p></div> |
| <div class="section"> |
| <h4><a name="Validation_Token"></a>Validation Token</h4> |
| <p>If the header validation was successful, the request is checked for the <tt>X-XSRF-TOKEN</tt> header. This header must contain a token that is returned from the login REST service together with the user information (<tt>validationToken</tt> element of the user element returned from the Login service). The token is encrypted with 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.</p></div></div> |
| <div class="section"> |
| <h3><a name="Maven_Module"></a>Maven Module</h3> |
| <p>You must add the following maven dependency</p> |
| <div class="source"> |
| <pre> |
| <dependency> |
| <groupId>org.codehaus.redback</groupId> |
| <artifactId>redback-rest-services</artifactId> |
| <version>2.2-SNAPSHOT</version> |
| </dependency> |
| </pre></div></div> |
| <div class="section"> |
| <h3><a name="CXF_setup"></a>CXF setup</h3> |
| <p>The spring file is in the redback-rest-services module. You must add META-INF/spring-context.xml in your spring configuration.</p> |
| <p>And add cxf servlet in your web.xml :</p> |
| <div class="source"> |
| <pre> |
| <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> |
| </pre></div></div> |
| <div class="section"> |
| <h3><a name="CXF_interceptors"></a>CXF interceptors</h3> |
| <p>Rest services are declared as it in the cxf configuration :</p> |
| <div class="source"> |
| <pre> |
| <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> |
| </pre></div> |
| <div class="section"> |
| <h4><a name="AuthenticationInterceptor"></a>AuthenticationInterceptor</h4> |
| <p>This interceptor is basic on HTTP BASIC authz with using HttpBasicAuthentication spring component.</p></div> |
| <div class="section"> |
| <h4><a name="PermissionInterceptor"></a>PermissionInterceptor</h4> |
| <p>This inceptor will use a new created annotation named @RedbackAuthorization which supports attributes : permissions, resource and noRestriction.</p> |
| <p>You can use it :</p> |
| <div class="source"> |
| <pre> |
| @RedbackAuthorization( permissions = "user-management-user-create" ) |
| public Boolean deleteUser( @PathParam( "userName" ) String username )</pre></div> |
| <p>The interceptor will basically check if the user has one of the required permissions.</p> |
| <p><b>Note all exposed services must be marked with this annotation. If not forbidden http response will be returned.</b></p> |
| <p>If the service doesn't need special permissions you must do :</p> |
| <div class="source"> |
| <pre> |
| @RedbackAuthorization(noRestriction = true) |
| public Boolean ping() |
| </pre></div></div> |
| <div class="section"> |
| <h4><a name="RequestValidationIntercepter"></a>RequestValidationIntercepter</h4> |
| <p>This is the interceptor used for CSRF prevention. See info <a href="#CSRF">above</a>.</p></div></div> |
| <div class="section"> |
| <h3><a name="Client_Usage"></a>Client Usage</h3> |
| <p>Dependencies to add in order to use those REST Services</p> |
| <div class="source"> |
| <pre> |
| <dependency> |
| <groupId>org.codehaus.redback</groupId> |
| <artifactId>redback-rest-api</artifactId> |
| <version>2.2-SNAPSHOT</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> |
| </pre></div> |
| <p>Sample on how to use</p> |
| <div class="source"> |
| <pre>Error during retrieving content skip as ignoreDownloadError activated.</pre></div> |
| <div class="source"> |
| <pre>Error during retrieving content skip as ignoreDownloadError activated.</pre></div></div></div> |
| </div> |
| </div> |
| |
| <hr/> |
| |
| <footer> |
| <div class="container"> |
| <div class="row"> |
| <p >Copyright © 2006–2017 |
| <a href="http://www.apache.org/">The Apache Software Foundation</a>. |
| All rights reserved. |
| |
| </p> |
| </div> |
| |
| |
| <div class="row span12">Apache Redback, Redback, Apache, the Apache feather logo, and the Apache Archiva project logos are trademarks of The Apache Software Foundation.</div> |
| |
| <div class="row span12"> |
| <a href="http://archiva.apache.org/redback-site/privacy-policy.html">Privacy Policy</a> |
| </div> |
| |
| <p id="poweredBy" class="pull-right"> |
| <a href="http://maven.apache.org/" title="Built by Maven" class="poweredBy"> |
| <img class="builtBy" alt="Built by Maven" src="../images/logos/maven-feather.png" /> |
| </a> |
| </p> |
| |
| |
| |
| |
| |
| <div id="ohloh" class="pull-right"> |
| <script type="text/javascript" src="http://www.ohloh.net/p/8659/widgets/project_basic_stats.js"></script> |
| </div> |
| </div> |
| </footer> |
| </body> |
| </html> |
