Modified: websites/production/cxf/content/docs/saml-web-sso.html
==============================================================================
--- websites/production/cxf/content/docs/saml-web-sso.html (original)
+++ websites/production/cxf/content/docs/saml-web-sso.html Wed Sep 13 15:05:52
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();
@@ -121,11 +121,11 @@ Apache CXF -- SAML Web SSO
 </p><p> </p><p> </p><p><style type="text/css">/*<![CDATA[*/
-div.rbtoc1505311244188 {padding: 0px;}
-div.rbtoc1505311244188 ul {list-style: disc;margin-left: 0px;}
-div.rbtoc1505311244188 li {margin-left: 0px;padding-left: 0px;}
+div.rbtoc1505314874731 {padding: 0px;}
+div.rbtoc1505314874731 ul {list-style: disc;margin-left: 0px;}
+div.rbtoc1505314874731 li {margin-left: 0px;padding-left: 0px;}
-/*]]>*/</style></p><div class="toc-macro rbtoc1505311244188">
+/*]]>*/</style></p><div class="toc-macro rbtoc1505314874731">
<ul class="toc-indentation"><li><a shape="rect"
href="#SAMLWebSSO-Introduction">Introduction</a>
<ul class="toc-indentation"><li><a shape="rect"
href="#SAMLWebSSO-TypicalFlow">Typical Flow</a></li></ul>
</li><li><a shape="rect" href="#SAMLWebSSO-Mavendependencies">Maven
dependencies</a></li><li><a shape="rect"
href="#SAMLWebSSO-IdentityProvider">Identity Provider</a></li><li><a
shape="rect" href="#SAMLWebSSO-ServiceProviderSecurityFilter">Service Provider
Security Filter</a>
@@ -136,14 +136,14 @@ div.rbtoc1505311244188 li {margin-left:
<ul class="toc-indentation"><li><a shape="rect"
href="#SAMLWebSSO-DistributedStateManagement">Distributed State
Management</a></li></ul>
</li><li><a shape="rect" href="#SAMLWebSSO-LogoutService">Logout
Service</a></li><li><a shape="rect" href="#SAMLWebSSO-MetadataService">Metadata
Service</a></li></ul>
</div><h1 id="SAMLWebSSO-Introduction">Introduction</h1><p><a shape="rect"
class="external-link" href="http://en.wikipedia.org/wiki/Single_sign-on";
rel="nofollow">SSO</a> is about a user having to sign in only once when
interacting with a custom web application which may offer of a number of
individual endpoints.</p><p>CXF 2.6.1 introduces a comprehensive service
provider (SP) support for the SAML Web SSO <a shape="rect"
class="external-link"
href="http://docs.oasis-open.org/security/saml/v2.0/saml-profiles-2.0-os.pdf";
rel="nofollow">profile</a>. This <a shape="rect" class="external-link"
href="http://en.wikipedia.org/wiki/SAML_2.0"; rel="nofollow">page</a> also
offers a good overview of the <a shape="rect" class="external-link"
href="http://en.wikipedia.org/wiki/SAML_2.0#Web_Browser_SSO_Profile";
rel="nofollow">profile</a>.</p><p>HTTP Redirect(via GET) and POST bindings are
supported. The module has been tested against many IDP providers and is easily
configurable.</p><p>The followin
g components are required to get SSO supported:</p><ul
class="alternate"><li>Identity Provider (IDP) supporting SAML
SSO</li><li>Request Assertion Consumer Service (RACS)</li><li>Service Provider
Security Filter</li><li>SSO State Provider</li></ul><p>The following sections
will describe these components in more details</p><h2
id="SAMLWebSSO-TypicalFlow">Typical Flow</h2><p>Typically, the following flow
represents the way SAML SSO is enforced:</p><p>1. User accesses a custom
application for the first time<br clear="none"> 2. Service Provider Security
Filter checks if the security context is available <br clear="none"> and
redirects the user to IDP with a SAML SSO request<br clear="none"> 3. IDP
challenges the user with the authentication dialog and redirects the user to<br
clear="none"> Request Assertion Consumer Service (RACS) after the user has
authenticated<br clear="none"> 4. RACS validates the response from IDP,
establishes a security context and redirects the user <br clear="no
ne"> to the original application endpoint<br clear="none"> 5. Service Provider
Security Filter enforces that a valid security context is available and lets
the user<br clear="none"> access the custom application.</p><h1
id="SAMLWebSSO-Mavendependencies">Maven dependencies</h1><div class="code panel
pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl">
-<pre class="brush: bash; gutter: false; theme: Confluence"
style="font-size:12px;"><dependency>
+<pre class="brush: java; gutter: false; theme: Default"
style="font-size:12px;"><dependency>
<groupId>org.apache.cxf</groupId>
<artifactId>cxf-rt-rs-security-sso-saml</artifactId>
<version>2.6.1</version>
</dependency>
</pre>
</div></div><h1 id="SAMLWebSSO-IdentityProvider">Identity
Provider</h1><p>Identity Provider (IDP) is the service which accepts the
redirect requests from application security filters, authenticates users and
redirects them back to Request Assertion Security Service.</p><p>CXF does not
offer its own IDP SAML Web SSO implementation but might provide it in the
future as part of the <a shape="rect"
href="http://cxf.apache.org/fediz.html";>Fediz</a> project.</p><p>However, CXF
has been tested against a number of popular IDP implementations which support
SAML SSO and thus should be interoperable with whatever IDP is being used in
the specific production environment. The interoperability tests have shown that
some IDPs may process SAML request and produce SAML response data the way which
may not be exactly specification-compliant and thus CXF Request Assertion
Consumer Service (RACS) and Service Provider Security Filter implementations
have a number of configuration properties for adjusting
the way SAML requests to IDP are prepared and SAML responses from IDP are
processed.</p><h1 id="SAMLWebSSO-ServiceProviderSecurityFilter">Service
Provider Security Filter</h1><p>SP Security Filter protects the application
endpoints by checking that a valid SSO security context is available. If it is
then the filter lets the request to continue, if not then it redirects the
current user to IDP.</p><p>When a filter redirects a user to IDP, it creates a
SAML Authentication Request, see <a shape="rect" class="external-link"
href="http://en.wikipedia.org/wiki/SAML_2.0#Web_Browser_SSO_Profile";
rel="nofollow">this page</a> for the example and appends it to the IDP Service
URI or gets it POSTed to IDP.<br clear="none"> Additionally, a RelayState token
pointing to the state of the current user request is also included which IDP
will <br clear="none"> return to Request Assertion Consumer Service (RACS)
after the user has authenticated.</p><p>CXF offers two SP Security filters, one
for redire
cting the user back to IDP via GET and another one - via POST.</p><h2
id="SAMLWebSSO-RedirectBindingFilter">Redirect Binding Filter</h2><p>Redirect
Binding Filter is implemented by
org.apache.cxf.rs.security.saml.sso.SamlRedirectBindingFilter.</p><p>Here is an
example of a typical filter protecting a custom JAX-RS endpoint:</p><div
class="code panel pdl" style="border-width: 1px;"><div class="codeContent
panelContent pdl">
-<pre class="brush: bash; gutter: false; theme: Confluence"
style="font-size:12px;"><bean id="serviceBean"
class="org.apache.cxf.samlp.sso.BookStore"/>
+<pre class="brush: java; gutter: false; theme: Default"
style="font-size:12px;"><bean id="serviceBean"
class="org.apache.cxf.samlp.sso.BookStore"/>
<jaxrs:server address="/app1">
<jaxrs:serviceBeans>
@@ -168,7 +168,7 @@ div.rbtoc1505311244188 li {margin-left:
</pre>
</div></div><p>Note that at the very minimum the filter needs to have 3
properties set-up:<br clear="none"> 1. IDP service address<br clear="none"> 2.
RACS address - it can be absolute or relative if RACS is collocated <br
clear="none"> (shares the same web application context) with the application
endpoint.<br clear="none"> 3. Reference to SSO State Provider.</p><p>The
following optional properties affecting the created SAML request may also be
set:</p><ul><li>String issuerId - it defaults to the base URI of the
application endpoint protected by this filter, for example,
"http://localhost:8080/services/app1";.</li><li><a shape="rect"
class="external-link"
href="http://svn.apache.org/viewvc/cxf/trunk/rt/rs/security/sso/saml/src/main/java/org/apache/cxf/rs/security/saml/sso/AuthnRequestBuilder.java?view=markup";>AuthnRequestBuilder</a>
authnRequestBuilder - A builder that constructs the SAML Request. It defaults
to <a shape="rect" class="external-link" href="http://svn.apache.org/viewv
c/cxf/trunk/rt/rs/security/sso/saml/src/main/java/org/apache/cxf/rs/security/saml/sso/DefaultAuthnRequestBuilder.java?view=markup">DefaultAuthnRequestBuilder</a>.</li></ul><p>The
IDP address is where filters will redirect users to and the RACS address is
where users will be redirected by IDP to.<br clear="none"> RACS will set up a
security context and redirect the user back to the original application address
by using the RelayState token which is included by the filters when users are
initially redirected to IDP.</p><h2 id="SAMLWebSSO-POSTBindingFilter">POST
Binding Filter</h2><p>POST Binding Filter is implemented by
org.apache.cxf.rs.security.saml.sso.SamlPostBindingFilter.</p><p>Here is an
example of a typical filter protecting a custom JAX-RS endpoint.</p><div
class="code panel pdl" style="border-width: 1px;"><div class="codeContent
panelContent pdl">
-<pre class="brush: bash; gutter: false; theme: Confluence"
style="font-size:12px;"><bean id="serviceBean"
class="org.apache.cxf.samlp.sso.BookStore"/>
+<pre class="brush: java; gutter: false; theme: Default"
style="font-size:12px;"><bean id="serviceBean"
class="org.apache.cxf.samlp.sso.BookStore"/>
<jaxrs:server address="/app2">
<jaxrs:serviceBeans>
<ref bean="serviceBean"/>
@@ -200,7 +200,7 @@ div.rbtoc1505311244188 li {margin-left:
</pre>
</div></div><p>Note that the POST binding filter has the same 3 required
properties as org.apache.cxf.rs.security.saml.sso.SamlRedirectBindingFilter has
but also sets a "useDeflateEncoding" property for getting a SAML request
deflated. Some IDPs might not be able to process deflated SAML requests with
POST binding redirects thus the compression may be optionally
disabled.</p><p>What is actually different in this case from the GET-based
redirect is that the filter prepares an instance of <a shape="rect"
class="external-link"
href="http://svn.apache.org/repos/asf/cxf/trunk/rt/rs/security/sso/saml/src/main/java/org/apache/cxf/rs/security/saml/sso/SamlRequestInfo.java";>SAMLRequestInfo</a>
which is subsequently bound to an XHTML view via a JSP filter. The view will
typically have a Java Script handler which will actually redirect the user to
IDP when it is loaded into the browser. The data to view binding is facilitated
by org.apache.cxf.jaxrs.provider.RequestDispatcherProvider, please s
ee <a shape="rect"
href="http://cxf.apache.org/docs/jax-rs-redirection.html#JAX-RSRedirection-WithRequestDispatcherProvider";>this
page</a> for more information.</p><p>One may prefer using the POST binding
filter in cases where having SAML request to IDP encoded as a URI parameter
prohibited.</p><p>Here is a typical JSP handler for binding
org.apache.cxf.rs.security.saml.sso.SAMLRequestInfo to the view:</p><div
class="code panel pdl" style="border-width: 1px;"><div class="codeContent
panelContent pdl">
-<pre class="brush: bash; gutter: false; theme: Confluence"
style="font-size:12px;"><%@ page
import="javax.servlet.http.HttpServletRequest,org.apache.cxf.rs.security.saml.sso.SamlRequestInfo"
%>
+<pre class="brush: java; gutter: false; theme: Default"
style="font-size:12px;"><%@ page
import="javax.servlet.http.HttpServletRequest,org.apache.cxf.rs.security.saml.sso.SamlRequestInfo"
%>
<%
SamlRequestInfo data =
(SamlRequestInfo)request.getAttribute("samlrequestinfo");
@@ -223,7 +223,7 @@ div.rbtoc1505311244188 li {margin-left:
</html>
</pre>
</div></div><h2 id="SAMLWebSSO-SigningSAMLAuthenticationRequests">Signing SAML
Authentication Requests</h2><p>The filters may optionally sign SAML requests,
the following configuration properties can be set-up:</p><ul><li>boolean
signRequest - Whether to sign the AuthnRequest or not. The default is
false.</li><li>String signatureUsername - The keystore alias to use to sign the
AuthnRequest.</li><li>Crypto signatureCrypto - A WSS4J Crypto object if the
SAML AuthnRequest is to be signed.</li><li>String signaturePropertiesFile -
This points to a properties file that can be used to load a Crypto instance if
the SAML AuthnRequest is to be signed.</li><li>CallbackHandler callbackHandler
- A CallbackHandler object to retrieve the private key password used to sign
the request.</li><li>String callbackHandlerClass - A class name that is loaded
for use as the CallbackHandler object.</li></ul><p>Either the "signatureCrypto"
or "signaturePropertiesFile" properties must be set if "signRequest" is
set to true. Similarly, either "callbackHandler" or "callbackHandlerClass"
must be configured.</p><p>Example:</p><div class="code panel pdl"
style="border-width: 1px;"><div class="codeContent panelContent pdl">
-<pre class="brush: bash; gutter: false; theme: Confluence"
style="font-size:12px;"><bean id="ssoSignedRedirectPOST"
class="org.apache.cxf.rs.security.saml.sso.SamlPostBindingFilter">
+<pre class="brush: java; gutter: false; theme: Default"
style="font-size:12px;"><bean id="ssoSignedRedirectPOST"
class="org.apache.cxf.rs.security.saml.sso.SamlPostBindingFilter">
<property name="idpServiceAddress"
value="https://localhost:9443/idp"/>
<property name="assertionConsumerServiceAddress"
value="/racs/sso"/>
<property name="stateProvider" ref="stateManager"/>
@@ -241,10 +241,10 @@ div.rbtoc1505311244188 li {margin-left:
</pre>
</div></div><h2 id="SAMLWebSSO-FiltersandStateManagement">Filters and State
Management</h2><p>The following properties affect the way filters manage the
SSO state:</p><ul><li><a shape="rect" class="external-link"
href="http://svn.apache.org/repos/asf/cxf/trunk/rt/rs/security/sso/saml/src/main/java/org/apache/cxf/rs/security/saml/sso/state/SPStateManager.java";>SPStateManager</a>
stateProvider</li><li>long stateTimeToLive - default is 2 minutes (in
milliseconds).</li><li>String webAppDomain.</li><li>boolean addWebAppContext -
default is true.</li><li>boolean boolean addEndpointAddressToContext - default
is false.</li></ul><p>The 'stateProvider' refers to a custom <a shape="rect"
class="external-link"
href="http://svn.apache.org/repos/asf/cxf/trunk/rt/rs/security/sso/saml/src/main/java/org/apache/cxf/rs/security/saml/sso/state/SPStateManager.java";>SPStateManager</a>
implementation and is used for filters and RACS coordinating with the filters
persisting the current user request state,
RACS validating it and persisting the current security context state and
filters getting the information about the context. Filters and RACS use a
'RelayState' token to work with the current request state. RACS persists the
security context and the filters retrieve and validate it using the cookie
which RACS also sets to point to this security context.</p><p>Note that a
'stateTimeToLive' property can be used to control how long the current security
context can be valid for.</p><p>Both filters and RACS use opaque cookies to
refer to the original request and security context state and 'webAppDomain',
'addWebAppContext' and 'addEndpointAddressToContext' affect the way these
cookies can be shared between multiple SP custom applications.</p><p>For
example, here is a typical Set Cookie request issued by a web application to
the browser:</p><div class="code panel pdl" style="border-width: 1px;"><div
class="codeContent panelContent pdl">
-<pre class="brush: bash; gutter: false; theme: Confluence"
style="font-size:12px;">Set-Cookie: value; Domain=mydomain; Path=/accounts;
Expires=Wed, 13-Jan-2021 22:23:01 GMT;
+<pre class="brush: java; gutter: false; theme: Default"
style="font-size:12px;">Set-Cookie: value; Domain=mydomain; Path=/accounts;
Expires=Wed, 13-Jan-2021 22:23:01 GMT;
</pre>
</div></div><p>By default, CXF will get a Cookie 'Path' property set to
something like "/services", where 'services' is the actual name of the war
archive.<br clear="none"> The 'addEndpointAddressToContext' property can be
further restrict this path to something like "/services/app1",
"/services/app2", where "/app1" and "/app2" are jaxrs:endpoint addresses, this
can be handy for testing, with every jaxrs:endpoint within a single war having
its own security context.<br clear="none"> If the custom SP application is
'spread' across multiple containers with different application context names,
then the 'addWebAppContext' can be set to 'false' leading to Cookie 'Path'
parameters set to '/' and the 'webAppDomain' property set to some shared
value.</p><p>Note that the stateTimeToLive property affects a Cookie 'Expires'
property but also used by filters and RACS to enforce that the internal state
has not expired.</p><h1 id="SAMLWebSSO-RequestAssertionConsumerService">Request
Assertion Consu
mer Service</h1><p>Request Assertion Consumer Service receives a SAML
Authentication Response and RelayState token from IDP, uses the token to
validate the response against the data available in the original SAML
Authentication Request, creates a security context if it does not already
exists for<br clear="none"> the current user, persists it and redirect the user
back to the original endpoint.</p><p>The RACS processes the SAML Response, and
validates it in a number of ways:</p><ul><li>The <a shape="rect"
class="external-link"
href="http://svn.apache.org/repos/asf/cxf/trunk/rt/rs/security/sso/saml/src/main/java/org/apache/cxf/rs/security/saml/sso/SAMLProtocolResponseValidator.java";>SAMLProtocolResponseValidator</a>
validates the Response against the specifications and checks the signature of
the Response (if it exists), as well as doing the same for any child Assertion
of the Response. It validates the status code of the Response as
well.</li><li>The <a shape="rect" class="external-
link"
href="http://svn.apache.org/repos/asf/cxf/trunk/rt/rs/security/sso/saml/src/main/java/org/apache/cxf/rs/security/saml/sso/SAMLSSOResponseValidator.java";>SAMLSSOResponseValidator</a>
validates the Response according to the Web SSO profile.</li></ul><p>Here is a
typical RACS consfiguration:</p><div class="code panel pdl"
style="border-width: 1px;"><div class="codeContent panelContent pdl">
-<pre class="brush: bash; gutter: false; theme: Confluence"
style="font-size:12px;"><bean id="consumerService"
class="org.apache.cxf.rs.security.saml.sso.RequestAssertionConsumerService">
+<pre class="brush: java; gutter: false; theme: Default"
style="font-size:12px;"><bean id="consumerService"
class="org.apache.cxf.rs.security.saml.sso.RequestAssertionConsumerService">
<property name="stateProvider" ref="stateManager"/>
<!-- responses are expected to be deflated by default
<property name="supportDeflateEncoding" value="false"/>
@@ -267,7 +267,7 @@ div.rbtoc1505311244188 li {margin-left:
</jaxrs:server>
</pre>
</div></div><p>RACS is implemented as a JAX-RS server endpoint. It needs a
reference to the SSO State Manager and by default it expects that SAML Response
is deflated and Base64 encoded which can be changed. It shares the same
'stateTimeToLive' property with the filters which can be used to restrict the
time the security context state is kept for.</p><p>The following properties may
also be set up:</p><ul><li>boolean enforceKnownIssuer - Whether the Issuer of
the Response (and child Assertions) is "known" to the RACS. This value is
compared against the IDP URL configured on the filter. The default value is
true.</li><li><a shape="rect" class="external-link"
href="http://svn.apache.org/repos/asf/cxf/trunk/rt/rs/security/sso/saml/src/main/java/org/apache/cxf/rs/security/saml/sso/TokenReplayCache.java";>TokenReplayCache</a>
replayCache - A TokenReplayCache implementation to store Assertion IDs for the
POST binding to guard against replay attacks. The <a shape="rect"
class="external-link"
href="http://svn.apache.org/repos/asf/cxf/trunk/rt/rs/security/sso/saml/src/main/java/org/apache/cxf/rs/security/saml/sso/EHCacheTokenReplayCache.java";>default</a>
uses an implementation based on EhCache.</li></ul><h2
id="SAMLWebSSO-DealingwithsignedSAMLResponses">Dealing with signed SAML
Responses</h2><p>RACS can be setup to support verifying signed Responses, or
signed Assertions contained in a Response. Similarly, either "callbackHandler"
or "callbackHandlerClass" must be configured if you wish to support decrypting
encrypted Assertions. For example:</p><div class="code panel pdl"
style="border-width: 1px;"><div class="codeContent panelContent pdl">
-<pre class="brush: bash; gutter: false; theme: Confluence"
style="font-size:12px;"><bean id="consumerService"
class="org.apache.cxf.rs.security.saml.sso.RequestAssertionConsumerService">
+<pre class="brush: java; gutter: false; theme: Default"
style="font-size:12px;"><bean id="consumerService"
class="org.apache.cxf.rs.security.saml.sso.RequestAssertionConsumerService">
<property name="stateProvider" ref="stateManager"/>
<property name="supportBase64Encoding" value="false"/>
@@ -277,7 +277,7 @@ div.rbtoc1505311244188 li {margin-left:
</bean>
</pre>
</div></div><p>In this example the "enforceAssertionsSigned" enforcing that
signed Assertions are contained in a Response is disabled by default and RACS
will only verify that the actual Responses are signed.</p><h2
id="SAMLWebSSO-SignatureKeyInfoValidation">Signature Key Info
Validation</h2><p>By default ds:Signature is expected to contain ds:KeyInfo
element.</p><p>Setting a "keyInfoMustBeAvailable" property to false will lead
to a default store alias being used to load the certificate for validating the
signature.</p><h2 id="SAMLWebSSO-UsingRACSasEndpointFilter">Using RACS as
Endpoint Filter</h2><p>As you can see from the documentation above, RACS is
typically represented as an independent service endpoint or service bean: in
such cases RACS redirects the requestor back to the the actual
endpoint.</p><p>Starting from CXF 3.0.0 it is possible to set it up as the
target endpoint filter, simply add
org.apache.cxf.rs.security.saml.sso.RequestionAssertionConsumerFilter to the
list of o
ther endpoint providers.</p><p>In this case the authentication filters do not
have to set their "assertionConsumerServiceAddress" property</p><h1
id="SAMLWebSSO-SSOStateProvider">SSO State Provider</h1><p>SP Security Filters
and RACS depend on the custom <a shape="rect" class="external-link"
href="http://svn.apache.org/repos/asf/cxf/trunk/rt/rs/security/sso/saml/src/main/java/org/apache/cxf/rs/security/saml/sso/state/SPStateManager.java";>SPStateManager</a>
implementation for persisting the current request and security context
state.</p><p>CXF ships a basic <a shape="rect" class="external-link"
href="http://svn.apache.org/repos/asf/cxf/trunk/rt/rs/security/sso/saml/src/main/java/org/apache/cxf/rs/security/saml/sso/state/MemorySPStateManager.java";>MemorySPStateProvider</a>
and an <a shape="rect" class="external-link" href="http://ehcache.org/";
rel="nofollow">EhCache</a>-based <a shape="rect" class="external-link"
href="http://svn.apache.org/repos/asf/cxf/trunk/rt/rs/security/sso/saml/
src/main/java/org/apache/cxf/rs/security/saml/sso/state/EHCacheSPStateManager.java">implementation</a>
which is memory based with an option to overflow to the disk. Users can
customize the EhCache provider or register their own custom SPStateProvider
implementations if required.</p><p>For example, by default, the EhCache
provider will overflow the data to the system temp directory and will not
persist the data across restarts. The following EhCache configuration can be
used to change it:</p><div class="code panel pdl" style="border-width:
1px;"><div class="codeContent panelContent pdl">
-<pre class="brush: bash; gutter: false; theme: Confluence"
style="font-size:12px;"><ehcache xsi:noNamespaceSchemaLocation="ehcache.xsd"
updateCheck="false" monitoring="autodetect" dynamicConfig="true">
+<pre class="brush: java; gutter: false; theme: Default"
style="font-size:12px;"><ehcache xsi:noNamespaceSchemaLocation="ehcache.xsd"
updateCheck="false" monitoring="autodetect" dynamicConfig="true">
<diskStore path="/home/username/work/ehcache"/>
@@ -301,7 +301,7 @@ Assuming this configuration is saved in
</bean>
</pre>
</div></div><h2 id="SAMLWebSSO-DistributedStateManagement">Distributed State
Management</h2><p>If you have a complex application supported by a number of
wars deployed into different containers, one has to decide whether to have a
single RequestAssertionConsumerService (RACS) endpoint which IDP will redirect
to when processing the user authentication requests or have a separate RACS
endpoint per every web application which all form a bigger
application.</p><p>For example, assume you have server1, server2 and server3
which all support a bigger application. One can have a serverRacs web
application which will host a RACS endpoint. Next, server1, server2 and server3
SSO filters will all point to this standalone RACS endpoint when redirecting
the user to IDP and IDP will eventually redirect the user to RACS which in turn
will redirect the user to the original target URI supported by server or
server2 or server3.</p><p>In this case, one has to decide how the state between
SSO security fi
lters protecting the individual servers and RACS will be shared.<br
clear="none"> One approach is to setup the Ehcache provider to use <a
shape="rect" class="external-link"
href="http://ehcache.org/documentation/configuration/distributed-cache-configuration";
rel="nofollow">Terracotta or RMI with the multicast</a> or implement the
alternative approach not involving Ehcache at all.</p><p>CXF offers a simple <a
shape="rect" class="external-link"
href="http://svn.apache.org/repos/asf/cxf/trunk/rt/rs/security/sso/saml/src/main/java/org/apache/cxf/rs/security/saml/sso/state/HTTPSPStateManager.java";>HTTPSPStateManager</a>
provider which can be used to simplify the task of setting up the distributed
state cache, which can be used for simple distributed web applications or to
support the more advanced applications at the proof-of-concept stage.</p><p>For
example, the following jaxrs:endpoint can be deployed alongside the RACS
endpoint running in its own web application:</p><div class="code p
anel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl">
-<pre class="brush: bash; gutter: false; theme: Confluence"
style="font-size:12px;"> <bean id="stateManager"
class="org.apache.cxf.rs.security.saml.sso.state.HTTPSPStateManager"/>
+<pre class="brush: java; gutter: false; theme: Default"
style="font-size:12px;"> <bean id="stateManager"
class="org.apache.cxf.rs.security.saml.sso.state.HTTPSPStateManager"/>
<bean id="consumerService"
class="org.apache.cxf.rs.security.saml.sso.RequestAssertionConsumerService">
<property name="stateProvider" ref="stateManager"/>
@@ -317,7 +317,7 @@ Assuming this configuration is saved in
</jaxrs:server>
</pre>
</div></div><p>Note that the RACS bean itself directly uses HTTPSPStateManager
which is also available as an HTTP endpoint for all the SSO security filters to
work with.<br clear="none"> Here is an example of how the SPStateManagers at
the individual SSO filter end can use this HTTP endpoint:</p><div class="code
panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl">
-<pre class="brush: bash; gutter: false; theme: Confluence"
style="font-size:12px;"><jaxrs:client id="stateManager"
+<pre class="brush: java; gutter: false; theme: Default"
style="font-size:12px;"><jaxrs:client id="stateManager"
address="https://localhost:${racs.port}/racs";
serviceClass="org.apache.cxf.rs.security.saml.sso.state.HTTPSPStateManager"/>
Modified: websites/production/cxf/content/docs/schemas-and-namespaces.html
==============================================================================
--- websites/production/cxf/content/docs/schemas-and-namespaces.html (original)
+++ websites/production/cxf/content/docs/schemas-and-namespaces.html Wed Sep 13
15:05:52 2017
@@ -145,7 +145,7 @@ Apache CXF -- Schemas and Namespaces
<p>The following is an example of a valid Spring configuration file. Using the
table above, there is no magic involved in setting the correct value for the
schemaLocation attribute!</p>
<div class="code panel pdl" style="border-width: 1px;"><div class="codeContent
panelContent pdl">
-<pre class="brush: bash; gutter: false; theme: Confluence"
style="font-size:12px;">
+<pre class="brush: java; gutter: false; theme: Default"
style="font-size:12px;">
<beans xmlns="http://www.springframework.org/schema/beans";
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance";
xmlns:http-conf="http://cxf.apache.org/transports/http/configuration";
@@ -175,7 +175,7 @@ http://www.springframework.org/schema/be
<p>Note for Developers: If you define your own configuration schema, place it
in the schemas subdirectory of the resources directory, then combine <a
shape="rect" href="http://cxf.apache.org/";>http://cxf.apache.org/</a> and the
path of the schema relative to the resources directory to form the system ID,
and make the latter known to Spring by adding a line similar to the following
to the <strong>spring.schemas</strong> file in your module's META-INF directory
(note the escaped : character):</p>
<div class="code panel pdl" style="border-width: 1px;"><div class="codeContent
panelContent pdl">
-<pre class="brush: bash; gutter: false; theme: Confluence"
style="font-size:12px;">
+<pre class="brush: java; gutter: false; theme: Default"
style="font-size:12px;">
http\://cxf.apache.org/schemas/wsdl/http-conf.xsd=schemas/wsdl/http-conf.xsd
</pre>
</div></div></div>
Modified: websites/production/cxf/content/docs/sdo.html
==============================================================================
--- websites/production/cxf/content/docs/sdo.html (original)
+++ websites/production/cxf/content/docs/sdo.html Wed Sep 13 15:05:52 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/shBrushBash.js'></script>
+<script src='/resources/highlighter/scripts/shBrushJava.js'></script>
<script>
SyntaxHighlighter.defaults['toolbar'] = false;
SyntaxHighlighter.all();
@@ -123,7 +123,7 @@ Apache CXF -- SDO
<p>By default, CXF does not ship with the Tuscany SDO jars. You will need to
acquire them elsewhere and add them to the classpath for the SDO databinding to
work. The list of required jars are:</p>
<div class="code panel pdl" style="border-width: 1px;"><div class="codeContent
panelContent pdl">
-<pre class="brush: bash; gutter: false; theme: Confluence"
style="font-size:12px;">
+<pre class="brush: java; gutter: false; theme: Default"
style="font-size:12px;">
backport-util-concurrent-3.0.jar
codegen-2.2.3.jar
codegen-ecore-2.2.3.jar
Modified: websites/production/cxf/content/docs/secure-jax-rs-services.html
==============================================================================
--- websites/production/cxf/content/docs/secure-jax-rs-services.html (original)
+++ websites/production/cxf/content/docs/secure-jax-rs-services.html Wed Sep 13
15:05:52 2017
@@ -32,9 +32,9 @@
<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/shBrushBash.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();
@@ -122,18 +122,18 @@ Apache CXF -- Secure JAX-RS Services
 </p><p> </p><p> </p><p><style type="text/css">/*<![CDATA[*/
-div.rbtoc1505311248908 {padding: 0px;}
-div.rbtoc1505311248908 ul {list-style: disc;margin-left: 0px;}
-div.rbtoc1505311248908 li {margin-left: 0px;padding-left: 0px;}
+div.rbtoc1505314958137 {padding: 0px;}
+div.rbtoc1505314958137 ul {list-style: disc;margin-left: 0px;}
+div.rbtoc1505314958137 li {margin-left: 0px;padding-left: 0px;}
-/*]]>*/</style></p><div class="toc-macro rbtoc1505311248908">
+/*]]>*/</style></p><div class="toc-macro rbtoc1505314958137">
<ul class="toc-indentation"><li><a shape="rect"
href="#SecureJAX-RSServices-HTTPS">HTTPS</a>
<ul class="toc-indentation"><li><a shape="rect"
href="#SecureJAX-RSServices-Configuringendpoints">Configuring
endpoints</a></li><li><a shape="rect"
href="#SecureJAX-RSServices-Configuringclients">Configuring
clients</a></li></ul>
</li><li><a shape="rect"
href="#SecureJAX-RSServices-Authentication">Authentication</a></li><li><a
shape="rect"
href="#SecureJAX-RSServices-Authorization">Authorization</a></li><li><a
shape="rect" href="#SecureJAX-RSServices-WS-Trustintegration">WS-Trust
integration</a>
<ul class="toc-indentation"><li><a shape="rect"
href="#SecureJAX-RSServices-ValidatingBasicAuthcredentialswithSTS">Validating
BasicAuth credentials with STS</a></li><li><a shape="rect"
href="#SecureJAX-RSServices-UsingSTStovalidateSAMLassertions">Using STS to
validate SAML assertions</a></li></ul>
</li><li><a shape="rect"
href="#SecureJAX-RSServices-NoteaboutSecurityManager">Note about
SecurityManager</a></li><li><a shape="rect"
href="#SecureJAX-RSServices-AdvancedSecurity">Advanced Security</a></li><li><a
shape="rect" href="#SecureJAX-RSServices-Restrictinglargepayloads">Restricting
large payloads</a></li><li><a shape="rect"
href="#SecureJAX-RSServices-CrossOriginResourceSharing">Cross Origin Resource
Sharing</a></li></ul>
</div><h1 id="SecureJAX-RSServices-HTTPS">HTTPS</h1><p>Transport-level
protection of JAX-RS endpoints can be managed by underlying Servlet containers,
for example, see this <a shape="rect" class="external-link"
href="http://tomcat.apache.org/tomcat-6.0-doc/ssl-howto.html";>Tomcat SSL
Configuration section</a>.</p><p>Additionally CXF provides support for
configuring endpoints which depend on embedded Jetty. CXF JAX-RS clients can
also be configured to support SSL.</p><h2
id="SecureJAX-RSServices-Configuringendpoints">Configuring
endpoints</h2><p>JAX-RS endpoints using embedded Jetty can rely on the
configuration like this one:</p><div class="code panel pdl"
style="border-width: 1px;"><div class="codeContent panelContent pdl">
-<pre class="brush: bash; gutter: false; theme: Confluence"
style="font-size:12px;"><beans
xmlns="http://www.springframework.org/schema/beans";
+<pre class="brush: java; gutter: false; theme: Default"
style="font-size:12px;"><beans
xmlns="http://www.springframework.org/schema/beans";
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance";
xmlns:http="http://cxf.apache.org/transports/http/configuration";
xmlns:httpj="http://cxf.apache.org/transports/http-jetty/configuration";
@@ -162,7 +162,7 @@ div.rbtoc1505311248908 li {margin-left:
</beans>
</pre>
</div></div><p>Instead keyPassword in keyManager you can also specify
keyPasswordCallbackHandler attribute. In this case attribute must contain full
name of the class implementing JSE <a shape="rect" class="external-link"
href="http://docs.oracle.com/javase/7/docs/api/javax/security/auth/callback/CallbackHandler.html";
rel="nofollow">CallbackHandler </a>interface and providing key password on the
runtime. Sample key password callback handler implementation can be found <a
shape="rect" class="external-link"
href="https://github.com/apache/cxf/blob/master/systests/transports/src/test/java/org/apache/cxf/systest/http/KeyPasswordCallbackHandler.java";
rel="nofollow">here</a>.</p><p>If you use JAXRSServerFactoryBean to create and
start JAX-RS endpoints from the code then the above configuration can be
utilized like this:</p><div class="code panel pdl" style="border-width:
1px;"><div class="codeContent panelContent pdl">
-<pre class="brush: bash; gutter: false; theme: Confluence"
style="font-size:12px;">JAXRSServerFactoryBean bean = new
JAXRSServerFactoryBean();
+<pre class="brush: java; gutter: false; theme: Default"
style="font-size:12px;">JAXRSServerFactoryBean bean = new
JAXRSServerFactoryBean();
SpringBusFactory bf = new SpringBusFactory();
Bus bus = bf.createBus("configuration/beans.xml");
bean.setBus(bus);
@@ -170,11 +170,11 @@ bean.setAddress("http://localhost:9095/r
bean.setServiceClass(CustomerService.class);
</pre>
</div></div><p>If you also have a jaxrs:server endpoint declared in the above
beans.xml, then make sure you have a 'depends-on' attribute set:</p><div
class="code panel pdl" style="border-width: 1px;"><div class="codeContent
panelContent pdl">
-<pre class="brush: bash; gutter: false; theme: Confluence"
style="font-size:12px;"><jaxrs:server serviceClass="CustomerService.class"
address="http://localhost:9095/rest";
+<pre class="brush: java; gutter: false; theme: Default"
style="font-size:12px;"><jaxrs:server serviceClass="CustomerService.class"
address="http://localhost:9095/rest";
depends-on="port-9095-tls-config"/>
</pre>
</div></div><p>Once you have JAX-RS and Jetty HTTPS combined then you can get
the application context initiated like this:</p><div class="code panel pdl"
style="border-width: 1px;"><div class="codeContent panelContent pdl">
-<pre class="brush: bash; gutter: false; theme: Confluence"
style="font-size:12px;">public class Server {
+<pre class="brush: java; gutter: false; theme: Default"
style="font-size:12px;">public class Server {
public void main(String[] args) throws Exception {
Bus busLocal = new
SpringBusFactory().createBus("configuration/beans.xml");
@@ -185,7 +185,7 @@ bean.setServiceClass(CustomerService.cla
}
</pre>
</div></div><p>Having JAX-RS endpoints declared alongside CXF Jetty HTTPS
configuration is only needed when an embedded Jetty container is used. If you
have application WARs deployed into Tomcat or Jetty then please follow
container-specific guides on how to set up SSL.</p><p>Please also see this <a
shape="rect" class="external-link"
href="http://svn.apache.org/repos/asf/cxf/trunk/distribution/src/main/release/samples/jax_rs/basic_https/";>HTTPS-based
demo</a> in the CXF distribution.</p><p>Additionally check the <a shape="rect"
href="http://cxf.apache.org/docs/jetty-configuration.html";>CXF Jetty
Configuration</a> section.</p><h2
id="SecureJAX-RSServices-Configuringclients">Configuring clients</h2><p>Secure
HTTPConduits for CXF JAX-RS proxies and WebClients can be configured as
described in this <a shape="rect"
href="http://cxf.apache.org/docs/client-http-transport-including-ssl-support.html";>section</a>.</p><p>For
example, check this <a shape="rect" class="external-link" href="http:
//svn.apache.org/repos/asf/cxf/trunk/distribution/src/main/release/samples/jax_rs/basic_https/src/main/resources/ClientConfig.xml">configuration
file</a>. Endpoint addresses used by proxies or clients have to match the
pattern used in the HTTPConduit configuration.</p><p>The configuration file can
be referenced during the proxy or WebClient creation:</p><div class="code panel
pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl">
-<pre class="brush: bash; gutter: false; theme: Confluence"
style="font-size:12px;">final String address = "http://localhost:9095/rest";;
+<pre class="brush: java; gutter: false; theme: Default"
style="font-size:12px;">final String address = "http://localhost:9095/rest";;
final String configLocation;
WebClient client = WebClient.create(address, configLocation);
@@ -193,7 +193,7 @@ WebClient client = WebClient.create(addr
BookStore proxy = JAXRSClientFactory.create(address, configLocation,
BookStore.class);
</pre>
</div></div><p>HTTPConduits can also be 'bound' to proxies or WebClients using
expanded QNames. Please see this <a shape="rect"
href="http://cxf.apache.org/docs/jax-rs-client-api.html#JAX-RSClientAPI-ConfiguringanHTTPConduitfromSpring";>section</a>
for more information.</p><p>Please see <a shape="rect" class="external-link"
href="http://aruld.info/programming-ssl-for-jetty-based-cxf-services/";
rel="nofollow">this blog entry</a> on how the HTTPConduit TLS properties can be
set up from the code. In the code, do
WebClient.getConfig(myClient).getHTTPConduit() and proceed from there.</p><h1
id="SecureJAX-RSServices-Authentication">Authentication</h1><p>It is often
containers like Tomcat or frameworks like Spring Security which handle the user
authentication. Sometimes you might want to do the custom authentication
instead. CXF HTTP Transport adds decoded Basic Authentication credentials into
an instance of AuthorizationPolicy extension and sets it on the current
message. Thus the easiest
way is to register a custom invoker or <code>@PreMatching
ContainerRequestFilter</code> filter which will extract a user name and
password like this:</p><div class="code panel pdl" style="border-width:
1px;"><div class="codeContent panelContent pdl">
-<pre class="brush: bash; gutter: false; theme: Confluence"
style="font-size:12px;">public class AuthenticationHandler implements
ContainerRequestFilter {
+<pre class="brush: java; gutter: false; theme: Default"
style="font-size:12px;">public class AuthenticationHandler implements
ContainerRequestFilter {
@Override
public void filter(ContainerRequestContext requestContext) throws
IOException {
@@ -225,7 +225,7 @@ BookStore proxy = JAXRSClientFactory.cre
 }
</pre>
</div></div><p>One other thing you may want to do, after authenticating a
user, is to initialize org.apache.cxf.security.SecurityContext with Principals
representing the user and its roles (if available).</p><p>If you prefer using
Spring Security then see how the authentication is handled in a <a shape="rect"
class="external-link"
href="http://svn.apache.org/repos/asf/cxf/trunk/distribution/src/main/release/samples/jax_rs/spring_security";>spring-security</a>
demo.</p><p>Next, please see the <a shape="rect"
href="securing-cxf-services.html">Securing CXF Services</a> section on how CXF
Security interceptors can help.</p><p>Additionally check this <a shape="rect"
class="external-link"
href="http://sberyozkin.blogspot.com/2010/12/authentication-and-authorization-cxf.html";
rel="nofollow">blog entry</a> for more information on how CXF JAX-RS wraps the
CXF security interceptors with helper filters.</p><p>For example, see how a
JAX-RS filter can be used to wrap CXF JAASLoginInterceptor:</p>
<div class="code panel pdl" style="border-width: 1px;"><div class="codeContent
panelContent pdl">
-<pre class="brush: bash; gutter: false; theme: Confluence"
style="font-size:12px;"><jaxrs:server address="/jaas">
+<pre class="brush: java; gutter: false; theme: Default"
style="font-size:12px;"><jaxrs:server address="/jaas">
<jaxrs:serviceBeans>
<bean
class="org.apache.cxf.systest.jaxrs.security.SecureBookStoreNoAnnotations"/>
</jaxrs:serviceBeans>
@@ -245,7 +245,7 @@ BookStore proxy = JAXRSClientFactory.cre
</bean>
</pre>
</div></div><p>The filter will redirect the client to "/login.jsp" if the
authentication fails. If no 'redirectURI' property is set then 401 will be
returned. A "realmName" property can also be set.</p><p>If the JAAS
Authentication succeeds then the filter will set a SecurityContext instance on
the message. This context can be used for authorization decisions.</p><h1
id="SecureJAX-RSServices-Authorization">Authorization</h1><p>It is often
containers like Tomcat or frameworks like Spring Security which handle user
authorization, similarly to the way the authentication is handled.</p><p>CXF
also provides two interceptors which make it easy to enforce authorization
decisions, as described in the <a shape="rect"
href="securing-cxf-services.html">Securing CXF Services</a> section.<br
clear="none"> CXF JAX-RS SimpleAuthorizingFilter can be used to wrap those
interceptors and return 403 in case of failures:</p><div class="code panel pdl"
style="border-width: 1px;"><div class="codeContent p
anelContent pdl">
-<pre class="brush: bash; gutter: false; theme: Confluence"
style="font-size:12px;"><jaxrs:server address="/jaas">
+<pre class="brush: java; gutter: false; theme: Default"
style="font-size:12px;"><jaxrs:server address="/jaas">
<jaxrs:serviceBeans>
<bean
class="org.apache.cxf.systest.jaxrs.security.SecureBookStoreNoAnnotations"/>
</jaxrs:serviceBeans>
@@ -264,7 +264,7 @@ BookStore proxy = JAXRSClientFactory.cre
</util:map>
</pre>
</div></div><p>SimpleAuthorizingFilter can also wrap CXF
SecureAnnotationsInterceptor.</p><p>Note that wrapping CXF security
interceptors with JAX-RS filters is not required; it simply makes it easier to
handle authentication and authorization exceptions and return appropriate HTTP
error statuses.</p><h1 id="SecureJAX-RSServices-WS-Trustintegration">WS-Trust
integration</h1><p>One of the requirements for deploying CXF endpoints into
secure web service environments is to ensure that existing WS-Trust STS
services can be used to protect the endpoints. JAX-WS endpoints can rely on CXF
WS-Security and WS-Trust support. Making sure CXF JAX-RS endpoints can be
additionally secured by STS is strategically important task. CXF provides close
integration between JAX-WS and JAX-RS frontends thus reusing CXF JAX-WS and
WS-Security is the most effective way toward achieving this integration.</p><h2
id="SecureJAX-RSServices-ValidatingBasicAuthcredentialswithSTS">Validating
BasicAuth credentials w
ith STS</h2><p>Validating Basic Authentication credentials with STS is
possible starting from CXF 2.4.1. JAX-RS and JAX-WS services can rely on this
feature. Here is an example on how a jaxrs endpoint can be configured:</p><div
class="code panel pdl" style="border-width: 1px;"><div class="codeContent
panelContent pdl">
-<pre class="brush: bash; gutter: false; theme: Confluence"
style="font-size:12px;"><jaxrs:server
serviceClass="org.customers.CustomerService"
+<pre class="brush: java; gutter: false; theme: Default"
style="font-size:12px;"><jaxrs:server
serviceClass="org.customers.CustomerService"
depends-on="ClientAuthHttpsSettings"
address="https://localhost:8081/rest">
@@ -326,7 +326,7 @@ BookStore proxy = JAXRSClientFactory.cre
</http:conduit>
</pre>
</div></div><p>AuthPolicyValidatingInterceptor converts Basic Auth info into
WSS4J UsernameToken and delegates to STS to validate.</p><h2
id="SecureJAX-RSServices-UsingSTStovalidateSAMLassertions">Using STS to
validate SAML assertions</h2><p>Please see <a shape="rect"
href="http://cxf.apache.org/docs/jax-rs-saml.html#JAX-RSSAML-SAMLAssertionValidation";>this
section</a> for more information on how STSTokenValidator can be used to
validate the inbound SAML assertions.</p><h1
id="SecureJAX-RSServices-NoteaboutSecurityManager">Note about
SecurityManager</h1><p>If <code>java.lang.SecurityManager</code> is installed
then you'll likely need to configure the trusted JAX-RS codebase with a
'suppressAccessChecks' permission for the injection of JAXRS context or
parameter fields to succeed. For example, you may want to update a Tomcat <a
shape="rect" class="external-link"
href="http://tomcat.apache.org/tomcat-5.5-doc/security-manager-howto.html";>catalina.policy</a>
with the following permissio
n :</p><div class="code panel pdl" style="border-width: 1px;"><div
class="codeContent panelContent pdl">
-<pre class="brush: bash; gutter: false; theme: Confluence"
style="font-size:12px;">grant codeBase
"file:${catalina.home}/webapps/yourwebapp/lib/cxf.jar" {
+<pre class="brush: java; gutter: false; theme: Default"
style="font-size:12px;">grant codeBase
"file:${catalina.home}/webapps/yourwebapp/lib/cxf.jar" {
permission java.lang.reflect.ReflectPermission "suppressAccessChecks";
};
</pre>
Modified: websites/production/cxf/content/docs/securing-cxf-services.html
==============================================================================
--- websites/production/cxf/content/docs/securing-cxf-services.html (original)
+++ websites/production/cxf/content/docs/securing-cxf-services.html Wed Sep 13
15:05:52 2017
@@ -117,11 +117,11 @@ Apache CXF -- Securing CXF Services
<!-- Content -->
<div class="wiki-content">
<div id="ConfluenceContent"><p><style type="text/css">/*<![CDATA[*/
-div.rbtoc1505311207039 {padding: 0px;}
-div.rbtoc1505311207039 ul {list-style: disc;margin-left: 0px;}
-div.rbtoc1505311207039 li {margin-left: 0px;padding-left: 0px;}
+div.rbtoc1505314840027 {padding: 0px;}
+div.rbtoc1505314840027 ul {list-style: disc;margin-left: 0px;}
+div.rbtoc1505314840027 li {margin-left: 0px;padding-left: 0px;}
-/*]]>*/</style></p><div class="toc-macro rbtoc1505311207039">
+/*]]>*/</style></p><div class="toc-macro rbtoc1505314840027">
<ul class="toc-indentation"><li><a shape="rect"
href="#SecuringCXFServices-Securetransports">Secure transports</a>
<ul class="toc-indentation"><li><a shape="rect"
href="#SecuringCXFServices-HTTPS">HTTPS</a></li></ul>
</li><li><a shape="rect"
href="#SecuringCXFServices-SecuringJAX-WSservices">Securing JAX-WS services</a>
@@ -136,7 +136,7 @@ div.rbtoc1505311207039 li {margin-left:
<ul class="toc-indentation"><li><a shape="rect"
href="#SecuringCXFServices-XML">XML</a></li><li><a shape="rect"
href="#SecuringCXFServices-XML-CXFversionspriorto2.7.4">XML - CXF versions
prior to 2.7.4</a></li><li><a shape="rect"
href="#SecuringCXFServices-Multiparts">Multiparts</a></li></ul>
</li><li><a shape="rect"
href="#SecuringCXFServices-Largedatastreamcaching">Large data stream
caching</a></li></ul>
</div><h1 id="SecuringCXFServices-Securetransports">Secure transports</h1><h2
id="SecuringCXFServices-HTTPS">HTTPS</h2><p>Please see the <a shape="rect"
href="http://cxf.apache.org/docs/client-http-transport-including-ssl-support.html";>Configuring
SSL Support</a> page for more information.</p><h1
id="SecuringCXFServices-SecuringJAX-WSservices">Securing JAX-WS
services</h1><h2 id="SecuringCXFServices-WS-Security">WS-Security</h2><p>CXF
supports WS-Security via the Apache WSS4J project. WSS4J provides an
implementation of the following WS-Security standards:</p><ul><li><a
shape="rect" class="external-link"
href="http://docs.oasis-open.org/wss/v1.1/wss-v1.1-spec-os-SOAPMessageSecurity.pdf";
rel="nofollow"> SOAP Message Security 1.1</a></li><li><a shape="rect"
class="external-link"
href="http://docs.oasis-open.org/wss/v1.1/wss-v1.1-spec-os-UsernameTokenProfile.pdf";
rel="nofollow">Username Token Profile 1.1</a></li><li><a shape="rect"
class="external-link" href="http://docs.oasis-open.org
/wss/v1.1/wss-v1.1-spec-os-x509TokenProfile.pdf" rel="nofollow">X.509
Certificate Token Profile 1.1</a></li><li><a shape="rect" class="external-link"
href="http://docs.oasis-open.org/wss/v1.1/wss-v1.1-spec-os-SAMLTokenProfile.pdf";
rel="nofollow">SAML Token Profile 1.1</a></li><li><a shape="rect"
class="external-link"
href="http://docs.oasis-open.org/wss/v1.1/wss-v1.1-spec-os-KerberosTokenProfile.pdf";
rel="nofollow">Kerberos Token Profile 1.1</a></li><li><a shape="rect"
class="external-link"
href="http://docs.oasis-open.org/wss/v1.1/wss-v1.1-spec-os-SwAProfile.pdf";
rel="nofollow">SOAP Messages with Attachments Profile 1.1</a></li><li><a
shape="rect" class="external-link"
href="http://www.ws-i.org/Profiles/BasicSecurityProfile-1.1.html";
rel="nofollow">Basic Security Profile 1.1</a></li></ul><p>Please see the <a
shape="rect" href="ws-security.html">WS-Security</a> page for more
information.</p><h2
id="SecuringCXFServices-WS-SecurityPolicy">WS-SecurityPolicy</h2><p>CXF fully
supports WS
-SecurityPolicy, which allows you to configure WS-Security requirements for an
endpoint using a WS-Policy annotation. This is the recommended way of
configuring WS-Security. Policies can be added in a WSDL or else referenced via
an annotation in code.</p><p>The WS-SecurityPolicy layer and the XML-Security
layer in Apache CXF share a common set of security configuration tags from CXF
3.1.0. The <a shape="rect" href="security-configuration.html">Security
Configuration</a> page details these tags and values. There are also some
addition configuration tags, that are only used for when security is configured
via WS-SecurityPolicy, see the following <a shape="rect"
href="ws-securitypolicy.html">page</a> for more information.</p><h2
id="SecuringCXFServices-WS-SecureConversation">WS-SecureConversation</h2><p>CXF
fully supports WS-SecureConveration, see the following <a shape="rect"
href="ws-secureconversation.html">page</a> for more information.</p><h2
id="SecuringCXFServices-WS-Trust,STS">
WS-Trust, STS</h2><p>CXF ships with a advanced SecurityTokenService (STS)
implementation that can be used to issue (SAML) tokens for authentication. CXF
also supports communicating with the STS using the WS-Trust specification. SSO
is supported by caching the tokens on the client side. Please see the <a
shape="rect" class="external-link"
href="https://cwiki.apache.org/CXF20DOC/ws-trust.html";>WS-Trust</a> page for
more information.</p><h1
id="SecuringCXFServices-SecuringJAX-RSservices">Securing JAX-RS
services</h1><h2 id="SecuringCXFServices-JAX-RSXMLSecurity">JAX-RS XML
Security</h2><p>It is possible to secure XML based JAX-RS requests (and
responses) using XML Signature and Encryption. See the <a shape="rect"
href="jax-rs-xml-security.html">JAX-RS XML Security</a> page for more
information.</p><h2 id="SecuringCXFServices-JAX-RSSAML">JAX-RS SAML</h2><p>See
the <a shape="rect" href="jax-rs-saml.html">JAX-RS SAML</a> page on creating
SAML Assertions and adding them to a JAX-RS request
, as well as how to validate them on the receiving side.</p><h2
id="SecuringCXFServices-JAX-RSJOSE">JAX-RS JOSE</h2><p>See the <a shape="rect"
href="jax-rs-jose.html">JAX-RS JOSE</a> page on support for the JWA, JWK, JWS,
JWE and JWT specifications.</p><h1 id="SecuringCXFServices-SSO">SSO</h1><h2
id="SecuringCXFServices-SAMLWebSSO">SAML Web SSO</h2><p>Please see <a
shape="rect" class="external-link"
href="http://coheigea.blogspot.ie/2012/06/saml-web-sso-profile-support-in-apache.html";
rel="nofollow">this blog entry</a> announcing the support for SAML Web SSO
profile and the <a shape="rect"
href="https://cwiki.apache.org/confluence/display/CXF20DOC/SAML+Web+SSO";>SAML
Web SSO</a> page for more information. CXF fully supports the SAML Web SSO
profile on the service provider side. As of yet however, no IdP is available in
CXF.</p><h2 id="SecuringCXFServices-WS-Federation">WS-Federation</h2><p>Apache
CXF <a shape="rect" href="../fediz.html">Fediz</a> is a subproject of CXF.
Fediz helps y
ou to secure your web applications and delegates security enforcement to the
underlying application server. With Fediz, authentication is externalized from
your web application to an identity provider installed as a dedicated server
component. The supported standard is <a shape="rect" class="external-link"
href="http://docs.oasis-open.org/wsfed/federation/v1.2/os/ws-federation-1.2-spec-os.html#_Toc223175002";
rel="nofollow">WS-Federation Passive Requestor Profile</a>. Fediz supports <a
shape="rect" class="external-link"
href="http://en.wikipedia.org/wiki/Claims-based_identity"; rel="nofollow">Claims
Based Access Control</a> beyond Role Based Access Control (RBAC).</p><h1
id="SecuringCXFServices-OAuth">OAuth</h1><p>Please check <a shape="rect"
href="http://cxf.apache.org/docs/jax-rs-oauth2.html";>OAuth2.0</a> and <a
shape="rect" href="http://cxf.apache.org/docs/jax-rs-oauth.html";>OAuth1.0</a>
pages for the information about the support for OAuth 2.0 and OAuth 1.0 in
CXF.</p><h1 id="Secu
ringCXFServices-Authentication">Authentication</h1><h2
id="SecuringCXFServices-JAASLoginInterceptor">JAASLoginInterceptor</h2><p>Container
or Spring Security managed authentication as well as the custom authentication
are all the viable options used by CXF developers.</p><p>Starting from CXF
2.3.2 and 2.4.0 it is possible to use an
org.apache.cxf.interceptor.security.JAASLoginInterceptor in order to
authenticate a current user and populate a CXF SecurityContext.</p><p>Example
:</p><div class="code panel pdl" style="border-width: 1px;"><div
class="codeContent panelContent pdl">
-<pre class="brush: bash; gutter: false; theme: Confluence"
style="font-size:12px;"><jaxws:endpoint address="/soapService">
+<pre class="brush: java; gutter: false; theme: Default"
style="font-size:12px;"><jaxws:endpoint address="/soapService">
<jaxws:inInterceptors>
<ref bean="authenticationInterceptor"/>
</jaxws:inInterceptors>
@@ -154,7 +154,7 @@ div.rbtoc1505311207039 li {margin-left:
-->
</pre>
</div></div><p>The JAAS authenticator is configured with the name of the JAAS
login context (the one usually specified in the JAAS configuration resource
which the server is aware of). It is also configured with an optional
"roleClassifier" property which is needed by the CXF SecurityContext in order
to differentiate between user and role Principals. By default CXF will assume
that role Principals are represented by javax.security.acl.Group
instances.</p><p>In some cases objects representing a user principal and roles
are implementing the same marker interface such as Principal. That can be
handled like this:</p><div class="code panel pdl" style="border-width:
1px;"><div class="codeContent panelContent pdl">
-<pre class="brush: bash; gutter: false; theme: Confluence"
style="font-size:12px;"><bean id="authenticationInterceptor"
class="org.apache.cxf.interceptor.security.JAASLoginInterceptor">
+<pre class="brush: java; gutter: false; theme: Default"
style="font-size:12px;"><bean id="authenticationInterceptor"
class="org.apache.cxf.interceptor.security.JAASLoginInterceptor">
<property name="contextName" value="jaasContext"/>
<property name="roleClassifier" value="RolePrincipal"/>
<property name="roleClassifierType" value="classname"/>
@@ -162,7 +162,7 @@ div.rbtoc1505311207039 li {margin-left:
<!-- Similarly for JAX-RS endpoints -->
</pre>
</div></div><p>In this case JAASLoginInterceptor will know that the roles are
represented by a class whose simple name is RolePrincipal. Note that full class
names are also supported.</p><h2
id="SecuringCXFServices-Kerberos">Kerberos</h2><p>Please see <a shape="rect"
href="http://cxf.apache.org/docs/client-http-transport-including-ssl-support.html#ClientHTTPTransport%28includingSSLsupport%29-SpnegoAuthentication%28Kerberos%29";>this
page</a> for the information about Spnego/Kerberos HTTPConduit client
support.</p><p>Please check the following blog entries about WS-Security
Kerberos support in CXF:</p><p><a shape="rect" class="external-link"
href="http://coheigea.blogspot.com/2011/10/using-kerberos-with-web-services-part-i.html";
rel="nofollow">Using Kerberos with Web Services - part 1</a><br clear="none">
<a shape="rect" class="external-link"
href="http://coheigea.blogspot.com/2011/10/using-kerberos-with-web-services-part.html";
rel="nofollow">Using Kerberos with Web Services - part 2<
/a><br clear="none"> <a shape="rect" class="external-link"
href="http://coheigea.blogspot.com/2012/02/ws-trust-spnego-support-in-apache-cxf.html";
rel="nofollow">WS-Trust SPNego support in Apache CXF </a></p><p>Please check
the following <a shape="rect" href="jaxrs-kerberos.html">page</a> about
Kerberos support in JAX-RS.</p><h1
id="SecuringCXFServices-Authorization">Authorization</h1><p>Container or Spring
Security managed authorization as well as the custom authorization are all the
viable options used by CXF developers.</p><p>CXF 2.3.2 and 2.4.0 introduce
org.apache.cxf.interceptor.security.SimpleAuthorizingInterceptor and
org.apache.cxf.interceptor.security.SecureAnnotationsInterceptor interceptors
which can help with enforcing the authorization rules.</p><p>Example :</p><div
class="code panel pdl" style="border-width: 1px;"><div class="codeContent
panelContent pdl">
-<pre class="brush: bash; gutter: false; theme: Confluence"
style="font-size:12px;"><jaxws:endpoint id="endpoint1"
address="/soapService1">
+<pre class="brush: java; gutter: false; theme: Default"
style="font-size:12px;"><jaxws:endpoint id="endpoint1"
address="/soapService1">
<jaxws:inInterceptors>
<ref bean="authorizationInterceptor"/>
</jaxws:inInterceptors>
@@ -195,7 +195,7 @@ div.rbtoc1505311207039 li {margin-left:
</pre>
</div></div><h1
id="SecuringCXFServices-ControllingLargeRequestPayloads">Controlling Large
Request Payloads</h1><h2 id="SecuringCXFServices-XML">XML</h2><p>Starting with
CXF 2.7.4, CXF now requires use of a StAX parser that can provide fine grained
control over the size of the incoming XML. The only parser that will currently
work is Woodstox 4.2 or newer. The main reason is there are a series of DOS
attacks that can only be prevented at the StAX parser level. There is a
"org.apache.cxf.stax.allowInsecureParser" System Property that can be set to
true to allow using an insecure parser, but that is HIGHLY not recommended and
doing so would also now allow the settings described in this section.</p><p>CXF
has several default settings that will prevent malicious XML from causing
various DOS failures. You can override the default values if you know you will
have incoming XML that will exceed these limits. These settings can be set as
Bus level properties, endpoint level properties, or ev
en per request via an interceptor.</p><div class="table-wrap"><table
class="confluenceTable"><tbody><tr><th colspan="1" rowspan="1"
class="confluenceTh"><p>Setting</p></th><th colspan="1" rowspan="1"
class="confluenceTh"><p>Default</p></th><th colspan="1" rowspan="1"
class="confluenceTh"><p>Description</p></th></tr><tr><td colspan="1"
rowspan="1"
class="confluenceTd"><p>org.apache.cxf.stax.maxChildElements</p></td><td
colspan="1" rowspan="1" class="confluenceTd"><p>50000</p></td><td colspan="1"
rowspan="1" class="confluenceTd"><p>Maximum number of child elements for a
given parent element</p></td></tr><tr><td colspan="1" rowspan="1"
class="confluenceTd"><p>org.apache.cxf.stax.maxElementDepth</p></td><td
colspan="1" rowspan="1" class="confluenceTd"><p>100</p></td><td colspan="1"
rowspan="1" class="confluenceTd"><p>Maximum depth of an
element</p></td></tr><tr><td colspan="1" rowspan="1"
class="confluenceTd"><p>org.apache.cxf.stax.maxAttributeCount</p></td><td
colspan="1" rowspan="1" c
lass="confluenceTd"><p>500</p></td><td colspan="1" rowspan="1"
class="confluenceTd"><p>Maximum number of attributes on a single
element</p></td></tr><tr><td colspan="1" rowspan="1"
class="confluenceTd"><p>org.apache.cxf.stax.maxAttributeSize</p></td><td
colspan="1" rowspan="1" class="confluenceTd"><p>64K</p></td><td colspan="1"
rowspan="1" class="confluenceTd"><p>Maximum size of a single
attribute</p></td></tr><tr><td colspan="1" rowspan="1"
class="confluenceTd"><p>org.apache.cxf.stax.maxTextLength</p></td><td
colspan="1" rowspan="1" class="confluenceTd"><p>128M</p></td><td colspan="1"
rowspan="1" class="confluenceTd"><p>Maximum size of an elements text
value</p></td></tr><tr><td colspan="1" rowspan="1"
class="confluenceTd"><p>org.apache.cxf.stax.maxElementCount</p></td><td
colspan="1" rowspan="1" class="confluenceTd"><p>Long.MAX_VALUE</p></td><td
colspan="1" rowspan="1" class="confluenceTd"><p>Maximum total number of
elements in the XML document</p></td></tr><tr><td colspan="1" row
span="1"
class="confluenceTd"><p>org.apache.cxf.stax.maxXMLCharacters</p></td><td
colspan="1" rowspan="1" class="confluenceTd"><p>Long.MAX_VALUE</p></td><td
colspan="1" rowspan="1" class="confluenceTd"><p>Maximum total number of
characters parsed by the parser</p></td></tr></tbody></table></div><h2
id="SecuringCXFServices-XML-CXFversionspriorto2.7.4">XML - CXF versions prior
to 2.7.4</h2><p>Endpoints expecting XML payloads may get <a shape="rect"
class="external-link"
href="http://svn.apache.org/repos/asf/cxf/trunk/rt/core/src/main/java/org/apache/cxf/interceptor/security/DepthRestrictingStreamInterceptor.java";>DepthRestrictingInterceptor</a>
registered and configured in order to control the limits a given XML payload
may not exceed. This can be useful in a variety of cases in order to protect
against massive payloads which can potentially cause the denial-of-service
situation or simply slow the service down a lot.</p><p>The complete number of
XML elements, the number of immediate c
hildren of a given XML element may contain and the stack depth of the payload
can be restricted, for example:</p><div class="code panel pdl"
style="border-width: 1px;"><div class="codeContent panelContent pdl">
-<pre class="brush: bash; gutter: false; theme: Confluence"
style="font-size:12px;"><bean id="depthInterceptor"
class="org.apache.cxf.interceptor.security.DepthRestrictingStreamInterceptor">
+<pre class="brush: java; gutter: false; theme: Default"
style="font-size:12px;"><bean id="depthInterceptor"
class="org.apache.cxf.interceptor.security.DepthRestrictingStreamInterceptor">
<!-- Total number of elements in the XML payload -->
<property name="elementCountThreshold" value="5000"/>
Modified: websites/production/cxf/content/docs/server-http-transport.html
==============================================================================
--- websites/production/cxf/content/docs/server-http-transport.html (original)
+++ websites/production/cxf/content/docs/server-http-transport.html Wed Sep 13
15:05:52 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/shBrushBash.js'></script>
+<script src='/resources/highlighter/scripts/shBrushJava.js'></script>
<script>
SyntaxHighlighter.defaults['toolbar'] = false;
SyntaxHighlighter.all();
@@ -132,7 +132,7 @@ Apache CXF -- Server HTTP Transport
<p>The elements used to configure an HTTP provider endpoint are defined in the
namespace <code><a shape="rect"
href="http://cxf.apache.org/transports/http/configuration";>http://cxf.apache.org/transports/http/configuration</a></code>.
It is commonly referred to using the prefix <code>http-conf</code>. In order
to use the HTTP configuration elements you will need to add the lines shown
below to the beans element of your endpoint's configuration file. In addition,
you will need to add the configuration elements' namespace to the
<code>xsi:schemaLocation</code> attribute.</p>
<div class="code panel pdl" style="border-width: 1px;"><div class="codeHeader
panelHeader pdl" style="border-bottom-width: 1px;"><b>Adding the Configuration
Namespace</b></div><div class="codeContent panelContent pdl">
-<pre class="brush: bash; gutter: false; theme: Confluence"
style="font-size:12px;">
+<pre class="brush: java; gutter: false; theme: Default"
style="font-size:12px;">
<beans ...
xmlns:http-conf="http://cxf.apache.org/transports/http/configuration
...
@@ -148,7 +148,7 @@ Apache CXF -- Server HTTP Transport
<p>You configure an HTTP server endpoint using the
<code>http-conf:destination</code> element and its children. The
<code>http-conf:destination</code> element takes a single attribute,
<code>name</code>, the specifies the WSDL port element that corresponds to the
endpoint. The value for the <code>name</code> attribute takes the form
<em>portQName</em><code>.http-destination</code>. The example below shows the
<code>http-conf:destination</code> element that would be used to add
configuration for an endpoint that was specified by the WSDL fragment
<code><port binding="widgetSOAPBinding" name="widgetSOAPPort></code> if
the endpoint's target namespace was <code><a shape="rect" class="external-link"
href="http://widgets.widgetvendor.net";
rel="nofollow">http://widgets.widgetvendor.net</a></code>.</p>
<div class="code panel pdl" style="border-width: 1px;"><div class="codeHeader
panelHeader pdl" style="border-bottom-width: 1px;"><b>http-conf:destination
Element</b></div><div class="codeContent panelContent pdl">
-<pre class="brush: bash; gutter: false; theme: Confluence"
style="font-size:12px;">
+<pre class="brush: java; gutter: false; theme: Default"
style="font-size:12px;">
...
<http-conf:destination
name="{http://widgets/widgetvendor.net}widgetSOAPPort.http-destination">
@@ -174,7 +174,7 @@ Apache CXF -- Server HTTP Transport
<p>The example below shows a the configuration for an HTTP service provider
endpoint that honors keep alive requests and suppresses all communication
errors.</p>
<div class="code panel pdl" style="border-width: 1px;"><div class="codeHeader
panelHeader pdl" style="border-bottom-width: 1px;"><b>HTTP Service Provider
Endpoint Configuration</b></div><div class="codeContent panelContent pdl">
-<pre class="brush: bash; gutter: false; theme: Confluence"
style="font-size:12px;">
+<pre class="brush: java; gutter: false; theme: Default"
style="font-size:12px;">
<beans xmlns="http://www.springframework.org/schema/beans";
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance";
xmlns:http-conf="http://cxf.apache.org/transports/http/configuration";
@@ -199,7 +199,7 @@ Apache CXF -- Server HTTP Transport
<p>The WSDL extension elements used to configure an HTTP server endpoint are
defined in the namespace <code><a shape="rect"
href="http://cxf.apache.org/transports/http/configuration";>http://cxf.apache.org/transports/http/configuration</a></code>.
It is commonly refered to using the prefix <code>http-conf</code>. In order to
use the HTTP configuration elements you will need to add the line shown below
to the <code>definitions</code> element of your endpoint's WSDL document.</p>
<div class="code panel pdl" style="border-width: 1px;"><div class="codeHeader
panelHeader pdl" style="border-bottom-width: 1px;"><b>HTTP Provider WSDL
Element's Namespace</b></div><div class="codeContent panelContent pdl">
-<pre class="brush: bash; gutter: false; theme: Confluence"
style="font-size:12px;">
+<pre class="brush: java; gutter: false; theme: Default"
style="font-size:12px;">
<definitions ...
xmlns:http-conf="http://cxf.apache.org/transports/http/configuration
</pre>
@@ -214,7 +214,7 @@ Apache CXF -- Server HTTP Transport
<p>The example below shows a WSDL fragment that configures an HTTP server
endpoint to specify that it will not interact with caches.</p>
<div class="code panel pdl" style="border-width: 1px;"><div class="codeHeader
panelHeader pdl" style="border-bottom-width: 1px;"><b>WSDL to Configure an HTTP
Service Provider Endpoint</b></div><div class="codeContent panelContent pdl">
-<pre class="brush: bash; gutter: false; theme: Confluence"
style="font-size:12px;">
+<pre class="brush: java; gutter: false; theme: Default"
style="font-size:12px;">
<service ...>
<port ...>
<soap:address ... />
Modified:
websites/production/cxf/content/docs/server-service-and-client-factorybeans.html
==============================================================================
---
websites/production/cxf/content/docs/server-service-and-client-factorybeans.html
(original)
+++
websites/production/cxf/content/docs/server-service-and-client-factorybeans.html
Wed Sep 13 15:05:52 2017
@@ -132,7 +132,7 @@ Apache CXF -- Server, Service, and Clien
<p>To add your own service configuration:</p>
<div class="code panel pdl" style="border-width: 1px;"><div class="codeContent
panelContent pdl">
-<pre class="brush: bash; gutter: false; theme: Confluence"
style="font-size:12px;">
+<pre class="brush: java; gutter: false; theme: Default"
style="font-size:12px;">
MyServiceConfiguration config = new AbstractServiceConfiguration() {
... // your implementation
};
Modified: websites/production/cxf/content/docs/service-routing.html
==============================================================================
--- websites/production/cxf/content/docs/service-routing.html (original)
+++ websites/production/cxf/content/docs/service-routing.html Wed Sep 13
15:05:52 2017
@@ -32,9 +32,9 @@
<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/shBrushBash.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();
@@ -127,7 +127,7 @@ Apache CXF -- Service Routing
<p>One common practice to version web services is using XML namespaces to
clearly delineate the versions of a document that are compatible. For
example:</p>
<div class="code panel pdl" style="border-width: 1px;"><div class="codeContent
panelContent pdl">
-<pre class="brush: bash; gutter: false; theme: Confluence"
style="font-size:12px;">
+<pre class="brush: java; gutter: false; theme: Default"
style="font-size:12px;">
<wsdl:types>
<schema
targetNamespace="http://apache.org/2007/03/21/hello_world_xml_http/mixed/types";
@@ -148,7 +148,7 @@ Apache CXF -- Service Routing
<p>Lets see the code:</p>
<div class="code panel pdl" style="border-width: 1px;"><div class="codeHeader
panelHeader pdl" style="border-bottom-width: 1px;"><b>Example 1: The server -
this server has three endpoints: one endpoint for the dummy service, another
two endpoints are different versions of Greeter service</b></div><div
class="codeContent panelContent pdl">
-<pre class="brush: bash; gutter: false; theme: Confluence"
style="font-size:12px;">
+<pre class="brush: java; gutter: false; theme: Default"
style="font-size:12px;">
import javax.xml.ws.Endpoint;
@@ -197,7 +197,7 @@ public class Server extends AbstractBusT
</div></div>
<div class="code panel pdl" style="border-width: 1px;"><div class="codeHeader
panelHeader pdl" style="border-bottom-width: 1px;"><b>Example 2: The
intermediary interceptor</b></div><div class="codeContent panelContent pdl">
-<pre class="brush: bash; gutter: false; theme: Confluence"
style="font-size:12px;">
+<pre class="brush: java; gutter: false; theme: Default"
style="font-size:12px;">
import java.io.BufferedInputStream;
import java.io.IOException;
import java.io.InputStream;
Modified: websites/production/cxf/content/docs/servlet-transport.html
==============================================================================
--- websites/production/cxf/content/docs/servlet-transport.html (original)
+++ websites/production/cxf/content/docs/servlet-transport.html Wed Sep 13
15:05:52 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();
@@ -118,7 +118,7 @@ Apache CXF -- Servlet Transport
<!-- Content -->
<div class="wiki-content">
<div id="ConfluenceContent"><h1
id="ServletTransport-Settingupyourweb.xml">Setting up your web.xml</h1><p>To
create services that use this transport you can either use the CXF APIs (for
example, see <a shape="rect" href="developing-a-service.html">JAX-WS</a>) or
create an XML file which registers services for you.</p><h2
id="ServletTransport-PublishinganendpointfromXML">Publishing an endpoint from
XML</h2><p>CXF uses <a shape="rect" href="configuration.html">Spring</a> to
provide XML configuration of services. This means that first we'll want to load
Spring via a Servlet listener and tell it where our XML configuration file
is:</p><p>Next, you'll need to add CXFServlet to your web.xml:</p><div
class="code panel pdl" style="border-width: 1px;"><div class="codeContent
panelContent pdl">
-<pre class="brush: bash; gutter: false; theme: Confluence"
style="font-size:12px;"><?xml version="1.0" encoding="ISO-8859-1"?>
+<pre class="brush: java; gutter: false; theme: Default"
style="font-size:12px;"><?xml version="1.0" encoding="ISO-8859-1"?>
<!DOCTYPE web-app
PUBLIC "-//Sun Microsystems, Inc.//DTD Web Application 2.3//EN"
"http://java.sun.com/dtd/web-app_2_3.dtd">
@@ -153,7 +153,7 @@ Apache CXF -- Servlet Transport
</web-app>
</pre>
</div></div><p>Alternatively, you can point to the configuration file using a
CXFServlet init parameter :</p><div class="code panel pdl" style="border-width:
1px;"><div class="codeContent panelContent pdl">
-<pre class="brush: bash; gutter: false; theme: Confluence"
style="font-size:12px;"><?xml version="1.0" encoding="ISO-8859-1"?>
+<pre class="brush: java; gutter: false; theme: Default"
style="font-size:12px;"><?xml version="1.0" encoding="ISO-8859-1"?>
<!DOCTYPE web-app
PUBLIC "-//Sun Microsystems, Inc.//DTD Web Application 2.3//EN"
"http://java.sun.com/dtd/web-app_2_3.dtd">
@@ -180,7 +180,7 @@ Apache CXF -- Servlet Transport
</web-app>
</pre>
</div></div><p>The next step is to actually write the configuration
file:</p><div class="code panel pdl" style="border-width: 1px;"><div
class="codeContent panelContent pdl">
-<pre class="brush: bash; gutter: false; theme: Confluence"
style="font-size:12px;"><beans
xmlns="http://www.springframework.org/schema/beans";
+<pre class="brush: java; gutter: false; theme: Default"
style="font-size:12px;"><beans
xmlns="http://www.springframework.org/schema/beans";
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance";
xmlns:jaxws="http://cxf.apache.org/jaxws";
xmlns:jaxrs="http://cxf.apache.org/jaxrs";
@@ -208,7 +208,7 @@ Apache CXF -- Servlet Transport
</beans>
</pre>
</div></div><p>Here we're creating a JAX-WS endpoint based on our
implementation class, GreeterImpl.</p><p><strong>NOTE:</strong> We're
publishing endpoints "http://localhost/mycontext/services/Greeter1"; and
"http://localhost/mycontext/services/GreeterRest";, but we set
jaxws:endpoint/@address and jaxrs:server/@address to relative values such as
"/Greeter1" "/GreeterRest".</p><h2
id="ServletTransport-SupportforAsynchronousRequests">Support for Asynchronous
Requests</h2><p>Enable an 'async-supported' servlet property if you work with
Servlet3 API containers and need to support asynchronous requests:</p><div
class="code panel pdl" style="border-width: 1px;"><div class="codeContent
panelContent pdl">
-<pre class="brush: bash; gutter: false; theme: Confluence"
style="font-size:12px;"><servlet>
+<pre class="brush: java; gutter: false; theme: Default"
style="font-size:12px;"><servlet>
<servlet-name>CXFServlet</servlet-name>
<display-name>CXF Servlet</display-name>
<servlet-class>
@@ -223,7 +223,7 @@ Apache CXF -- Servlet Transport
</servlet>
</pre>
</div></div><h2
id="ServletTransport-Redirectingrequestsandservingthestaticcontent">Redirecting
requests and serving the static content</h2><p>Starting from CXF 2.2.5 it is
possible to configure CXFServlet to redirect current requests to other servlets
or serve the static resources.</p><p>"redirects-list" init parameter can be
used to provide a space separated list of URI patterns; if a given request URI
matches one of the patterns then CXFServlet will try to find a
RequestDispatcher using the pathInfo of the current HTTP request and will
redirect the request to it.</p><p>"redirect-servlet-path" can be used to affect
a RequestDispatcher lookup, if specified then it will concatenated with the
pathInfo of the current request.</p><p>"redirect-servlet-name" init parameter
can be used to enable a named RequestDispatcher look-up, after one of the URI
patterns in the "redirects-list" has matched the current request
URI.</p><p>"static-resources-list" init parameter can be used to provide a
space separated list of static resource such as html, css, or pdf files which
CXFServlet will serve directly.</p><p>One can have requests redirected to other
servlets or JSP pages.</p><p>CXFServlets serving both JAXWS and JAXRS based
endpoints can avail of this feature.</p><p>For example, please see this <a
shape="rect" class="external-link"
href="http://svn.apache.org/repos/asf/cxf/trunk/systests/jaxrs/src/test/resources/jaxrs_dispatch/WEB-INF/web.xml";>web.xml</a>.</p><p>The
"http://localhost:9080/the/bookstore1/books/html/123"; request URI will
initially be matched by the CXFServlet given that it has a more specific URI
pattern than the RedirectCXFServlet. After a current URI has reached a
jaxrs:server endpoint, the response will be redirected by the JAXRS <a
shape="rect"
href="http://cxf.apache.org/docs/jax-rs.html#JAX-RS-WithRequestDispatcherProvider";>RequestDispatcherProvider</a>
to a "/book.html" address, see "dispatchProvider1" bean <a shape="rect"
class="external-link" href="
https://git-wip-us.apache.org/repos/asf?p=cxf.git;a=blob;f=systests/jaxrs/src/test/resources/jaxrs_dispatch/WEB-INF/web.xml;h=a2212337bd6a9ed7a212b21a6826850581601121;hb=HEAD";>here</a>.</p><p>Next,
the request URI "/book.html" will be handled by RedirectCXFServlet. Note that
a uri pattern can be a regular expression. This servlet redirects the request
further to a RequestDispatcher capable of handling a
"/static/book.html".</p><p>Finally, DefaultCXFServlet serves a requested
book.html.</p><h2 id="ServletTransport-Servingwelcomepages">Serving welcome
pages</h2><p>Starting from CXF 2.5.5 and 2.6.2 it is possible to configure
CXFServlet to serve welcome pages in a number of ways.</p><p>For example, lets
assume we have a web application called "webapp" which has a root resource
called "index.html". For CXFServlet to support both "/webapp" and
"/webapp/index.html" requests returning "index.html", while letting all other
requests to proceed to the actual endpoints, the following can be do
ne.</p><p>Option1. Delegating to Default Servlet</p><div class="code panel
pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl">
-<pre class="brush: bash; gutter: false; theme: Confluence"
style="font-size:12px;"><servlet>
+<pre class="brush: java; gutter: false; theme: Default"
style="font-size:12px;"><servlet>
<servlet-name>CXFServlet</servlet-name>
<display-name>CXF Servlet</display-name>
<servlet-class>
@@ -259,7 +259,7 @@ Apache CXF -- Servlet Transport
</welcome-file-list>
</pre>
</div></div><p>Note that the redirects-list parameter has two space separated
values, "/" and "index.html". The request attribute
'javax.servlet.include.request_uri' might need to be set for the underlying
container like Jetty to successfully read "index.html".</p><p>Option2. Using
CXFServlet itself to read index.html</p><div class="code panel pdl"
style="border-width: 1px;"><div class="codeContent panelContent pdl">
-<pre class="brush: bash; gutter: false; theme: Confluence"
style="font-size:12px;"><servlet>
+<pre class="brush: java; gutter: false; theme: Default"
style="font-size:12px;"><servlet>
<servlet-name>CXFServlet</servlet-name>
<display-name>CXF Servlet</display-name>
<servlet-class>
@@ -281,7 +281,7 @@ Apache CXF -- Servlet Transport
</servlet-mapping>
</pre>
</div></div><h2
id="ServletTransport-PublishinganendpointwiththeAPI">Publishing an endpoint
with the API</h2><p>Once your Servlet is registered in your web.xml, you should
set the default bus with CXFServlet's bus to make sure that CXF uses it as its
HTTP Transport. Simply publish with the related path "Greeter" and your service
should appear at the address you specify:</p><div class="code panel pdl"
style="border-width: 1px;"><div class="codeContent panelContent pdl">
-<pre class="brush: bash; gutter: false; theme: Confluence"
style="font-size:12px;">import javax.xml.ws.Endpoint;
+<pre class="brush: java; gutter: false; theme: Default"
style="font-size:12px;">import javax.xml.ws.Endpoint;
import org.apache.cxf.Bus;
import org.apache.cxf.BusFactory;
import org.apache.cxf.transport.servlet.CXFServlet;
@@ -293,7 +293,7 @@ BusFactory.setDefaultBus(bus);
Endpoint.publish("/Greeter", new GreeterImpl());
</pre>
</div></div><p>The one thing you must ensure is that your CXFServlet is set up
to listen on that path. Otherwise the CXFServlet will never receive the
requests.</p><p><strong>NOTE:</strong></p><p>Endpoint.publish(...) is a JAX-WS
API for publishing JAX-WS endpoints. Thus, it would require the JAX-WS module
and APIs to be present. If you are not using JAX-WS or want more control over
the published endpoint properties, you should replace that call with the proper
calls to the appropriate ServerFactory.</p><p>Since CXFServlet know nothing
about the web container listening port and the application context path, you
need to specify the relative path instead of the full http address.</p><h2
id="ServletTransport-UsingtheservlettransportwithoutSpring">Using the servlet
transport without Spring</h2><p>A user who doesn't want to touch any Spring
stuff could also publish the endpoint with CXF servlet transport. First you
should extend the CXFNonSpringServlet and then override the method loadBu
s, e.g.:</p><div class="code panel pdl" style="border-width: 1px;"><div
class="codeContent panelContent pdl">
-<pre class="brush: bash; gutter: false; theme: Confluence"
style="font-size:12px;">import javax.xml.ws.Endpoint;
+<pre class="brush: java; gutter: false; theme: Default"
style="font-size:12px;">import javax.xml.ws.Endpoint;
...
@Override
@@ -314,7 +314,7 @@ Endpoint.publish("/Greeter", new Greeter
}
</pre>
</div></div><p>If you are using the Jetty as the embedded servlet engine, you
could publish endpoint like this:</p><div class="code panel pdl"
style="border-width: 1px;"><div class="codeContent panelContent pdl">
-<pre class="brush: bash; gutter: false; theme: Confluence"
style="font-size:12px;">import javax.xml.ws.Endpoint;
+<pre class="brush: java; gutter: false; theme: Default"
style="font-size:12px;">import javax.xml.ws.Endpoint;
...
// Setup the system properties to use the CXFBusFactory not the
SpringBusFactory
@@ -356,11 +356,11 @@ Endpoint.publish("/Greeter", new Greeter
}
</pre>
</div></div><h2
id="ServletTransport-AccessingtheMessageContextand/orHTTPRequestandResponse">Accessing
the MessageContext and/or HTTP Request and Response</h2><p>Sometimes you'll
want to access more specific message details in your service implementation.
One example might be accessing the actual request or response object itself.
This can be done using the WebServiceContext object.</p><p>First, declare a
private field for the <a shape="rect" class="external-link"
href="http://java.sun.com/javase/6/docs/api/javax/xml/ws/WebServiceContext.html";
rel="nofollow">WebServiceContext</a> in your service implementation, and
annotate it as a resource:</p><div class="code panel pdl" style="border-width:
1px;"><div class="codeContent panelContent pdl">
-<pre class="brush: bash; gutter: false; theme: Confluence"
style="font-size:12px;">@Resource
+<pre class="brush: java; gutter: false; theme: Default"
style="font-size:12px;">@Resource
private WebServiceContext context;
</pre>
</div></div><p>Then, within your implementing methods, you can access the
MessageContext, HttpServletRequest, and HttpServletResponse as follows:</p><div
class="code panel pdl" style="border-width: 1px;"><div class="codeContent
panelContent pdl">
-<pre class="brush: bash; gutter: false; theme: Confluence"
style="font-size:12px;">import javax.servlet.http.HttpServletRequest;
+<pre class="brush: java; gutter: false; theme: Default"
style="font-size:12px;">import javax.servlet.http.HttpServletRequest;
import javax.servlet.http.HttpServletResponse;
import javax.xml.ws.handler.MessageContext;
import org.apache.cxf.transport.http.AbstractHTTPDestination;
