| <!DOCTYPE html> |
| <!-- |
| | Generated by Apache Maven Doxia Site Renderer 1.8.1 |
| | Rendered using Apache Maven Fluido Skin 1.6 |
| --> |
| <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 http-equiv="Content-Language" content="en" /> |
| <title>Apache Redback – Redback Rest Support</title> |
| <link rel="stylesheet" href="../css/apache-maven-fluido-1.6.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.6.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"> |
| <a href="https://github.com/apache/archiva-redback-core"> |
| <img style="position: absolute; top: 0; right: 0; border: 0; z-index: 10000;" |
| src="https://s3.amazonaws.com/github/ribbons/forkme_right_gray_6d6d6d.png" |
| alt="Fork me on GitHub"> |
| </a> |
| <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> |
| <li class="dropdown-submenu"> |
| <a href="../" title="Module Documentation">Module Documentation</a> |
| <ul class="dropdown-menu"> |
| <li><a href="../core/" title="Release 2.6">Release 2.6</a></li> |
| <li><a href="../core/3.0.0-SNAPSHOT/" title="Dev 3.0.0-SNAPSHOT">Dev 3.0.0-SNAPSHOT</a></li> |
| </ul> |
| </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="http://archiva.apache.org/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="../ci-management.html" title="CI Management">CI Management</a></li> |
| <li><a href="../mailing-lists.html" title="Mailing Lists">Mailing Lists</a></li> |
| <li><a href="../issue-management.html" title="Issue Management">Issue Management</a></li> |
| <li><a href="../licenses.html" title="Licenses">Licenses</a></li> |
| <li><a href="../team.html" title="Team">Team</a></li> |
| <li><a href="../scm.html" title="Source Code Management">Source Code Management</a></li> |
| </ul> |
| </li> |
| </ul> |
| </li> |
| </ul> |
| <form id="search-form" action="https://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">asyncJs( 'https://cse.google.com/brand?form=search-form' )</script> |
| </div> |
| </div> |
| </div> |
| </div> |
| <div class="container"> |
| <div id="banner"> |
| <div class="pull-left"><a href="http://archiva.apache.org/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 class=""><a href="https://www.apache.org" class="externalLink" title="Apache">Apache</a><span class="divider">/</span></li> |
| <li class=""><a href="../../" title="Archiva">Archiva</a><span class="divider">/</span></li> |
| <li class=""><a href="../" title="Redback">Redback</a><span class="divider">/</span></li> |
| <li class="active ">Redback Rest Support</li> |
| <li id="publishDate" class="pull-right">Last Published: 2019-11-29</li> |
| </ul> |
| </div> |
| <div id="bodyColumn" > |
| <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_.28CSRF.29_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_.28CSRF.29_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 class="prettyprint"> |
| <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 class="prettyprint"> |
| <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 class="prettyprint"> |
| <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 class="prettyprint"> |
| @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 class="prettyprint"> |
| @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 class="prettyprint"> |
| <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 class="prettyprint">Error during retrieving content skip as ignoreDownloadError activated.</pre></div> |
| <div class="source"><pre class="prettyprint">Error during retrieving content skip as ignoreDownloadError activated.</pre></div></div></div> |
| </div> |
| </div> |
| <hr/> |
| <footer> |
| <div class="container"> |
| <div class="row"> |
| <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="https://archiva.apache.org/redback-site/privacy-policy.html">Privacy Policy</a> |
| </div> |
| </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="https://www.ohloh.net/p/8659/widgets/project_thin_badge.js"></script> |
| </div> |
| </div> |
| </footer> |
| </body> |
| </html> |