cxf-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From build...@apache.org
Subject svn commit: r823119 - in /websites/production/cxf/content: cache/docs.pageCache docs/saml-web-sso.html
Date Mon, 25 Jun 2012 13:47:51 GMT
Author: buildbot
Date: Mon Jun 25 13:47:50 2012
New Revision: 823119

Log:
Production update by buildbot for cxf

Modified:
    websites/production/cxf/content/cache/docs.pageCache
    websites/production/cxf/content/docs/saml-web-sso.html

Modified: websites/production/cxf/content/cache/docs.pageCache
==============================================================================
Binary files - no diff available.

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 Mon Jun 25 13:47:50 2012
@@ -125,7 +125,7 @@ Apache CXF -- SAML Web SSO
 
 
 <div>
-<ul><li><a shape="rect" href="#SAMLWebSSO-Introduction">Introduction</a></li><ul><li><a
shape="rect" href="#SAMLWebSSO-TypicalFlow">Typical Flow</a></li></ul><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></li><ul><li><a shape="rect" href="#SAMLWebSSO-RedirectBindingFilter">Redirect
Binding Filter</a></li><li><a shape="rect" href="#SAMLWebSSO-POSTBindingFilter">POST
Binding Filter</a></li></ul><li><a shape="rect" href="#SAMLWebSSO-RequestAssertionSecurityService">Request
Assertion Security Service</a></li><li><a shape="rect" href="#SAMLWebSSO-SSOStateProvider">SSO
State Provider</a></li></ul></div>
+<ul><li><a shape="rect" href="#SAMLWebSSO-Introduction">Introduction</a></li><ul><li><a
shape="rect" href="#SAMLWebSSO-TypicalFlow">Typical Flow</a></li></ul><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></li><ul><li><a shape="rect" href="#SAMLWebSSO-RedirectBindingFilter">Redirect
Binding Filter</a></li><li><a shape="rect" href="#SAMLWebSSO-POSTBindingFilter">POST
Binding Filter</a></li><li><a shape="rect" href="#SAMLWebSSO-SigningSAMLAuthenticationRequests">Signing
SAML Authentication Requests</a></li><li><a shape="rect" href="#SAMLWebSSO-FiltersandStateManagement">Filters
and State Management</a></li></ul><li><a shape="rect" href="#SAMLWebSSO-RequestAssertionSecurityService">Request
Assertion Security Service</a></li><ul><li><a shape="rect" href="#SAM
 LWebSSO-DealingwithsignedSAMLResponses">Dealing with signed SAML Responses</a></li></ul><li><a
shape="rect" href="#SAMLWebSSO-SSOStateProvider">SSO State Provider</a></li></ul></div>
 
 <h1><a shape="rect" name="SAMLWebSSO-Introduction"></a>Introduction</h1>
 
@@ -180,6 +180,10 @@ Apache CXF -- SAML Web SSO
 
 <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 redirecting the user back to IDP via
GET and another one - via POST.</p>
 
 <h2><a shape="rect" name="SAMLWebSSO-RedirectBindingFilter"></a>Redirect
