Modified: websites/production/cxf/content/docs/jax-rs.html
==============================================================================
--- websites/production/cxf/content/docs/jax-rs.html (original)
+++ websites/production/cxf/content/docs/jax-rs.html Tue Aug 29 11:11:59 2017
@@ -32,8 +32,8 @@
<link type="text/css" rel="stylesheet"
href="/resources/highlighter/styles/shThemeCXF.css">
<script src='/resources/highlighter/scripts/shCore.js'></script>
-<script src='/resources/highlighter/scripts/shBrushJava.js'></script>
<script src='/resources/highlighter/scripts/shBrushXml.js'></script>
+<script src='/resources/highlighter/scripts/shBrushJava.js'></script>
<script>
SyntaxHighlighter.defaults['toolbar'] = false;
SyntaxHighlighter.all();
@@ -117,26 +117,29 @@ Apache CXF -- JAX-RS
<td height="100%">
<!-- Content -->
<div class="wiki-content">
-<div id="ConfluenceContent"><p> </p><p> <span class="inline-first-p"
style="font-size:2em;font-weight:bold">JAX-RS
(JSR-339)</span> </p><p> </p><p><style type="text/css">/*<![CDATA[*/
-div.rbtoc1478713617597 {padding: 0px;}
-div.rbtoc1478713617597 ul {list-style: disc;margin-left: 0px;}
-div.rbtoc1478713617597 li {margin-left: 0px;padding-left: 0px;}
+<div id="ConfluenceContent"><p> </p><p> <span
style="font-size:2em;font-weight:bold">JAX-RS</span>
+
-/*]]>*/</style></p><div class="toc-macro rbtoc1478713617597">
+ </p><p> </p><p><style type="text/css">/*<![CDATA[*/
+div.rbtoc1504004873631 {padding: 0px;}
+div.rbtoc1504004873631 ul {list-style: disc;margin-left: 0px;}
+div.rbtoc1504004873631 li {margin-left: 0px;padding-left: 0px;}
+
+/*]]>*/</style></p><div class="toc-macro rbtoc1504004873631">
<ul class="toc-indentation"><li><a shape="rect"
href="#JAX-RS-Introduction">Introduction</a></li><li><a shape="rect"
href="#JAX-RS-JAX-RSCompliance">JAX-RS Compliance</a>
-<ul class="toc-indentation"><li><a shape="rect" href="#JAX-RS-2.0Final">2.0
Final</a></li><li><a shape="rect" href="#JAX-RS-1.1">1.1</a></li></ul>
+<ul class="toc-indentation"><li><a shape="rect" href="#JAX-RS-2.1Final">2.1
Final</a></li><li><a shape="rect" href="#JAX-RS-2.0Final">2.0
Final</a></li><li><a shape="rect" href="#JAX-RS-1.1">1.1</a></li></ul>
</li><li><a shape="rect" href="#JAX-RS-Projectsetupandconfiguration">Project
setup and configuration</a>
<ul class="toc-indentation"><li><a shape="rect"
href="#JAX-RS-Migration">Migration</a>
-<ul class="toc-indentation"><li><a shape="rect"
href="#JAX-RS-FromJAX-RS2.0toJAX-RS2.1">From JAX-RS 2.0 to JAX-RS
2.1</a></li><li><a shape="rect" href="#JAX-RS-FromJAX-RS1.1to2.0">From JAX-RS
1.1 to 2.0</a></li><li><a shape="rect"
href="#JAX-RS-FromCXF2.7.xtoCXF3.0.0">From CXF 2.7.x to CXF
3.0.0</a></li><li><a shape="rect"
href="#JAX-RS-CXF3.1.2ProviderSortingChanges">CXF 3.1.2 Provider Sorting
Changes</a></li><li><a shape="rect" href="#JAX-RS-FromCXF2.6.xtoCXF2.7.x">From
CXF 2.6.x to CXF 2.7.x</a></li></ul>
+<ul class="toc-indentation"><li><a shape="rect"
href="#JAX-RS-FromJAX-RS2.0toJAX-RS2.1">From JAX-RS 2.0 to JAX-RS
2.1</a></li><li><a shape="rect" href="#JAX-RS-FromJAX-RS1.1to2.0">From JAX-RS
1.1 to 2.0</a></li><li><a shape="rect"
href="#JAX-RS-FromCXF2.7.xtoCXF3.0.xor3.1.x">From CXF 2.7.x to CXF 3.0.x or
3.1.x</a></li><li><a shape="rect"
href="#JAX-RS-CXF3.1.2ProviderSortingChanges">CXF 3.1.2 Provider Sorting
Changes</a></li></ul>
</li><li><a shape="rect" href="#JAX-RS-Mavendependencies">Maven
dependencies</a>
-<ul class="toc-indentation"><li><a shape="rect" href="#JAX-RS-CXF3.0.0">CXF
3.0.0</a></li><li><a shape="rect" href="#JAX-RS-CXF2.7.0">CXF
2.7.0</a></li><li><a shape="rect" href="#JAX-RS-CXF2.6.x">CXF
2.6.x</a></li></ul>
-</li><li><a shape="rect" href="#JAX-RS-Settinguptheclasspath">Setting up the
classpath</a></li><li><a shape="rect" href="#JAX-RS-CXFJAX-RSbundle">CXF JAX-RS
bundle</a></li></ul>
+<ul class="toc-indentation"><li><a shape="rect" href="#JAX-RS-CXF3.2.0">CXF
3.2.0</a></li><li><a shape="rect" href="#JAX-RS-CXF3.1.x">CXF
3.1.x</a></li></ul>
+</li><li><a shape="rect" href="#JAX-RS-CXFJAX-RSbundle">CXF JAX-RS
bundle</a></li></ul>
</li><li><a shape="rect" href="#JAX-RS-WhatisNew">What is New</a></li><li><a
shape="rect" href="#JAX-RS-GettingStartedwithJAX-RS">Getting Started with
JAX-RS</a>
<ul class="toc-indentation"><li><a shape="rect"
href="#JAX-RS-UnderstandingtheBasics">Understanding the Basics</a></li><li><a
shape="rect" href="#JAX-RS-SupportforDataBindings">Support for Data
Bindings</a></li><li><a shape="rect" href="#JAX-RS-HowRequestURIisMatched">How
Request URI is Matched</a></li><li><a shape="rect"
href="#JAX-RS-ClientAPI">Client API</a></li><li><a shape="rect"
href="#JAX-RS-BeanValidation">Bean Validation</a></li><li><a shape="rect"
href="#JAX-RS-Filters,InterceptorsandInvokers">Filters, Interceptors and
Invokers</a></li><li><a shape="rect"
href="#JAX-RS-ServicelistingsandWADLsupport">Service listings and WADL
support</a></li><li><a shape="rect"
href="#JAX-RS-ConfiguringJAX-RSservices">Configuring JAX-RS
services</a></li><li><a shape="rect"
href="#JAX-RS-Testing">Testing</a></li><li><a shape="rect"
href="#JAX-RS-Debugging">Debugging</a></li><li><a shape="rect"
href="#JAX-RS-Logging">Logging</a></li></ul>
</li><li><a shape="rect" href="#JAX-RS-AdvancedFeatures">Advanced Features</a>
<ul class="toc-indentation"><li><a shape="rect"
href="#JAX-RS-Multiparts">Multiparts</a></li><li><a shape="rect"
href="#JAX-RS-SecureJAX-RSservices">Secure JAX-RS services</a></li><li><a
shape="rect" href="#JAX-RS-FailoverandLoadDistributionFeatures">Failover and
Load Distribution Features</a></li><li><a shape="rect"
href="#JAX-RS-Redirection">Redirection</a></li><li><a shape="rect"
href="#JAX-RS-XSLTandXPath">XSLT and XPath</a></li><li><a shape="rect"
href="#JAX-RS-ComplexSearchQueries">Complex Search Queries</a></li><li><a
shape="rect" href="#JAX-RS-Model-View-Controllersupport">Model-View-Controller
support</a></li><li><a shape="rect"
href="#JAX-RS-CombiningJAX-WSandJAX-RS">Combining JAX-WS and
JAX-RS</a></li><li><a shape="rect"
href="#JAX-RS-IntegrationwithDistributedOSGi">Integration with Distributed
OSGi</a></li><li><a shape="rect" href="#JAX-RS-OtherAdvancedFeatures">Other
Advanced Features</a></li></ul>
</li><li><a shape="rect" href="#JAX-RS-MavenPlugins">Maven
Plugins</a></li><li><a shape="rect"
href="#JAX-RS-Deployment">Deployment</a></li><li><a shape="rect"
href="#JAX-RS-Third-partyprojects">Third-party projects</a></li><li><a
shape="rect" href="#JAX-RS-References">References</a></li><li><a shape="rect"
href="#JAX-RS-Howtocontribute">How to contribute</a></li></ul>
-</div><h1 id="JAX-RS-Introduction">Introduction</h1><p><a shape="rect"
class="external-link" href="http://en.wikipedia.org/wiki/JAX-RS";
rel="nofollow">JAX-RS</a>: Java API for RESTful Web Services is a Java
programming language API that provides support in creating web services
according to the Representational State Transfer (REST) architectural
style.</p><p>CXF supports the Java API for RESTful Web Services: JAX-RS 2.0 (<a
shape="rect" class="external-link" href="http://jcp.org/en/jsr/detail?id=339";
rel="nofollow">JSR-339</a>) and JAX-RS 1.1 (<a shape="rect"
class="external-link" href="http://jcp.org/en/jsr/detail?id=311";
rel="nofollow">JSR-311</a>).</p><p><strong>New</strong>:CXF 3.2.0 SNAPSHOT
implements some parts of the early JAX-RS 2.1 Draft, in particular Reactive
Client API (CompletableFuture or RxJava based) and Server Side Events (server
only) have already been implemented.</p><p>CXF 3.0.0 completely implements
JAX-RS 2.0 including new Client API.  See <a shape=
"rect" href="jax-rs.html">below</a> for information about
compliance.</p><p>Existing JAX-RS 1.1 applications can be run with CXF
3.0.0.</p><p>CXF 2.7.0 supports most of the new features introduced in JAX-RS
2.0 (excluding 2.0 Client API for now - but note that CXF client API has been
retrofitted to support new filters, interceptors, exception classes and
Response API, plus the asynchronous client invoker API).</p><p>CXF 2.6.x
supports <a shape="rect" class="external-link"
href="https://jsr311.dev.java.net/nonav/releases/1.1/index.html";
rel="nofollow">JSR-311 API 1.1</a> and is JAX-RS TCK 1.1
compliant.</p><p>JAX-RS related demos are located under the <a shape="rect"
class="external-link"
href="http://svn.apache.org/viewvc/cxf/trunk/distribution/src/main/release/samples/jax_rs/";>samples/jax_rs
</a> directory.</p><p>This documentation will refer to JAX-RS 2.0 (JSR-339)
API.</p><p>Outstanding JAX-RS JIRA issues can be found <a shape="rect"
class="external-link" href="https://issues.apa
che.org/jira/secure/IssueNavigator.jspa?reset=true&jqlQuery=project+%3D+CXF+AND+resolution+%3D+Unresolved+AND+component+%3D+JAX-RS+ORDER+BY+priority+DESC&mode=hide">here</a>.</p><h1
id="JAX-RS-JAX-RSCompliance">JAX-RS Compliance</h1><p><span
class="confluence-anchor-link" id="JAX-RS-2_0_FINAL"></span></p><h2
id="JAX-RS-2.0Final">2.0 Final</h2><p>CXF 3.x has been updated to implement the
JAX-RS 2.0 API’s as completely as possible without access to the final
JAX-RS 2.0 TCK. <br clear="none">We have done extensive testing with JAX-RS 2.0
user applications, samples, and the preliminary TCK to make sure CXF’s
implementation is as complete and compatible as we can make it. <br
clear="none">CXF makes and will continue making the best possible effort to
have JAX-RS 2.0 and new JAX-RS version implementations technically complete and
offering an environment for running the portable JAX-RS 2.0 applications.<br
clear="none">If the final 2.0 TCK is made available to Apache, w
e will make sure CXF is updated to pass.<br clear="none">If another TCK
licensee that uses CXF’s JAX-RS 2.0 implementation in their products
finds issues with CXF’s compliance, we are more than happy to fix bugs
that are raised.</p><h2 id="JAX-RS-1.1">1.1</h2><p>Apache CXF 2.6.x passes the
final JAX-RS 1.1 TCK and is formally 1.1 compliant.</p><p>Please consult the <a
shape="rect" class="external-link"
href="http://tomee.apache.org/apache-tomee.html";>TomEE</a> documentation on the
support of Java EE related JAX-RS 1.1 options in its Apache CXF-based JAX-RS
runtime.</p><p>CXF 2.7.x and CXF 3.0.0 will fully support and run JAX-RS 1.1
applications but will not pass the JAX-RS 1.1 TCK Signature tests due
to</p><p>CXF 2.7.x and CXF 3.0.0 depending on 2.0-m10 and 2.0 final versions of
JAX-RS 2.0 API.</p><p> </p><h1
id="JAX-RS-Projectsetupandconfiguration">Project setup and
configuration</h1><h2 id="JAX-RS-Migration">Migration</h2><h3
id="JAX-RS-FromJAX-RS2.0toJAX-RS2.1">F
rom JAX-RS 2.0 to JAX-RS 2.1</h3><p>CXF 3.2.0-SNAPSHOT depends on the first
JAX-RS 2.1 API draft. All the existing JAX-RS 2.0 applications will run on CXF
3.2.0.</p><h3 id="JAX-RS-FromJAX-RS1.1to2.0">From JAX-RS 1.1 to
2.0</h3><p>JAX-RS 2.0 is backward compatible with JAX-RS 1.1. Please see <a
shape="rect" href="jax-rs-basics.html">JAX-RS Basics</a> for more information
about JAX-RS 2.0.</p><p>CXF 2.7.10 and CXF 3.0.0 are expected to support
existing JAX-RS 1.1 applications.</p><h3
id="JAX-RS-FromCXF2.7.xtoCXF3.0.0">From CXF 2.7.x to CXF 3.0.0</h3><p>Please
check the <a shape="rect"
href="http://cxf.apache.org/docs/30-migration-guide.html";>CXF 3.0.0 Migration
Guide</a> for the information about all the changes<br clear="none"> in CXF
3.0.0. Here are more details on the changes specifically affecting JAX-RS
users:</p><p>1. CXF RequestHandler and ResponseHandler filters have been
removed.</p><p>These legacy CXF filters are still supported in 2.7.x but no
longer in 3.0.0. Please use <a
shape="rect" class="external-link"
href="https://jax-rs-spec.java.net/nonav/2.0/apidocs/javax/ws/rs/container/ContainerRequestFilter.html";
rel="nofollow">ContainerRequestFilter</a> and <a shape="rect"
class="external-link"
href="https://jax-rs-spec.java.net/nonav/2.0/apidocs/javax/ws/rs/container/ContainerResponseFilter.html";
rel="nofollow">ContainerResponseFilter</a> instead. Also, <a shape="rect"
class="external-link"
href="https://jax-rs-spec.java.net/nonav/2.0/apidocs/javax/ws/rs/ext/ReaderInterceptor.html";
rel="nofollow">ReaderInterceptor</a> and <a shape="rect" class="external-link"
href="https://jax-rs-spec.java.net/nonav/2.0/apidocs/javax/ws/rs/ext/WriterInterceptor.html";
rel="nofollow">WriterInterceptor</a> can be used too.</p><p>Note, CXF filters
had org.apache.cxf.message.Message available in the signature. If CXF Message
is used in the existing CXF RequestHandler or ResponseHandler then use
"org.apache.cxf.phase.PhaseInterceptorChain.getCurrentMessage()" or "org.apache.
cxf.jaxrs.util.JAXRSUtils.getCurrentMessage()" to get a Message which has all
the contextual information available.</p><p>For example, instead of</p><div
class="code panel pdl" style="border-width: 1px;"><div class="codeContent
panelContent pdl">
+</div><h1 id="JAX-RS-Introduction">Introduction</h1><p><a shape="rect"
class="external-link" href="http://en.wikipedia.org/wiki/JAX-RS";
rel="nofollow">JAX-RS</a>: Java API for RESTful Web Services is a Java
programming language API that provides support in creating web services
according to the Representational State Transfer (REST) architectural
style.</p><p>CXF supports JAX-RS 2.1 (<a shape="rect" class="external-link"
href="https://www.jcp.org/en/jsr/detail?id=370"; rel="nofollow">JSR-370</a>),
2.0 (<a shape="rect" class="external-link"
href="http://jcp.org/en/jsr/detail?id=339"; rel="nofollow">JSR-339</a>) and 1.1
(<a shape="rect" class="external-link"
href="http://jcp.org/en/jsr/detail?id=311";
rel="nofollow">JSR-311</a>).</p><p>CXF 3.2.0 supports JAX-RS 2.1. All existing
JAX-RS 2.0 and 1.1 applications can be run with CXF 3.2.0.</p><p>CXF 3.1.x and
3.0.x support JAX-RS 2.0.  Existing JAX-RS 1.1 applications can be run
with CXF 3.1.x/3.0.x.</p><p>See <a shape="rect" href
="jax-rs.html">below</a> for more information about the
compliance.</p><p>JAX-RS related demos are located under the <a shape="rect"
class="external-link"
href="http://svn.apache.org/viewvc/cxf/trunk/distribution/src/main/release/samples/jax_rs/";>samples/jax_rs
</a> directory.</p><p>Outstanding JAX-RS JIRA issues can be found <a
shape="rect" class="external-link"
href="https://issues.apache.org/jira/secure/IssueNavigator.jspa?reset=true&jqlQuery=project+%3D+CXF+AND+resolution+%3D+Unresolved+AND+component+%3D+JAX-RS+ORDER+BY+priority+DESC&mode=hide";>here</a>.</p><h1
id="JAX-RS-JAX-RSCompliance">JAX-RS Compliance</h1><p><span
class="confluence-anchor-link" id="JAX-RS-2_0_FINAL"></span></p><h2
id="JAX-RS-2.1Final">2.1 Final</h2><p>CXF 3.2.0 has been updated to implement
the JAX-RS 2.1 API’s as completely as possible.</p><p>If another TCK
licensee that uses CXF’s JAX-RS 2.1 implementation in their products
finds issues with CXF’s compliance, we are more than ha
ppy to fix bugs that are raised.</p><h2 id="JAX-RS-2.0Final">2.0
Final</h2><p>CXF 3.1.x and CXF 3.0.x have been updated to implement the JAX-RS
2.0 API’s as completely as possible without access to the final JAX-RS
2.0 TCK. <br clear="none">We have done extensive testing with JAX-RS 2.0 user
applications, samples, and the preliminary TCK to make sure CXF’s
implementation is as complete and compatible as we can make it. <br
clear="none">CXF makes and will continue making the best possible effort to
have JAX-RS 2.0 and new JAX-RS version implementations technically complete and
offering an environment for running the portable JAX-RS 2.0 applications.<br
clear="none">If the final 2.0 TCK is made available to Apache, we will make
sure CXF is updated to pass.<br clear="none">If another TCK licensee that uses
CXF’s JAX-RS 2.0 implementation in their products finds issues with
CXF’s compliance, we are more than happy to fix bugs that are
raised.</p><h2 id="JAX-RS-1.
1">1.1</h2><p>Apache CXF 2.6.x passes the final JAX-RS 1.1 TCK and is formally
1.1 compliant.</p><p>Please consult the <a shape="rect" class="external-link"
href="http://tomee.apache.org/apache-tomee.html";>TomEE</a> documentation on the
support of Java EE related JAX-RS 1.1 options in its Apache CXF-based JAX-RS
runtime.</p><p>CXF 2.7.x and CXF 3.0.0 will fully support and run JAX-RS 1.1
applications but will not pass the JAX-RS 1.1 TCK Signature tests due
to</p><p>CXF 2.7.x and CXF 3.0.0 depending on 2.0-m10 and 2.0 final versions of
JAX-RS 2.0 API.</p><p> </p><h1
id="JAX-RS-Projectsetupandconfiguration">Project setup and
configuration</h1><h2 id="JAX-RS-Migration">Migration</h2><h3
id="JAX-RS-FromJAX-RS2.0toJAX-RS2.1">From JAX-RS 2.0 to JAX-RS
2.1</h3><p>JAX-RS 2.1 is backward compatible with JAX-RS 2.0. Please see <a
shape="rect" href="jax-rs-basics.html">JAX-RS Basics</a> for more information
about JAX-RS 2.1.</p><p>All the existing JAX-RS 2.0 and 1.1 applications will
run
on CXF 3.2.0.</p><h3 id="JAX-RS-FromJAX-RS1.1to2.0">From JAX-RS 1.1 to
2.0</h3><p>JAX-RS 2.0 is backward compatible with JAX-RS 1.1. Please see <a
shape="rect" href="jax-rs-basics.html">JAX-RS Basics</a> for more information
about JAX-RS 2.0.</p><p>CXF 3.1.x and CXF 3.0.x are expected to support the
existing JAX-RS 1.1 applications.</p><h3
id="JAX-RS-FromCXF2.7.xtoCXF3.0.xor3.1.x">From CXF 2.7.x to CXF 3.0.x or
3.1.x</h3><p>Please check the <a shape="rect"
href="http://cxf.apache.org/docs/30-migration-guide.html";>CXF 3.0.0 Migration
Guide</a> for the information about all the changes<br clear="none"> in CXF
3.0.0. Here are more details on the changes specifically affecting JAX-RS
users:</p><p>1. CXF RequestHandler and ResponseHandler filters have been
removed.</p><p>These legacy CXF filters are still supported in 2.7.x but no
longer in 3.0.0. Please use <a shape="rect" class="external-link"
href="https://jax-rs-spec.java.net/nonav/2.0/apidocs/javax/ws/rs/container/ContainerRequestFi
lter.html" rel="nofollow">ContainerRequestFilter</a> and <a shape="rect"
class="external-link"
href="https://jax-rs-spec.java.net/nonav/2.0/apidocs/javax/ws/rs/container/ContainerResponseFilter.html";
rel="nofollow">ContainerResponseFilter</a> instead. Also, <a shape="rect"
class="external-link"
href="https://jax-rs-spec.java.net/nonav/2.0/apidocs/javax/ws/rs/ext/ReaderInterceptor.html";
rel="nofollow">ReaderInterceptor</a> and <a shape="rect" class="external-link"
href="https://jax-rs-spec.java.net/nonav/2.0/apidocs/javax/ws/rs/ext/WriterInterceptor.html";
rel="nofollow">WriterInterceptor</a> can be used too.</p><p>Note, CXF filters
had org.apache.cxf.message.Message available in the signature. If CXF Message
is used in the existing CXF RequestHandler or ResponseHandler then use
"org.apache.cxf.phase.PhaseInterceptorChain.getCurrentMessage()" or
"org.apache.cxf.jaxrs.util.JAXRSUtils.getCurrentMessage()" to get a Message
which has all the contextual information available.</p><p>For exa
mple, instead of</p><div class="code panel pdl" style="border-width:
1px;"><div class="codeContent panelContent pdl">
<pre class="brush: java; gutter: false; theme: Default"
style="font-size:12px;">public class CustomRequestHandler implements
RequestHandler {
public Response handleRequest(Message message, ClassResourceInfo cri) {
}
@@ -202,28 +205,21 @@ public void upload(InputStream is) {
public void upload(@Multipart InputStream is) {
}
</pre>
-</div></div><p>Alternatively, setting a "support.type.as.multipart" contextual
property will do.</p><p>7. If the custom code throws JAX-RS
WebApplicationException with Response containing a non-null entity then custom
WebApplicationException mappers will be bypassed - another problematic
requirement, for example, the custom mappers doing the logging will miss on
such exceptions.<br clear="none"> Set CXF "support.wae.spec.optimization"
property to false to disable it.</p><p>8. In some cases the matching
sub-resource locators will be dropped to precisely meet the current JAX-RS
matching algorithm text, please see <a shape="rect" class="external-link"
href="https://issues.apache.org/jira/browse/CXF-5650";>CXF-5650</a> for more
information. Use a new "keep.subresource.candidates" property to support the
existing application if needed.</p><h3
id="JAX-RS-CXF3.1.2ProviderSortingChanges">CXF 3.1.2 Provider Sorting
Changes</h3><p>Starting from CXF 3.1.2 customMessageBodyReader (MBR), MessageB
odyWriter (MBW) and ExceptionMapper providers are sorted together with default
providers.</p><p>Before CXF 3.1.2 if a custom MBR or MBW matches the read or
write selection criteria, example, if MBR Consumes matches Content-Type and its
isReadable() returns true, then</p><p>the default providers are not even
checked. The specification however does let the custom providers be selected
only if no higher priority matching default provider is available.</p><p>For
example, suppose you have a custom StringReader which is not typed by String
but by Object. In this case the default provider which is typed by String wins.
To have the custom String provider winning one needs to type it by
String.</p><p>Check the specification or ask at the users list for more
details.</p><h3 id="JAX-RS-FromCXF2.6.xtoCXF2.7.x">From CXF 2.6.x to CXF
2.7.x</h3><p>Please check the <a shape="rect"
href="http://cxf.apache.org/docs/27-migration-guide.html";>CXF 2.7 Migration
Guide</a> for the information about all the
changes affecting the JAX-RS users</p><h2 id="JAX-RS-Mavendependencies">Maven
dependencies</h2><h3 id="JAX-RS-CXF3.0.0">CXF 3.0.0</h3><p>The
cxf-rt-frontend-jaxrs dependency is required:</p><div class="code panel pdl"
style="border-width: 1px;"><div class="codeContent panelContent pdl">
+</div></div><p>Alternatively, setting a "support.type.as.multipart" contextual
property will do.</p><p>7. If the custom code throws JAX-RS
WebApplicationException with Response containing a non-null entity then custom
WebApplicationException mappers will be bypassed - another problematic
requirement, for example, the custom mappers doing the logging will miss on
such exceptions.<br clear="none"> Set CXF "support.wae.spec.optimization"
property to false to disable it.</p><p>8. In some cases the matching
sub-resource locators will be dropped to precisely meet the current JAX-RS
matching algorithm text, please see <a shape="rect" class="external-link"
href="https://issues.apache.org/jira/browse/CXF-5650";>CXF-5650</a> for more
information. Use a new "keep.subresource.candidates" property to support the
existing application if needed.</p><h3
id="JAX-RS-CXF3.1.2ProviderSortingChanges">CXF 3.1.2 Provider Sorting
Changes</h3><p>Starting from CXF 3.1.2 customMessageBodyReader (MBR), MessageB
odyWriter (MBW) and ExceptionMapper providers are sorted together with default
providers.</p><p>Before CXF 3.1.2 if a custom MBR or MBW matches the read or
write selection criteria, example, if MBR Consumes matches Content-Type and its
isReadable() returns true, then</p><p>the default providers are not even
checked. The specification however does let the custom providers be selected
only if no higher priority matching default provider is available.</p><p>For
example, suppose you have a custom StringReader which is not typed by String
but by Object. In this case the default provider which is typed by String wins.
To have the custom String provider winning one needs to type it by
String.</p><p>Check the specification or ask at the users list for more
details.</p><p> </p><h2 id="JAX-RS-Mavendependencies">Maven
dependencies</h2><h3 id="JAX-RS-CXF3.2.0">CXF 3.2.0</h3><p>The
cxf-rt-frontend-jaxrs dependency is required:</p><div class="code panel pdl"
style="border-width: 1px;"><div c
lass="codeContent panelContent pdl">
<pre class="brush: xml; gutter: false; theme: Default"
style="font-size:12px;"> <dependency>
<groupId>org.apache.cxf</groupId>
<artifactId>cxf-rt-frontend-jaxrs</artifactId>
- <version>3.0.0-milestone1</version>
+ <version>3.2.0</version>
</dependency>
</pre>
-</div></div><p>This will in turn pull other <a shape="rect"
href="http://cxf.apache.org/project-status.html";>CXF modules</a> such
<code>cxf-core</code> and <code>cxf-rt-transports-http</code>, check <a
shape="rect" class="external-link"
href="http://svn.apache.org/repos/asf/cxf/trunk/rt/frontend/jaxrs/pom.xml";>the
pom</a> for more
information.</p><p><code>javax.ws.rs/javax.ws.rs-api/2.0</code> dependency
provides JAX-RS 2.0 Final
API.</p><pre>javax.annotation/javax.annotation-api/1.2 dependency is needed if
custom JAX-RS 2.0 filters or interceptors use a javax.annotation.Priority
annotation.</pre><p>Existing JAX-RS 1.1 applications can run in CXF
3.0.0.</p><h3 id="JAX-RS-CXF2.7.0">CXF
2.7.0</h3><p><code>javax.ws.rs/javax.ws.rs-api/2.0-m10</code> replaces
<code>javax.ws.rs/jsr311-api/1.1.1</code>. This is very close to JSR-339 Public
Release API level. Users can expect very minor differences in the Final Release
of API.</p><p>Existing JAX-RS 1.1 applications can run in CXF 2.7.x.</p>
<h3 id="JAX-RS-CXF2.6.x">CXF 2.6.x</h3><p>Please check the <a shape="rect"
href="http://cxf.apache.org/docs/26-migration-guide.html";>CXF 2.6 Migration
Guide</a> for the information about all the changes affecting the JAX-RS users.
Typically adding the frontend jaxrs dependency should be enough.</p><p>1.
<code>javax.ws.rs/jsr311-api/1.1.1</code></p><p>Optional providers (including
the default JSONProvider) are located in this module:</p><div class="code panel
pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl">
+</div></div><p>This will in turn pull other <a shape="rect"
href="http://cxf.apache.org/project-status.html";>CXF modules</a> such
<code>cxf-core</code> and <code>cxf-rt-transports-http</code>, check <a
shape="rect" class="external-link"
href="https://github.com/apache/cxf/blob/master/rt/frontend/jaxrs/pom.xml";
rel="nofollow">the pom</a> for more information.</p><p><code><a shape="rect"
class="external-link" href="http://javax.ws"; rel="nofollow">javax.ws</a>.rs/<a
shape="rect" class="external-link" href="http://javax.ws";
rel="nofollow">javax.ws</a>.rs-api/2.1</code> dependency provides JAX-RS 2.1
Final API.</p><h3 id="JAX-RS-CXF3.1.x">CXF 3.1.x</h3><p>The
cxf-rt-frontend-jaxrs dependency is required:</p><div class="code panel pdl"
style="border-width: 1px;"><div class="codeContent panelContent pdl">
<pre class="brush: xml; gutter: false; theme: Default"
style="font-size:12px;"> <dependency>
<groupId>org.apache.cxf</groupId>
- <artifactId>cxf-rt-rs-extension-providers</artifactId>
- <version>2.6.0</version>
- </dependency>
-</pre>
-</div></div><p>The Search extension is now located in</p><div class="code
panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl">
-<pre class="brush: xml; gutter: false; theme: Default"
style="font-size:12px;"> <dependency>
- <groupId>org.apache.cxf</groupId>
- <artifactId>cxf-rt-rs-extension-search</artifactId>
- <version>2.6.0</version>
+ <artifactId>cxf-rt-frontend-jaxrs</artifactId>
+ <version>3.1.12</version>
</dependency>
</pre>
-</div></div><h2 id="JAX-RS-Settinguptheclasspath">Setting up the
classpath</h2><p>If Maven is not used then the following JARs will need to be
available at the runtime classpath.</p><p>For CXF 3.0.0:</p><p>TODO</p><p>For
CXF 2.7.x:</p><p>TODO</p><h2 id="JAX-RS-CXFJAX-RSbundle">CXF JAX-RS
bundle</h2><p>Note CXF JAX-RS bundle has been removed in CXF 3.0.0. Prefer
depending on the JAX-RS frontend directly. In CXF 3.0.0 a complete CXF
all-inclusive <a shape="rect" class="external-link"
href="http://svn.apache.org/repos/asf/cxf/trunk/osgi/bundle/all/pom.xml";>bundle</a>
can still be used if really needed.</p><p>Only in CXF 2.7.x or earlier:<br
clear="none"> A standalone <a shape="rect" class="external-link"
href="http://svn.apache.org/repos/asf/cxf/branches/2.7.x-fixes/osgi/bundle/all/pom.xml";>JAX-RS
bundle</a> is available which may be of interest to users doing the JAX-RS
work only.</p><p>Please note that this bundle has a transitive Maven dependency
on the Jetty server modules. If you
are using Maven and working with other servlet containers such as Tomcat then
please add the following exclusion:</p><div class="code panel pdl"
style="border-width: 1px;"><div class="codeContent panelContent pdl">
+</div></div><p>This will in turn pull other <a shape="rect"
href="http://cxf.apache.org/project-status.html";>CXF modules</a> such
<code>cxf-core</code> and <code>cxf-rt-transports-http</code>, check <a
shape="rect" class="external-link"
href="https://github.com/apache/cxf/blob/3.1.x-fixes/rt/frontend/jaxrs/pom.xml";
rel="nofollow">the pom</a> for more
information.</p><p><code>javax.ws.rs/javax.ws.rs-api/2.0</code> dependency
provides JAX-RS 2.0 Final
API.</p><pre>javax.annotation/javax.annotation-api/1.2 dependency is needed if
custom JAX-RS 2.0 filters or interceptors use a javax.annotation.Priority
annotation.</pre><p>Existing JAX-RS 1.1 applications can run in CXF 3.1.x and
CXF 3.0.x.</p><h2 id="JAX-RS-CXFJAX-RSbundle">CXF JAX-RS bundle</h2><p>Note CXF
JAX-RS bundle has been removed in CXF 3.0.0. Prefer depending on the JAX-RS
frontend directly. In CXF 3.0.0 a complete CXF all-inclusive <a shape="rect"
class="external-link" href="http://svn.apache.org/repos/asf/cxf/trunk/osgi/bund
le/all/pom.xml">bundle</a> can still be used if really needed.</p><p>Only in
CXF 2.7.x or earlier:<br clear="none"> A standalone <a shape="rect"
class="external-link"
href="http://svn.apache.org/repos/asf/cxf/branches/2.7.x-fixes/osgi/bundle/all/pom.xml";>JAX-RS
bundle</a> is available which may be of interest to users doing the JAX-RS
work only.</p><p>Please note that this bundle has a transitive Maven dependency
on the Jetty server modules. If you are using Maven and working with other
servlet containers such as Tomcat then please add the following
exclusion:</p><div class="code panel pdl" style="border-width: 1px;"><div
class="codeContent panelContent pdl">
<pre class="brush: xml; gutter: false; theme: Default"
style="font-size:12px;"> <dependency>
<groupId>org.apache.cxf</groupId>
<artifactId>cxf-bundle-jaxrs</artifactId>
@@ -237,7 +233,7 @@ public void upload(@Multipart InputStrea
</dependency>
</pre>
-</div></div><h1 id="JAX-RS-WhatisNew">What is New</h1><ul><li>Complete support
for JAX-RS 2.0, please see <a shape="rect" href="jax-rs-basics.html">JAX-RS
Basics</a> for more information</li><li>Bean Validation 1.1 Support, please see
<a shape="rect"
href="http://cxf.apache.org/docs/validationfeature.html";>http://cxf.apache.org/docs/validationfeature.html</a>
for more information</li><li><a shape="rect"
href="http://cxf.apache.org/docs/swagger2feature.html";>Swagger Feature</a> for
generating <a shape="rect" class="external-link"
href="http://swagger.io/specification/"; rel="nofollow">Swagger API</a>
documentation from JAX-RS endpoints</li></ul><h1
id="JAX-RS-GettingStartedwithJAX-RS">Getting Started with JAX-RS</h1><h2
id="JAX-RS-UnderstandingtheBasics">Understanding the Basics</h2><p>You are
encouraged to read <a shape="rect" class="external-link"
href="http://jcp.org/en/jsr/detail?id=339"; rel="nofollow">JSR-339</a>
specification to find out information not covered by this documenta
tion. The specification introduces many terms such as root resources, resource
methods, sub-resources and sub-resource locators, message body readers and
writers. JAX-RS 2.0 additionally introduces filters, interceptors, new client
API, features, new exception classes, server-side support for asynchronous
invocations.</p><p>Please see the <a shape="rect"
href="jax-rs-basics.html">JAX-RS Basics</a> page for more information.</p><h2
id="JAX-RS-SupportforDataBindings">Support for Data Bindings</h2><p>JAX-RS
MessageBodyReader and MessageBodyWriter can be used to create data bindings for
reading and writing data in a number of different formats. Compliant JAX-RS
implementations are expected to support JAXB-annotated beans, JAXP Source
objects, InputStreams, etc.</p><p>In addition, CXF JAX-RS lets users reuse
existing CXF DataBindings for working with JAXB, XBeans, Aegis and
SDO.</p><p>Please see the <a shape="rect"
href="jax-rs-data-bindings.html">JAX-RS Data Bindings</a> page for more i
nformation.</p><h2 id="JAX-RS-HowRequestURIisMatched">How Request URI is
Matched</h2><p>Lets assume you have a web application called 'rest' (example, a
'rest.war' archive). CXFServlet's url-pattern is "/test/*". Finally,
jaxrs:server's address is "/bar".</p><p>Requests like /rest/test/bar or
/rest/test/bar/baz will be delivered to one of the resource classes in a given
jaxrs:server endpoint. For the former request to be handled, a resource class
with @Path("/") should be available, in the latter case - at least @Path("/")
or a more specific @Path("/baz").</p><p>The same requirement can be expressed
by having a CXFServlet with "/*" and jaxrs:server with "/test/bar".</p><p>When
both CXFServlet and jaxrs:server use "/" then it's a root resource class which
should provide a @Path with at least "/test/bar" for the above requests to be
matched.</p><p>Generally, it can be a good idea to specify the URI segments
which are more likely to change now and then with CXFServlets or jaxrs:server.
</p><h2 id="JAX-RS-ClientAPI">Client API</h2><p>CXF 3.0.0 implements JAX-RS
2.0 Client API.</p><p>CXF 2.7.x or earlier provides a comprehensive support for
developing RESTful clients by supporting 3 flavors of the client API:
proxy-based, HTTP-centric and XML-centric. CXF-specific client API is supported
alongside new JAX-RS 2.0 Client API in CXF 3.0.0.</p><p>Please see the <a
shape="rect" href="jax-rs-client-api.html">JAX-RS Client API</a> page for more
information.</p><h2 id="JAX-RS-BeanValidation">Bean Validation</h2><p>Bean
Validation 1.1 is supported since CXF 3.0.0-milestone1. Please see the <a
shape="rect"
href="http://cxf.apache.org/docs/validationfeature.html";>http://cxf.apache.org/docs/validationfeature.html</a>
for more information.</p><h2
id="JAX-RS-Filters,InterceptorsandInvokers">Filters, Interceptors and
Invokers</h2><p>It is possible to intercept and modify the inbound and outbound
calls with the help of CXF JAX-RS filters and/or CXF interceptors.
Additionally, custo
m invokers offer an option to intercept a call immediately before a service
bean is invoked.</p><p>Please see the <a shape="rect"
href="jax-rs-filters.html">JAX-RS Filters</a> page for more
information.</p><p>Please see the <a shape="rect"
href="jax-rs-basics.html">JAX-RS Basics</a> page for more information about new
JAX-RS 2.0 filters and interceptors available in CXF 2.7.x and 3.0.0.</p><h2
id="JAX-RS-ServicelistingsandWADLsupport">Service listings and WADL
support</h2><p><strong>New</strong>: Swagger feature has been
introduced.</p><p>CXF JAX-RS supports <a shape="rect" class="external-link"
href="http://www.w3.org/Submission/wadl"; rel="nofollow">WADL</a>. CXF JAX-RS
service endpoints can be listed in the service listings page and users can
check the WADL documents.</p><p>Please see the <a shape="rect"
href="jaxrs-services-description.html">JAXRS Services Description</a> page for
more information.</p><h2 id="JAX-RS-ConfiguringJAX-RSservices">Configuring
JAX-RS services</h2><p>JA
X-RS services can be configured programmatically, using Blueprint, Spring or
CXFNonSpringJAXRSServlet.</p><p>Please see the <a shape="rect"
href="jaxrs-services-configuration.html">JAXRS Services Configuration</a> page
for more information.</p><h2 id="JAX-RS-Testing">Testing</h2><p>JAX-RS services
can be easily tested using the embedded Jetty or CXF Local Transport.<br
clear="none"> Please see the <a shape="rect"
href="https://cwiki.apache.org/confluence/display/CXF20DOC/JAXRS+Testing";>JAXRS
Testing</a> page for more information.</p><h2
id="JAX-RS-Debugging">Debugging</h2><p>One may want to use a browser to test
how a given HTTP resource reacts to different HTTP Accept or Accept-Language
header values and request methods. For example, if a resource class supports a
"/resource" URI then one can test the resource class using one of the following
queries :</p><p><code>> GET /resource.xml</code> <br clear="none">
<code>> GET /resource.en</code></p><p>The runtime will replace '.xml
' or '.en' with an appropriate header value. For it to know the type or
language value associated with a given URI suffix, some configuration needs to
be done. Here's an example of how it can be done with Spring:</p><div
class="code panel pdl" style="border-width: 1px;"><div class="codeContent
panelContent pdl">
+</div></div><h1 id="JAX-RS-WhatisNew">What is New</h1><ul><li>Complete support
for JAX-RS 2.1, please see <a shape="rect" href="jax-rs-basics.html">JAX-RS
Basics</a> for more information</li><li><a shape="rect"
href="jax-rs-nio.html">JAX-RS NIO</a> extension based on the early JAX-RS 2.1
API prototype.</li><li><a shape="rect" href="jax-rs-rxjava.html">JAX-RS
RxJava</a> Observable support: as a standard JAX-RS 2.1 RxInvoker client
provider and returning it asynchronously from the resource methods (CXF
extension) </li><li>Complete support for JAX-RS 2.0, please see <a
shape="rect" href="jax-rs-basics.html">JAX-RS Basics</a> for more
information</li><li>Bean Validation 1.1 Support, please see <a shape="rect"
href="http://cxf.apache.org/docs/validationfeature.html";>http://cxf.apache.org/docs/validationfeature.html</a>
for more information</li><li><a shape="rect"
href="http://cxf.apache.org/docs/swagger2feature.html";>Swagger Feature</a> for
generating <a shape="rect" class="external
-link" href="http://swagger.io/specification/"; rel="nofollow">Swagger API</a>
documentation from JAX-RS endpoints</li></ul><h1
id="JAX-RS-GettingStartedwithJAX-RS">Getting Started with JAX-RS</h1><h2
id="JAX-RS-UnderstandingtheBasics">Understanding the Basics</h2><p>You are
encouraged to read JAX-RS 2.1 <a shape="rect" class="external-link"
href="http://jcp.org/en/jsr/detail?id=370"; rel="nofollow">JSR-370</a>
specification to find out the information not covered by this documentation.
The specification enhances JAX-RS 2.0 by introducing a support for Reactive
Client API extensions, Server Sent Events (client and server), returning
CompletableFuture from the resource methods and the sub-resource classes (as
opposed to instances) from the sub-resource locators.</p><p>You are also
encouraged to read JAX-RS 2.0 <a shape="rect" class="external-link"
href="http://jcp.org/en/jsr/detail?id=339"; rel="nofollow">JSR-339</a>
specification to find out the information not covered by this document
ation. The specification introduces many terms such as root resources,
resource methods, sub-resources and sub-resource locators, message body readers
and writers. JAX-RS 2.0 additionally introduces filters, interceptors, new
client API, features, new exception classes, server-side support for
asynchronous invocations.</p><p>Please see the <a shape="rect"
href="jax-rs-basics.html">JAX-RS Basics</a> page for more information.</p><h2
id="JAX-RS-SupportforDataBindings">Support for Data Bindings</h2><p>JAX-RS
MessageBodyReader and MessageBodyWriter can be used to create data bindings for
reading and writing data in a number of different formats. Compliant JAX-RS
implementations are expected to support JAXB-annotated beans, JAXP Source
objects, InputStreams, etc.</p><p>In addition, CXF JAX-RS lets users reuse
existing CXF DataBindings for working with JAXB, XBeans, Aegis and
SDO.</p><p>Please see the <a shape="rect"
href="jax-rs-data-bindings.html">JAX-RS Data Bindings</a> page for more
information.</p><h2 id="JAX-RS-HowRequestURIisMatched">How Request URI is
Matched</h2><p>Lets assume you have a web application called 'rest' (example, a
'rest.war' archive). CXFServlet's url-pattern is "/test/*". Finally,
jaxrs:server's address is "/bar".</p><p>Requests like /rest/test/bar or
/rest/test/bar/baz will be delivered to one of the resource classes in a given
jaxrs:server endpoint. For the former request to be handled, a resource class
with @Path("/") should be available, in the latter case - at least @Path("/")
or a more specific @Path("/baz").</p><p>The same requirement can be expressed
by having a CXFServlet with "/*" and jaxrs:server with "/test/bar".</p><p>When
both CXFServlet and jaxrs:server use "/" then it's a root resource class which
should provide a @Path with at least "/test/bar" for the above requests to be
matched.</p><p>Generally, it can be a good idea to specify the URI segments
which are more likely to change now and then with CXFServlets or jaxrs:server
.</p><h2 id="JAX-RS-ClientAPI">Client API</h2><p>CXF 3.0.0 implements JAX-RS
2.0 Client API.</p><p>CXF 2.7.x or earlier provides a comprehensive support for
developing RESTful clients by supporting 3 flavors of the client API:
proxy-based, HTTP-centric and XML-centric. CXF-specific client API is supported
alongside new JAX-RS 2.0 Client API in CXF 3.0.0.</p><p>Please see the <a
shape="rect" href="jax-rs-client-api.html">JAX-RS Client API</a> page for more
information.</p><h2 id="JAX-RS-BeanValidation">Bean Validation</h2><p>Bean
Validation 1.1 is supported since CXF 3.0.0-milestone1. Please see the <a
shape="rect"
href="http://cxf.apache.org/docs/validationfeature.html";>http://cxf.apache.org/docs/validationfeature.html</a>
for more information.</p><h2
id="JAX-RS-Filters,InterceptorsandInvokers">Filters, Interceptors and
Invokers</h2><p>It is possible to intercept and modify the inbound and outbound
calls with the help of CXF JAX-RS filters and/or CXF interceptors.
Additionally, cust
om invokers offer an option to intercept a call immediately before a service
bean is invoked.</p><p>Please see the <a shape="rect"
href="jax-rs-filters.html">JAX-RS Filters</a> page for more
information.</p><p>Please see the <a shape="rect"
href="jax-rs-basics.html">JAX-RS Basics</a> page for more information about new
JAX-RS 2.0 filters and interceptors available in CXF 2.7.x and 3.0.0.</p><h2
id="JAX-RS-ServicelistingsandWADLsupport">Service listings and WADL
support</h2><p><strong>New</strong>: Swagger feature has been
introduced.</p><p>CXF JAX-RS supports <a shape="rect" class="external-link"
href="http://www.w3.org/Submission/wadl"; rel="nofollow">WADL</a>. CXF JAX-RS
service endpoints can be listed in the service listings page and users can
check the WADL documents.</p><p>Please see the <a shape="rect"
href="jaxrs-services-description.html">JAXRS Services Description</a> page for
more information.</p><h2 id="JAX-RS-ConfiguringJAX-RSservices">Configuring
JAX-RS services</h2><p>J
AX-RS services can be configured programmatically, using Blueprint, Spring or
CXFNonSpringJAXRSServlet.</p><p>Please see the <a shape="rect"
href="jaxrs-services-configuration.html">JAXRS Services Configuration</a> page
for more information.</p><h2 id="JAX-RS-Testing">Testing</h2><p>JAX-RS services
can be easily tested using the embedded Jetty or CXF Local Transport.<br
clear="none"> Please see the <a shape="rect"
href="https://cwiki.apache.org/confluence/display/CXF20DOC/JAXRS+Testing";>JAXRS
Testing</a> page for more information.</p><h2
id="JAX-RS-Debugging">Debugging</h2><p>One may want to use a browser to test
how a given HTTP resource reacts to different HTTP Accept or Accept-Language
header values and request methods. For example, if a resource class supports a
"/resource" URI then one can test the resource class using one of the following
queries :</p><p><code>> GET /resource.xml</code> <br clear="none">
<code>> GET /resource.en</code></p><p>The runtime will replace '.xm
l' or '.en' with an appropriate header value. For it to know the type or
language value associated with a given URI suffix, some configuration needs to
be done. Here's an example of how it can be done with Spring:</p><div
class="code panel pdl" style="border-width: 1px;"><div class="codeContent
panelContent pdl">
<pre class="brush: xml; gutter: false; theme: Default"
style="font-size:12px;"> <jaxrs:server id="customerService" address="/">
<jaxrs:serviceBeans>
<bean class="org.apache.cxf.jaxrs.systests.CustomerService" />
Modified: websites/production/cxf/content/docs/security-configuration.html
==============================================================================
--- websites/production/cxf/content/docs/security-configuration.html (original)
+++ websites/production/cxf/content/docs/security-configuration.html Tue Aug 29
11:11:59 2017
@@ -107,7 +107,7 @@ Apache CXF -- Security Configuration
<td height="100%">
<!-- Content -->
<div class="wiki-content">
-<div id="ConfluenceContent"><h2
id="SecurityConfiguration-Backgroundtocommonsecurityconfiguration">Background
to common security configuration</h2><p>From Apache CXF 3.1.0, the <a
shape="rect" href="ws-securitypolicy.html">WS-SecurityPolicy</a> and the <a
shape="rect" href="jax-rs-xml-security.html">XML Security</a> (JAX-RS)
components in CXF share a common set of configuration tags. Previously, the
configuration tags were all defined in the SecurityConstants class in the
cxf-rt-ws-security module. The JAX-RS XML Security component then referenced
these configuration tags directly, which meant that the XML Security component
had to have a dependency on a SOAP module, which was not ideal.</p><h2
id="SecurityConfiguration-NewconfigurationtagsinApacheCXF3.1.0">New
configuration tags in Apache CXF 3.1.0</h2><p>From Apache CXF 3.1.0, the
cxf-rt-security module is now shared between both the WS-Security and JAX-RS
XML Security modules, and contains a SecurityConstants class that defines s
ecurity constants used by both stacks. These configuration tags are exactly
the same as a set of previous configuration tags found in the WS-Security
SecurityConstants class in previous releases, except that the prefix is now
"security" (was "ws-security"). Here are the new set of configuration
tags:</p><h4 id="SecurityConfiguration-Userproperties">User properties</h4><div
class="table-wrap"><table class="confluenceTable"><tbody><tr><td colspan="1"
rowspan="1" class="confluenceTd"><p>security.username</p></td><td colspan="1"
rowspan="1" class="confluenceTd"><p>The user's name. It is used differently by
each of the Security functions, see <a shape="rect"
href="http://cxf.apache.org/javadoc/latest/org/apache/cxf/ws/security/SecurityConstants.html#USERNAME";>here</a>
for more information.</p></td></tr><tr><td colspan="1" rowspan="1"
class="confluenceTd"><p>security.password</p></td><td colspan="1" rowspan="1"
class="confluenceTd"><p>The user's password when "security.callback-handler" i
s not defined. It is currently only used for the case of adding a password to
a UsernameToken.</p></td></tr><tr><td colspan="1" rowspan="1"
class="confluenceTd"><p>security.signature.username</p></td><td colspan="1"
rowspan="1" class="confluenceTd"><p>The user's name for signature. It is used
as the alias name in the keystore to get the user's cert and private key for
signature. See <a shape="rect"
href="http://cxf.apache.org/javadoc/latest/org/apache/cxf/ws/security/SecurityConstants.html#SIGNATURE_USERNAME";>here</a>
for more information.</p></td></tr><tr><td colspan="1" rowspan="1"
class="confluenceTd"><p>security.encryption.username</p></td><td colspan="1"
rowspan="1" class="confluenceTd"><p>The user's name for encryption. It is used
as the alias name in the keystore to get the user's public key for encryption.
See <a shape="rect"
href="http://cxf.apache.org/javadoc/latest/org/apache/cxf/ws/security/SecurityConstants.html#ENCRYPT_USERNAME";>here</a>
for more information.</p></td><
/tr></tbody></table></div><h4
id="SecurityConfiguration-CallbackClassandCryptoproperties">Callback Class and
Crypto properties</h4><div class="table-wrap"><table
class="confluenceTable"><tbody><tr><td colspan="1" rowspan="1"
class="confluenceTd"><p>security.callback-handler</p></td><td colspan="1"
rowspan="1" class="confluenceTd"><p>The CallbackHandler <a shape="rect"
href="http://cxf.apache.org/javadoc/latest/org/apache/cxf/ws/security/SecurityConstants.html#CALLBACK_HANDLER";>implementation</a>
class used to obtain passwords.</p></td></tr><tr><td colspan="1" rowspan="1"
class="confluenceTd"><p>security.saml-callback-handler</p></td><td colspan="1"
rowspan="1" class="confluenceTd"><p>The SAML CallbackHandler <a shape="rect"
href="http://cxf.apache.org/javadoc/latest/org/apache/cxf/ws/security/SecurityConstants.html#SAML_CALLBACK_HANDLER";>implementation</a>
class used to construct SAML Assertions.</p></td></tr><tr><td colspan="1"
rowspan="1" class="confluenceTd"><p>security.signature
.properties</p></td><td colspan="1" rowspan="1" class="confluenceTd"><p>The
Crypto property <a shape="rect"
href="http://cxf.apache.org/javadoc/latest/org/apache/cxf/ws/security/SecurityConstants.html#SIGNATURE_PROPERTIES";>configuration</a>
to use for signature, if "security.signature.crypto" is not set
instead.</p></td></tr><tr><td colspan="1" rowspan="1"
class="confluenceTd"><p>security.encryption.properties</p></td><td colspan="1"
rowspan="1" class="confluenceTd"><p>The Crypto property <a shape="rect"
href="http://cxf.apache.org/javadoc/latest/org/apache/cxf/ws/security/SecurityConstants.html#ENCRYPT_PROPERTIES";>configuration</a>
to use for encryption, if "security.encryption.crypto" is not set
instead.</p></td></tr><tr><td colspan="1" rowspan="1"
class="confluenceTd"><p>security.signature.crypto</p></td><td colspan="1"
rowspan="1" class="confluenceTd"><p>A Crypto <a shape="rect"
class="external-link"
href="http://ws.apache.org/wss4j/apidocs/org/apache/ws/security/components/cryp
to/Crypto.html">object</a> to be used for signature. If this is not defined
then "security.signature.properties" is used instead.</p></td></tr><tr><td
colspan="1" rowspan="1"
class="confluenceTd"><p>security.encryption.crypto</p></td><td colspan="1"
rowspan="1" class="confluenceTd"><p>A Crypto <a shape="rect"
class="external-link"
href="http://ws.apache.org/wss4j/apidocs/org/apache/ws/security/components/crypto/Crypto.html";>object</a>
to be used for encryption. If this is not defined then
"security.encryption.properties" is used
instead.</p></td></tr></tbody></table></div><p><strong>Note:</strong> for
Symmetric bindings that specify a protection token, the security-encryption
properties are used.</p><h4
id="SecurityConfiguration-BooleanSecurityconfigurationtags,e.g.thevalueshouldbe"true"or"false".">Boolean
Security configuration tags, e.g. the value should be "true" or
"false".</h4><div class="table-wrap"><table
class="confluenceTable"><tbody><tr><td colspan="1"
rowspan="1" class="confluenceTd"><p>constant</p></td><td colspan="1"
rowspan="1" class="confluenceTd"><p>default</p></td><td colspan="1" rowspan="1"
class="confluenceTd"><p>definition</p></td></tr><tr><td colspan="1" rowspan="1"
class="confluenceTd"><p>security.enableRevocation</p></td><td colspan="1"
rowspan="1" class="confluenceTd"><p>false</p></td><td colspan="1" rowspan="1"
class="confluenceTd"><p>Whether to enable Certificate Revocation List (CRL)
checking or not when verifying trust in a certificate.</p></td></tr><tr><td
colspan="1" rowspan="1"
class="confluenceTd">security.enable.unsigned-saml-assertion.principal</td><td
colspan="1" rowspan="1" class="confluenceTd">false</td><td colspan="1"
rowspan="1" class="confluenceTd">Whether to allow unsigned saml assertions as
SecurityContext Principals. The default is false.<p>Note that "unsigned" refers
to an internal signature. Even if the token is signed by an external signature
(as per the "sender-vouches" requirement), this boole
an must still be configured if you want to use the token to set up the
security context.</p></td></tr><tr><td colspan="1" rowspan="1"
class="confluenceTd">security.validate.saml.subject.conf</td><td colspan="1"
rowspan="1" class="confluenceTd">true</td><td colspan="1" rowspan="1"
class="confluenceTd">Whether to validate the SubjectConfirmation requirements
of a received SAML Token.</td></tr><tr><td colspan="1" rowspan="1"
class="confluenceTd">security.sc.jaas-subject</td><td colspan="1" rowspan="1"
class="confluenceTd">true</td><td colspan="1" rowspan="1"
class="confluenceTd">Set this to "false" if security context must not be
created from JAAS Subject.</td></tr><tr><td colspan="1" rowspan="1"
class="confluenceTd">security.validate.audience-restriction</td><td colspan="1"
rowspan="1" class="confluenceTd">(varies)</td><td colspan="1" rowspan="1"
class="confluenceTd"><p>If this is set to "true", then IF the SAML Token
contains Audience Restriction URIs, one of them must match either t
he request URL or the Service QName. The default is "true" for CXF 3.0.x, and
"false" for 2.7.x.</p></td></tr></tbody></table></div><h4
id="SecurityConfiguration-Non-booleanSecurityConfigurationparameters">Non-boolean
Security Configuration parameters</h4><div class="table-wrap"><table
class="confluenceTable"><tbody><tr><td colspan="1" rowspan="1"
class="confluenceTd"><p>security.saml-role-attributename</p></td><td
colspan="1" rowspan="1" class="confluenceTd"><p>The attribute URI of the SAML
AttributeStatement where the role information is stored. The default is "<a
shape="rect" class="external-link"
href="http://schemas.xmlsoap.org/ws/2005/05/identity/claims/role";
rel="nofollow">http://schemas.xmlsoap.org/ws/2005/05/identity/claims/role</a>".</p></td></tr><tr><td
colspan="1" rowspan="1"
class="confluenceTd"><p>security.subject.cert.constraints</p></td><td
colspan="1" rowspan="1" class="confluenceTd"><p>A comma separated String of
regular expressions which will be applied to the sub
ject DN of the certificate used for signature validation, after trust
verification of the certificate chain associated with the certificate. These
constraints are not used when the certificate is contained in the keystore
(direct trust).</p></td></tr></tbody></table></div><h4
id="SecurityConfiguration-STSClientConfigurationtags">STS Client Configuration
tags</h4><p><strong>Note: </strong>From CXF 3.1.3 onwards. Prior to CXF 3.1.3
these tags had a "ws-" prefix. The older tags will still work for backwards
compatibility reasons.</p><div class="table-wrap"><table
class="confluenceTable"><tbody><tr><td colspan="1" rowspan="1"
class="confluenceTd"><p>security.sts.client</p></td><td colspan="1" rowspan="1"
class="confluenceTd"><p>A reference to the STSClient class used to communicate
with the STS.</p></td></tr><tr><td colspan="1" rowspan="1"
class="confluenceTd"><p>security.sts.applies-to</p></td><td colspan="1"
rowspan="1" class="confluenceTd"><p>The "AppliesTo" address to send to the ST
S. The default is the endpoint address of the service
provider.</p></td></tr><tr><td colspan="1" rowspan="1"
class="confluenceTd"><p>security.sts.token.usecert</p></td><td colspan="1"
rowspan="1" class="confluenceTd"><p>If true, writes out an X509Certificate
structure in UseKey/KeyInfo. If false (the default), writes out a KeyValue
structure instead.</p></td></tr><tr><td colspan="1" rowspan="1"
class="confluenceTd"><p>security.sts.token.do.cancel</p></td><td colspan="1"
rowspan="1" class="confluenceTd"><p>Whether to cancel a token when using
SecureConversation after successful invocation. The default is
"false".</p></td></tr><tr><td colspan="1" rowspan="1"
class="confluenceTd">security.issue.after.failed.renew</td><td colspan="1"
rowspan="1" class="confluenceTd"><p>Whether to fall back to calling "issue"
after failing to renew an expired token. The default is
"true".</p></td></tr><tr><td colspan="1" rowspan="1"
class="confluenceTd"><p>security.cache.issued.token.in.endpoint</p></td>
<td colspan="1" rowspan="1" class="confluenceTd"><p>Set this to "false" to not
cache a SecurityToken per proxy object in the IssuedTokenInterceptorProvider.
This should be done if a token is being retrieved from an STS in an
intermediary. The default value is "true".</p></td></tr><tr><td colspan="1"
rowspan="1"
class="confluenceTd"><p>security.sts.disable-wsmex-call-using-epr-address</p></td><td
colspan="1" rowspan="1" class="confluenceTd"><p>Whether to avoid STS client
trying send WS-MetadataExchange call using STS EPR WSA address when the
endpoint contract contains no WS-MetadataExchange info. The default value is
"false".</p></td></tr><tr><td colspan="1" rowspan="1"
class="confluenceTd"><p>security.sts.token.crypto</p></td><td colspan="1"
rowspan="1" class="confluenceTd"><p>A Crypto object to be used for the STS. See
<a shape="rect"
href="http://cxf.apache.org/javadoc/latest/org/apache/cxf/ws/security/SecurityConstants.html#STS_TOKEN_CRYPTO";>here</a>
for more information.</p></td
></tr><tr><td colspan="1" rowspan="1"
>class="confluenceTd"><p>security.sts.token.properties</p></td><td colspan="1"
>rowspan="1" class="confluenceTd"><p>The Crypto property configuration to use
>for the STS. See <a shape="rect"
>href="http://cxf.apache.org/javadoc/latest/org/apache/cxf/ws/security/SecurityConstants.html#STS_TOKEN_PROPERTIES";>here</a>
> for more information.</p></td></tr><tr><td colspan="1" rowspan="1"
>class="confluenceTd"><p>security.sts.token.username</p></td><td colspan="1"
>rowspan="1" class="confluenceTd"><p>The alias name in the keystore to get the
>user's public key to send to the STS for the PublicKey KeyType
>case.</p></td></tr><tr><td colspan="1" rowspan="1"
>class="confluenceTd"><p>security.sts.token.act-as</p></td><td colspan="1"
>rowspan="1" class="confluenceTd"><p>The token to be sent to the STS in an
>"ActAs" field. See <a shape="rect"
>href="http://cxf.apache.org/javadoc/latest/org/apache/cxf/ws/security/SecurityConstants.html#STS_TOKEN_ACT_AS";>here</a>
> for more
information.</p></td></tr><tr><td colspan="1" rowspan="1"
class="confluenceTd"><p>security.sts.token.on-behalf-of</p></td><td colspan="1"
rowspan="1" class="confluenceTd"><p>The token to be sent to the STS in an
"OnBehalfOf" field. See <a shape="rect"
href="http://cxf.apache.org/javadoc/latest/org/apache/cxf/ws/security/SecurityConstants.html#STS_TOKEN_ON_BEHALF_OF";>here</a>
for more information.</p></td></tr><tr><td colspan="1" rowspan="1"
class="confluenceTd">security.issue.after.failed.renew</td><td colspan="1"
rowspan="1" class="confluenceTd">Whether to call "Issue" if a token "Renew"
fails. Some STSs do not support the renew binding. Defaults to
"true".</td></tr><tr><td colspan="1" rowspan="1"
class="confluenceTd">security.sts.token.imminent-expiry-value</td><td
colspan="1" rowspan="1" class="confluenceTd">The value in seconds within which
a token is considered to be expired by the client, i.e. it is considered to be
expired if it will expire in a time less than the value speci
fied by this tag. The default value is "10" for CXF 3.0.2+, and "0" for CXF
2.7.13+.</td></tr><tr><td colspan="1" rowspan="1"
class="confluenceTd">security.sts.token.cacher.impl <strong>CXF
3.1.11</strong></td><td colspan="1" rowspan="1" class="confluenceTd"><p>An
implementation of the STSTokenCacher interface, if you want to plug in custom
caching behaviour for STS clients. The default value is the
DefaultSTSTokenCacher.</p></td></tr></tbody></table></div><h2
id="SecurityConfiguration-Backwardscompatibility">Backwards
compatibility</h2><p>Users of Apache CXF prior to 3.1.0 do not need to make any
adjustment to their code or spring files. The older "ws-" prefix associated
with the configuration tags above will continue to be accepted.</p></div>
+<div id="ConfluenceContent"><h2
id="SecurityConfiguration-Backgroundtocommonsecurityconfiguration">Background
to common security configuration</h2><p>From Apache CXF 3.1.0, the <a
shape="rect" href="ws-securitypolicy.html">WS-SecurityPolicy</a> and the <a
shape="rect" href="jax-rs-xml-security.html">XML Security</a> (JAX-RS)
components in CXF share a common set of configuration tags. Previously, the
configuration tags were all defined in the SecurityConstants class in the
cxf-rt-ws-security module. The JAX-RS XML Security component then referenced
these configuration tags directly, which meant that the XML Security component
had to have a dependency on a SOAP module, which was not ideal.</p><h2
id="SecurityConfiguration-NewconfigurationtagsinApacheCXF3.1.0">New
configuration tags in Apache CXF 3.1.0</h2><p>From Apache CXF 3.1.0, the
cxf-rt-security module is now shared between both the WS-Security and JAX-RS
XML Security modules, and contains a SecurityConstants class that defines s
ecurity constants used by both stacks. These configuration tags are exactly
the same as a set of previous configuration tags found in the WS-Security
SecurityConstants class in previous releases, except that the prefix is now
"security" (was "ws-security"). Here are the new set of configuration
tags:</p><h4 id="SecurityConfiguration-Userproperties">User properties</h4><div
class="table-wrap"><table class="confluenceTable"><tbody><tr><td colspan="1"
rowspan="1" class="confluenceTd"><p>security.username</p></td><td colspan="1"
rowspan="1" class="confluenceTd"><p>The user's name. It is used differently by
each of the Security functions, see <a shape="rect"
href="http://cxf.apache.org/javadoc/latest/org/apache/cxf/ws/security/SecurityConstants.html#USERNAME";>here</a>
for more information.</p></td></tr><tr><td colspan="1" rowspan="1"
class="confluenceTd"><p>security.password</p></td><td colspan="1" rowspan="1"
class="confluenceTd"><p>The user's password when "security.callback-handler" i
s not defined. It is currently only used for the case of adding a password to
a UsernameToken.</p></td></tr><tr><td colspan="1" rowspan="1"
class="confluenceTd"><p>security.signature.username</p></td><td colspan="1"
rowspan="1" class="confluenceTd"><p>The user's name for signature. It is used
as the alias name in the keystore to get the user's cert and private key for
signature. See <a shape="rect"
href="http://cxf.apache.org/javadoc/latest/org/apache/cxf/ws/security/SecurityConstants.html#SIGNATURE_USERNAME";>here</a>
for more information.</p></td></tr><tr><td colspan="1" rowspan="1"
class="confluenceTd"><p>security.encryption.username</p></td><td colspan="1"
rowspan="1" class="confluenceTd"><p>The user's name for encryption. It is used
as the alias name in the keystore to get the user's public key for encryption.
See <a shape="rect"
href="http://cxf.apache.org/javadoc/latest/org/apache/cxf/ws/security/SecurityConstants.html#ENCRYPT_USERNAME";>here</a>
for more information.</p></td><
/tr></tbody></table></div><h4
id="SecurityConfiguration-CallbackClassandCryptoproperties">Callback Class and
Crypto properties</h4><div class="table-wrap"><table
class="confluenceTable"><tbody><tr><td colspan="1" rowspan="1"
class="confluenceTd"><p>security.callback-handler</p></td><td colspan="1"
rowspan="1" class="confluenceTd"><p>The CallbackHandler <a shape="rect"
href="http://cxf.apache.org/javadoc/latest/org/apache/cxf/ws/security/SecurityConstants.html#CALLBACK_HANDLER";>implementation</a>
class used to obtain passwords.</p></td></tr><tr><td colspan="1" rowspan="1"
class="confluenceTd"><p>security.saml-callback-handler</p></td><td colspan="1"
rowspan="1" class="confluenceTd"><p>The SAML CallbackHandler <a shape="rect"
href="http://cxf.apache.org/javadoc/latest/org/apache/cxf/ws/security/SecurityConstants.html#SAML_CALLBACK_HANDLER";>implementation</a>
class used to construct SAML Assertions.</p></td></tr><tr><td colspan="1"
rowspan="1" class="confluenceTd"><p>security.signature
.properties</p></td><td colspan="1" rowspan="1" class="confluenceTd"><p>The
Crypto property <a shape="rect"
href="http://cxf.apache.org/javadoc/latest/org/apache/cxf/ws/security/SecurityConstants.html#SIGNATURE_PROPERTIES";>configuration</a>
to use for signature, if "security.signature.crypto" is not set
instead.</p></td></tr><tr><td colspan="1" rowspan="1"
class="confluenceTd"><p>security.encryption.properties</p></td><td colspan="1"
rowspan="1" class="confluenceTd"><p>The Crypto property <a shape="rect"
href="http://cxf.apache.org/javadoc/latest/org/apache/cxf/ws/security/SecurityConstants.html#ENCRYPT_PROPERTIES";>configuration</a>
to use for encryption, if "security.encryption.crypto" is not set
instead.</p></td></tr><tr><td colspan="1" rowspan="1"
class="confluenceTd"><p>security.signature.crypto</p></td><td colspan="1"
rowspan="1" class="confluenceTd"><p>A Crypto <a shape="rect"
class="external-link"
href="http://ws.apache.org/wss4j/apidocs/org/apache/ws/security/components/cryp
to/Crypto.html">object</a> to be used for signature. If this is not defined
then "security.signature.properties" is used instead.</p></td></tr><tr><td
colspan="1" rowspan="1"
class="confluenceTd"><p>security.encryption.crypto</p></td><td colspan="1"
rowspan="1" class="confluenceTd"><p>A Crypto <a shape="rect"
class="external-link"
href="http://ws.apache.org/wss4j/apidocs/org/apache/ws/security/components/crypto/Crypto.html";>object</a>
to be used for encryption. If this is not defined then
"security.encryption.properties" is used
instead.</p></td></tr></tbody></table></div><p><strong>Note:</strong> for
Symmetric bindings that specify a protection token, the security-encryption
properties are used.</p><h4
id="SecurityConfiguration-BooleanSecurityconfigurationtags,e.g.thevalueshouldbe"true"or"false".">Boolean
Security configuration tags, e.g. the value should be "true" or
"false".</h4><div class="table-wrap"><table
class="confluenceTable"><tbody><tr><td colspan="1"
rowspan="1" class="confluenceTd"><p>constant</p></td><td colspan="1"
rowspan="1" class="confluenceTd"><p>default</p></td><td colspan="1" rowspan="1"
class="confluenceTd"><p>definition</p></td></tr><tr><td colspan="1" rowspan="1"
class="confluenceTd"><p>security.enableRevocation</p></td><td colspan="1"
rowspan="1" class="confluenceTd"><p>false</p></td><td colspan="1" rowspan="1"
class="confluenceTd"><p>Whether to enable Certificate Revocation List (CRL)
checking or not when verifying trust in a certificate.</p></td></tr><tr><td
colspan="1" rowspan="1"
class="confluenceTd">security.enable.unsigned-saml-assertion.principal</td><td
colspan="1" rowspan="1" class="confluenceTd">false</td><td colspan="1"
rowspan="1" class="confluenceTd">Whether to allow unsigned saml assertions as
SecurityContext Principals. The default is false.<p>Note that "unsigned" refers
to an internal signature. Even if the token is signed by an external signature
(as per the "sender-vouches" requirement), this boole
an must still be configured if you want to use the token to set up the
security context.</p></td></tr><tr><td colspan="1" rowspan="1"
class="confluenceTd">security.validate.saml.subject.conf</td><td colspan="1"
rowspan="1" class="confluenceTd">true</td><td colspan="1" rowspan="1"
class="confluenceTd">Whether to validate the SubjectConfirmation requirements
of a received SAML Token.</td></tr><tr><td colspan="1" rowspan="1"
class="confluenceTd">security.sc.jaas-subject</td><td colspan="1" rowspan="1"
class="confluenceTd">true</td><td colspan="1" rowspan="1"
class="confluenceTd">Set this to "false" if security context must not be
created from JAAS Subject.</td></tr><tr><td colspan="1" rowspan="1"
class="confluenceTd">security.validate.audience-restriction</td><td colspan="1"
rowspan="1" class="confluenceTd">(varies)</td><td colspan="1" rowspan="1"
class="confluenceTd"><p>If this is set to "true", then IF the SAML Token
contains Audience Restriction URIs, one of them must match one of t
he values of the AUDIENCE_RESTRICTIONS property. The default is "true" for CXF
3.0.x, and "false" for 2.7.x.</p></td></tr></tbody></table></div><h4
id="SecurityConfiguration-Non-booleanSecurityConfigurationparameters">Non-boolean
Security Configuration parameters</h4><div class="table-wrap"><table
class="confluenceTable"><tbody><tr><td colspan="1" rowspan="1"
class="confluenceTd"><p>security.saml-role-attributename</p></td><td
colspan="1" rowspan="1" class="confluenceTd"><p>The attribute URI of the SAML
AttributeStatement where the role information is stored. The default is "<a
shape="rect" class="external-link"
href="http://schemas.xmlsoap.org/ws/2005/05/identity/claims/role";
rel="nofollow">http://schemas.xmlsoap.org/ws/2005/05/identity/claims/role</a>".</p></td></tr><tr><td
colspan="1" rowspan="1"
class="confluenceTd"><p>security.subject.cert.constraints</p></td><td
colspan="1" rowspan="1" class="confluenceTd"><p>A comma separated String of
regular expressions which will be applie
d to the subject DN of the certificate used for signature validation, after
trust verification of the certificate chain associated with the certificate.
These constraints are not used when the certificate is contained in the
keystore (direct trust).</p></td></tr><tr><td colspan="1" rowspan="1"
class="confluenceTd">security.audience-restrictions <strong>CXF
3.1.13</strong></td><td colspan="1" rowspan="1" class="confluenceTd"><p>A comma
separated String corresponding to a list of audience restriction URIs. The
default value for this property contains the request URL and the Service QName.
If the AUDIENCE_RESTRICTION_VALIDATION property is "true", and if a received
SAML Token contains audience restriction URIs, then one of them must match one
of the values specified in this
property.</p></td></tr></tbody></table></div><h4
id="SecurityConfiguration-STSClientConfigurationtags">STS Client Configuration
tags</h4><p><strong>Note: </strong>From CXF 3.1.3 onwards. Prior to CXF 3.1.3
these tag
s had a "ws-" prefix. The older tags will still work for backwards
compatibility reasons.</p><div class="table-wrap"><table
class="confluenceTable"><tbody><tr><td colspan="1" rowspan="1"
class="confluenceTd"><p>security.sts.client</p></td><td colspan="1" rowspan="1"
class="confluenceTd"><p>A reference to the STSClient class used to communicate
with the STS.</p></td></tr><tr><td colspan="1" rowspan="1"
class="confluenceTd"><p>security.sts.applies-to</p></td><td colspan="1"
rowspan="1" class="confluenceTd"><p>The "AppliesTo" address to send to the STS.
The default is the endpoint address of the service
provider.</p></td></tr><tr><td colspan="1" rowspan="1"
class="confluenceTd"><p>security.sts.token.usecert</p></td><td colspan="1"
rowspan="1" class="confluenceTd"><p>If true, writes out an X509Certificate
structure in UseKey/KeyInfo. If false (the default), writes out a KeyValue
structure instead.</p></td></tr><tr><td colspan="1" rowspan="1"
class="confluenceTd"><p>security.sts.token.do
.cancel</p></td><td colspan="1" rowspan="1" class="confluenceTd"><p>Whether to
cancel a token when using SecureConversation after successful invocation. The
default is "false".</p></td></tr><tr><td colspan="1" rowspan="1"
class="confluenceTd">security.issue.after.failed.renew</td><td colspan="1"
rowspan="1" class="confluenceTd"><p>Whether to fall back to calling "issue"
after failing to renew an expired token. The default is
"true".</p></td></tr><tr><td colspan="1" rowspan="1"
class="confluenceTd"><p>security.cache.issued.token.in.endpoint</p></td><td
colspan="1" rowspan="1" class="confluenceTd"><p>Set this to "false" to not
cache a SecurityToken per proxy object in the IssuedTokenInterceptorProvider.
This should be done if a token is being retrieved from an STS in an
intermediary. The default value is "true".</p></td></tr><tr><td colspan="1"
rowspan="1"
class="confluenceTd"><p>security.sts.disable-wsmex-call-using-epr-address</p></td><td
colspan="1" rowspan="1" class="confluenceTd"
><p>Whether to avoid STS client trying send WS-MetadataExchange call using STS
>EPR WSA address when the endpoint contract contains no WS-MetadataExchange
>info. The default value is "false".</p></td></tr><tr><td colspan="1"
>rowspan="1" class="confluenceTd"><p>security.sts.token.crypto</p></td><td
>colspan="1" rowspan="1" class="confluenceTd"><p>A Crypto object to be used
>for the STS. See <a shape="rect"
>href="http://cxf.apache.org/javadoc/latest/org/apache/cxf/ws/security/SecurityConstants.html#STS_TOKEN_CRYPTO";>here</a>
> for more information.</p></td></tr><tr><td colspan="1" rowspan="1"
>class="confluenceTd"><p>security.sts.token.properties</p></td><td colspan="1"
>rowspan="1" class="confluenceTd"><p>The Crypto property configuration to use
>for the STS. See <a shape="rect"
>href="http://cxf.apache.org/javadoc/latest/org/apache/cxf/ws/security/SecurityConstants.html#STS_TOKEN_PROPERTIES";>here</a>
> for more information.</p></td></tr><tr><td colspan="1" rowspan="1"
>class="confluenceTd"><p>se
curity.sts.token.username</p></td><td colspan="1" rowspan="1"
class="confluenceTd"><p>The alias name in the keystore to get the user's public
key to send to the STS for the PublicKey KeyType case.</p></td></tr><tr><td
colspan="1" rowspan="1"
class="confluenceTd"><p>security.sts.token.act-as</p></td><td colspan="1"
rowspan="1" class="confluenceTd"><p>The token to be sent to the STS in an
"ActAs" field. See <a shape="rect"
href="http://cxf.apache.org/javadoc/latest/org/apache/cxf/ws/security/SecurityConstants.html#STS_TOKEN_ACT_AS";>here</a>
for more information.</p></td></tr><tr><td colspan="1" rowspan="1"
class="confluenceTd"><p>security.sts.token.on-behalf-of</p></td><td colspan="1"
rowspan="1" class="confluenceTd"><p>The token to be sent to the STS in an
"OnBehalfOf" field. See <a shape="rect"
href="http://cxf.apache.org/javadoc/latest/org/apache/cxf/ws/security/SecurityConstants.html#STS_TOKEN_ON_BEHALF_OF";>here</a>
for more information.</p></td></tr><tr><td colspan="1" rowspan="1
" class="confluenceTd">security.issue.after.failed.renew</td><td colspan="1"
rowspan="1" class="confluenceTd">Whether to call "Issue" if a token "Renew"
fails. Some STSs do not support the renew binding. Defaults to
"true".</td></tr><tr><td colspan="1" rowspan="1"
class="confluenceTd">security.sts.token.imminent-expiry-value</td><td
colspan="1" rowspan="1" class="confluenceTd">The value in seconds within which
a token is considered to be expired by the client, i.e. it is considered to be
expired if it will expire in a time less than the value specified by this tag.
The default value is "10" for CXF 3.0.2+, and "0" for CXF
2.7.13+.</td></tr><tr><td colspan="1" rowspan="1"
class="confluenceTd">security.sts.token.cacher.impl <strong>CXF
3.1.11</strong></td><td colspan="1" rowspan="1" class="confluenceTd"><p>An
implementation of the STSTokenCacher interface, if you want to plug in custom
caching behaviour for STS clients. The default value is the
DefaultSTSTokenCacher.</p></td></tr></tb
ody></table></div><h2
id="SecurityConfiguration-Backwardscompatibility">Backwards
compatibility</h2><p>Users of Apache CXF prior to 3.1.0 do not need to make any
adjustment to their code or spring files. The older "ws-" prefix associated
with the configuration tags above will continue to be accepted.</p></div>
</div>
<!-- Content -->
</td>