Binding Filter</h2>
@@ -221,6 +225,13 @@ Apache CXF -- SAML Web SSO
   (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/viewvc/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><a shape="rect" name="SAMLWebSSO-POSTBindingFilter"></a>POST Binding
Filter</h2>
 
 <p>POST Binding Filter is implemented by org.apache.cxf.rs.security.saml.sso.SamlPostBindingFilter.</p>
@@ -261,11 +272,13 @@ Apache CXF -- SAML Web SSO
 </pre>
 </div></div>
 
-<p>Note that the POST binding filter has the same base properties as org.apache.cxf.rs.security.saml.sso.SamlRedirectBindingFilter
has but also <br clear="none">
-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>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 see <a shape="rect" href="http://cxf.apache.org/docs/jax-rs-redirection.html#JAX-RSRedirection-WithRequestDispatcherProvider">this
page</a> for more information.</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 see <a shape="rect" href="http://cxf.apache.org/docs/jax-rs-redirection.html#JAX-RSRedirection-WithRequestDispatcherProvider">this
page</a> for more information.<br clear="none">
-Here is a typical JSP handler for binding org.apache.cxf.rs.security.saml.sso.SAMLRequestInfo
to the view:</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" style="border-width: 1px;"><div class="codeContent panelContent">
 <pre class="code-xml">
@@ -293,10 +306,134 @@ Here is a typical JSP handler for bindin
 </pre>
 </div></div>
 
+<h2><a shape="rect" name="SAMLWebSSO-SigningSAMLAuthenticationRequests"></a>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" style="border-width: 1px;"><div class="codeContent panelContent">
+<pre class="code-xml">
+<span class="code-tag">&lt;bean id=<span class="code-quote">"ssoSignedRedirectPOST"</span>
class=<span class="code-quote">"org.apache.cxf.rs.security.saml.sso.SamlPostBindingFilter"</span>&gt;</span>
+        <span class="code-tag">&lt;property name=<span class="code-quote">"idpServiceAddress"</span>
value=<span class="code-quote">"https://localhost:9443/idp"</span>/&gt;</span>
+        <span class="code-tag">&lt;property name=<span class="code-quote">"assertionConsumerServiceAddress"</span>
value=<span class="code-quote">"/racs/sso"</span>/&gt;</span>
+        <span class="code-tag">&lt;property name=<span class="code-quote">"stateProvider"</span>
ref=<span class="code-quote">"stateManager"</span>/&gt;</span>
+
+        <span class="code-tag">&lt;property name=<span class="code-quote">"signRequest"</span>
value=<span class="code-quote">"true"</span>/&gt;</span>
+
+        <span class="code-tag">&lt;property name=<span class="code-quote">"callbackHandlerClass"</span>
value=<span class="code-quote">"org.apache.cxf.samlp.sso.SSOCallbackHandler"</span>/&gt;</span>
+        <span class="code-tag">&lt;property name=<span class="code-quote">"signatureUsername"</span>
value=<span class="code-quote">"myservicekey"</span>/&gt;</span>
+        <span class="code-tag">&lt;property name=<span class="code-quote">"signaturePropertiesFile"</span>
value=<span class="code-quote">"serviceKeystore.properties"</span>/&gt;</span>
+<span class="code-tag">&lt;/bean&gt;</span> 
+
+<span class="code-tag">&lt;bean id=<span class="code-quote">"stateManager"</span>
class=<span class="code-quote">"org.apache.cxf.rs.security.saml.sso.state.EHCacheSPStateManager"</span>&gt;</span>
+    <span class="code-tag">&lt;constructor-arg ref=<span class="code-quote">"cxf"</span>/&gt;</span>
+<span class="code-tag">&lt;/bean&gt;</span>
+
+</pre>
+</div></div>
+
+<h2><a shape="rect" name="SAMLWebSSO-FiltersandStateManagement"></a>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" style="border-width: 1px;"><div class="codeContent panelContent">
+<pre class="code-java">
+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><a shape="rect" name="SAMLWebSSO-RequestAssertionSecurityService"></a>Request
Assertion Security Service</h1>
 
-<h1><a shape="rect" name="SAMLWebSSO-SSOStateProvider"></a>SSO State Provider</h1></div>
+<p>Request Assertion Security 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" style="border-width: 1px;"><div class="codeContent panelContent">
+<pre class="code-xml">
+
+<span class="code-tag">&lt;bean id=<span class="code-quote">"consumerService"</span>
class=<span class="code-quote">"org.apache.cxf.rs.security.saml.sso.RequestAssertionConsumerService"</span>&gt;</span>
+        <span class="code-tag">&lt;property name=<span class="code-quote">"stateProvider"</span>
ref=<span class="code-quote">"stateManager"</span>/&gt;</span>
+        &lt;!-- responses are expected to be deflated by default
+        <span class="code-tag">&lt;property name=<span class="code-quote">"supportDeflateEncoding"</span>
value=<span class="code-quote">"false"</span>/&gt;</span>
+        --&gt;
+        &lt;!-- 
+           responses are expected to be base64 encoded by default
+        --&gt;
+        <span class="code-tag">&lt;property name=<span class="code-quote">"supportBase64Encoding"</span>
value=<span class="code-quote">"false"</span>/&gt;</span>
+<span class="code-tag">&lt;/bean&gt;</span>
+
+<span class="code-tag">&lt;bean id=<span class="code-quote">"stateManager"</span>
class=<span class="code-quote">"org.apache.cxf.rs.security.saml.sso.state.EHCacheSPStateManager"</span>&gt;</span>
+    <span class="code-tag">&lt;constructor-arg ref=<span class="code-quote">"cxf"</span>/&gt;</span>
+<span class="code-tag">&lt;/bean&gt;</span>
+
+
+<span class="code-tag">&lt;jaxrs:server address=<span class="code-quote">"/racs"</span>&gt;</span>

+   <span class="code-tag">&lt;jaxrs:serviceBeans&gt;</span>
+       <span class="code-tag">&lt;ref bean=<span class="code-quote">"consumerService"</span>/&gt;</span>

+   <span class="code-tag">&lt;/jaxrs:serviceBeans&gt;</span>
+<span class="code-tag">&lt;/jaxrs:server&gt;</span>
+</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><a shape="rect" name="SAMLWebSSO-DealingwithsignedSAMLResponses"></a>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" style="border-width: 1px;"><div class="codeContent panelContent">
+<pre class="code-xml">
+<span class="code-tag">&lt;bean id=<span class="code-quote">"consumerService"</span>
class=<span class="code-quote">"org.apache.cxf.rs.security.saml.sso.RequestAssertionConsumerService"</span>&gt;</span>
+        <span class="code-tag">&lt;property name=<span class="code-quote">"stateProvider"</span>
ref=<span class="code-quote">"stateManager"</span>/&gt;</span>
+        <span class="code-tag">&lt;property name=<span class="code-quote">"supportBase64Encoding"</span>
value=<span class="code-quote">"false"</span>/&gt;</span>
+
+        <span class="code-tag">&lt;property name=<span class="code-quote">"signaturePropertiesFile"</span>
value=<span class="code-quote">"serviceKeystore.properties"</span>/&gt;</span>
+        <span class="code-tag">&lt;property name=<span class="code-quote">"enforceAssertionsSigned"</span>
value=<span class="code-quote">"false"</span>/&gt;</span>
+        <span class="code-tag">&lt;property name=<span class="code-quote">"callbackHandlerClass"</span>
value=<span class="code-quote">"org.apache.cxf.samlp.sso.SSOCallbackHandler"</span>/&gt;</span>
+<span class="code-tag">&lt;/bean&gt;</span>
+</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>
+
+<h1><a shape="rect" name="SAMLWebSSO-SSOStateProvider"></a>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 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>.
Users can register their own custom implementations if required.</p></div>
            </div>
            <!-- Content -->
          </td>



Mime
View raw message