cxf-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From conflue...@apache.org
Subject [CONF] Apache CXF Documentation > SAML Web SSO
Date Mon, 17 Jun 2013 08:52:00 GMT
<html>
<head>
    <base href="https://cwiki.apache.org/confluence">
            <link rel="stylesheet" href="/confluence/s/2042/9/1/_/styles/combined.css?spaceKey=CXF20DOC&amp;forWysiwyg=true"
type="text/css">
    </head>
<body style="background: white;" bgcolor="white" class="email-body">
<div id="pageContent">
<div id="notificationFormat">
<div class="wiki-content">
<div class="email">
    <h2><a href="https://cwiki.apache.org/confluence/display/CXF20DOC/SAML+Web+SSO">SAML
Web SSO</a></h2>
    <h4>Page <b>edited</b> by             <a href="https://cwiki.apache.org/confluence/display/~coheigea@apache.org">Colm
O hEigeartaigh</a>
    </h4>
        <br/>
                         <h4>Changes (1)</h4>
                                 
    
<div id="page-diffs">
                    <table class="diff" cellpadding="0" cellspacing="0">
    
            <tr><td class="diff-snipped" >...<br></td></tr>
            <tr><td class="diff-unchanged" > <br>        &lt;property
name=&quot;useDeflateEncoding&quot; value=&quot;true&quot;/&gt; <br></td></tr>
            <tr><td class="diff-changed-lines" ><span class="diff-changed-words">&lt;/bean<span
class="diff-added-chars"style="background-color: #dfd;">&gt;</span></span>
<br></td></tr>
            <tr><td class="diff-unchanged" > <br>&lt;bean id=&quot;samlRequestFormCreator&quot;
class=&quot;org.apache.cxf.jaxrs.provider.RequestDispatcherProvider&quot;&gt;
<br></td></tr>
            <tr><td class="diff-snipped" >...<br></td></tr>
    
            </table>
    </div>                            <h4>Full Content</h4>
                    <div class="notificationGreySide">
        <p><span style="font-size:2em;font-weight:bold"> JAX-RS: SAML Web SSO</span></p>


<div>
<ul>
    <li><a href='#SAMLWebSSO-Introduction'>Introduction</a></li>
<ul>
    <li><a href='#SAMLWebSSO-TypicalFlow'>Typical Flow</a></li>
</ul>
    <li><a href='#SAMLWebSSO-Mavendependencies'>Maven dependencies</a></li>
    <li><a href='#SAMLWebSSO-IdentityProvider'>Identity Provider</a></li>
    <li><a href='#SAMLWebSSO-ServiceProviderSecurityFilter'>Service Provider Security
Filter</a></li>
<ul>
    <li><a href='#SAMLWebSSO-RedirectBindingFilter'>Redirect Binding Filter</a></li>
    <li><a href='#SAMLWebSSO-POSTBindingFilter'>POST Binding Filter</a></li>
    <li><a href='#SAMLWebSSO-SigningSAMLAuthenticationRequests'>Signing SAML Authentication
Requests</a></li>
    <li><a href='#SAMLWebSSO-FiltersandStateManagement'>Filters and State Management</a></li>
</ul>
    <li><a href='#SAMLWebSSO-RequestAssertionConsumerService'>Request Assertion
Consumer Service</a></li>
<ul>
    <li><a href='#SAMLWebSSO-DealingwithsignedSAMLResponses'>Dealing with signed
SAML Responses</a></li>
</ul>
    <li><a href='#SAMLWebSSO-SSOStateProvider'>SSO State Provider</a></li>
<ul>
    <li><a href='#SAMLWebSSO-DistributedStateManagement'>Distributed State Management</a></li>
</ul>
</ul></div>

<h1><a name="SAMLWebSSO-Introduction"></a>Introduction</h1>

<p><a href="http://en.wikipedia.org/wiki/Single_sign-on" class="external-link" 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 href="http://docs.oasis-open.org/security/saml/v2.0/saml-profiles-2.0-os.pdf" class="external-link"
rel="nofollow">profile</a>. This <a href="http://en.wikipedia.org/wiki/SAML_2.0"
class="external-link" rel="nofollow">page</a> also offers a good overview of the
<a href="http://en.wikipedia.org/wiki/SAML_2.0#Web_Browser_SSO_Profile" class="external-link"
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 following components are required to get SSO supported:</p>

<ul class="alternate" type="square">
	<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><a name="SAMLWebSSO-TypicalFlow"></a>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/>
2. Service Provider Security Filter checks if the security context is available <br/>
   and redirects the user to IDP with a SAML SSO request<br/>
3. IDP challenges the user with the authentication dialog and redirects the user to<br/>
   Request Assertion Consumer Service (RACS) after the user has authenticated<br/>
4. RACS validates the response from IDP, establishes a security context and redirects the
user <br/>
   to the original application endpoint<br/>
5. Service Provider Security Filter enforces that a valid security context is available and
lets the user<br/>
   access the custom application.</p>

<h1><a name="SAMLWebSSO-Mavendependencies"></a>Maven dependencies</h1>

<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-xml">
<span class="code-tag">&lt;dependency&gt;</span>
  <span class="code-tag">&lt;groupId&gt;</span>org.apache.cxf<span
class="code-tag">&lt;/groupId&gt;</span>
  <span class="code-tag">&lt;artifactId&gt;</span>cxf-rt-rs-security-sso-saml<span
class="code-tag">&lt;/artifactId&gt;</span>
  <span class="code-tag">&lt;version&gt;</span>2.6.1<span class="code-tag">&lt;/version&gt;</span>
<span class="code-tag">&lt;/dependency&gt;</span>
</pre>
</div></div>

<h1><a name="SAMLWebSSO-IdentityProvider"></a>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 href="http://cxf.apache.org/fediz.html" class="external-link"
rel="nofollow">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><a name="SAMLWebSSO-ServiceProviderSecurityFilter"></a>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 href="http://en.wikipedia.org/wiki/SAML_2.0#Web_Browser_SSO_Profile" class="external-link"
rel="nofollow">this page</a> for the example and appends it to the IDP Service URI
or gets it POSTed to IDP.<br/>
Additionally, a RelayState token pointing to the state of the current user request is also
included which IDP will <br/>
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 name="SAMLWebSSO-RedirectBindingFilter"></a>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" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-xml">
<span class="code-tag">&lt;bean id=<span class="code-quote">"serviceBean"</span>
class=<span class="code-quote">"org.apache.cxf.samlp.sso.BookStore"</span>/&gt;</span>

<span class="code-tag">&lt;jaxrs:server address=<span class="code-quote">"/app1"</span>&gt;</span>

       <span class="code-tag">&lt;jaxrs:serviceBeans&gt;</span>
          <span class="code-tag">&lt;ref bean=<span class="code-quote">"serviceBean"</span>/&gt;</span>
       <span class="code-tag">&lt;/jaxrs:serviceBeans&gt;</span>
       <span class="code-tag">&lt;jaxrs:providers&gt;</span>
          <span class="code-tag">&lt;ref bean=<span class="code-quote">"redirectGetFilter"</span>/&gt;</span>
       <span class="code-tag">&lt;/jaxrs:providers&gt;</span>
<span class="code-tag">&lt;/jaxrs:server&gt;</span>

<span class="code-tag">&lt;bean id=<span class="code-quote">"redirectGetFilter"</span>
class=<span class="code-quote">"org.apache.cxf.rs.security.saml.sso.SamlRedirectBindingFilter"</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"><span class="code-comment">&lt;!-- both relative
and absolute URIs are supported --&gt;</span></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;/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>

<p>Note that at the very minimum the filter needs to have 3 properties set-up:<br/>
1. IDP service address<br/>
2. RACS address - it can be absolute or relative if RACS is collocated <br/>
  (shares the same web application context) with the application endpoint.<br/>
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 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"
class="external-link" rel="nofollow">AuthnRequestBuilder</a> authnRequestBuilder
- A builder that constructs the SAML Request. It defaults to <a 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"
class="external-link" rel="nofollow">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/>
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 name="SAMLWebSSO-POSTBindingFilter"></a>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" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-xml">
<span class="code-tag">&lt;bean id=<span class="code-quote">"serviceBean"</span>
class=<span class="code-quote">"org.apache.cxf.samlp.sso.BookStore"</span>/&gt;</span>
<span class="code-tag">&lt;jaxrs:server address=<span class="code-quote">"/app2"</span>&gt;</span>

    <span class="code-tag">&lt;jaxrs:serviceBeans&gt;</span>
       <span class="code-tag">&lt;ref bean=<span class="code-quote">"serviceBean"</span>/&gt;</span>
     <span class="code-tag">&lt;/jaxrs:serviceBeans&gt;</span>
     <span class="code-tag">&lt;jaxrs:providers&gt;</span>
          <span class="code-tag">&lt;ref bean=<span class="code-quote">"ssoRedirectPOST"</span>/&gt;</span>
          <span class="code-tag">&lt;ref bean=<span class="code-quote">"samlRequestFormCreator"</span>/&gt;</span>

     <span class="code-tag">&lt;/jaxrs:providers&gt;</span>
       
<span class="code-tag">&lt;/jaxrs:server&gt;</span>

<span class="code-tag">&lt;bean id=<span class="code-quote">"ssoRedirectPOST"</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">"useDeflateEncoding"</span>
value=<span class="code-quote">"true"</span>/&gt;</span>
<span class="code-tag">&lt;/bean&gt;</span>

<span class="code-tag">&lt;bean id=<span class="code-quote">"samlRequestFormCreator"</span>
class=<span class="code-quote">"org.apache.cxf.jaxrs.provider.RequestDispatcherProvider"</span>&gt;</span>
      <span class="code-tag">&lt;property name=<span class="code-quote">"dispatcherName"</span>
value=<span class="code-quote">"jsp"</span>/&gt;</span>
      <span class="code-tag">&lt;property name=<span class="code-quote">"useClassNames"</span>
value=<span class="code-quote">"true"</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>

<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 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"
class="external-link" rel="nofollow">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 href="http://cxf.apache.org/docs/jax-rs-redirection.html#JAX-RSRedirection-WithRequestDispatcherProvider"
class="external-link" rel="nofollow">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" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-xml">
<span class="code-tag">&lt;%@ page import=<span class="code-quote">"javax.servlet.http.HttpServletRequest,org.apache.cxf.rs.security.saml.sso.SamlRequestInfo"</span>
%&gt;</span>

&lt;%
    SamlRequestInfo data = (SamlRequestInfo)request.getAttribute(<span class="code-quote">"samlrequestinfo"</span>);
%&gt;
<span class="code-tag">&lt;html xmlns=<span class="code-quote">"http://www.w3.org/1999/xhtml"</span>&gt;</span>
<span class="code-tag">&lt;body onLoad=<span class="code-quote">"document.forms[0].submit();"</span>&gt;</span>
   <span class="code-tag">&lt;form action=<span class="code-quote">"&lt;%=
data.getIdpServiceAddress() %&gt;</span>"</span> method=<span class="code-quote">"POST"</span>&gt;
       <span class="code-tag">&lt;div&gt;</span>             
        &lt;input type=<span class="code-quote">"hidden"</span> name=<span
class="code-quote">"SAMLRequest"</span>
                value=<span class="code-quote">"<span class="code-tag">&lt;%=
data.getSamlRequest() %&gt;</span>"</span>/&gt;
        &lt;input type=<span class="code-quote">"hidden"</span> name=<span
class="code-quote">"RelayState"</span>
                value=<span class="code-quote">"<span class="code-tag">&lt;%=
data.getRelayState() %&gt;</span>"</span>/&gt;
       <span class="code-tag">&lt;/div&gt;</span>
        <span class="code-tag">&lt;div&gt;</span>
         <span class="code-tag">&lt;input type=<span class="code-quote">"submit"</span>
value=<span class="code-quote">"Continue"</span>/&gt;</span>
       <span class="code-tag">&lt;/div&gt;</span>
   <span class="code-tag">&lt;/form&gt;</span>
 
<span class="code-tag">&lt;/body&gt;</span>
<span class="code-tag">&lt;/html&gt;</span>
</pre>
</div></div>

<h2><a 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 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 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"
class="external-link" rel="nofollow">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 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"
class="external-link" rel="nofollow">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/>
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/>
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 name="SAMLWebSSO-RequestAssertionConsumerService"></a>Request Assertion
Consumer 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/>
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 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"
class="external-link" rel="nofollow">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 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"
class="external-link" rel="nofollow">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 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"
class="external-link" rel="nofollow">TokenReplayCache</a> replayCache - A TokenReplayCache
implementation to store Assertion IDs for the POST binding to guard against replay attacks.
The <a 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"
class="external-link" rel="nofollow">default</a> uses an implementation based on
EhCache.</li>
</ul>



<h2><a 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 name="SAMLWebSSO-SSOStateProvider"></a>SSO State Provider</h1>

<p>SP Security Filters and RACS depend on the custom <a 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"
class="external-link" rel="nofollow">SPStateManager</a> implementation for persisting
the current request and security context state. </p>

<p>CXF ships a basic <a 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"
class="external-link" rel="nofollow">MemorySPStateProvider</a> and an <a href="http://ehcache.org/"
class="external-link" rel="nofollow">EhCache</a>-based <a 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"
class="external-link" rel="nofollow">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" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-xml">
<span class="code-tag">&lt;ehcache xsi:noNamespaceSchemaLocation=<span class="code-quote">"ehcache.xsd"</span>
updateCheck=<span class="code-quote">"false"</span> monitoring=<span class="code-quote">"autodetect"</span>
dynamicConfig=<span class="code-quote">"true"</span>&gt;</span>

    <span class="code-tag">&lt;diskStore path=<span class="code-quote">"/home/username/work/ehcache"</span>/&gt;</span>

    &lt;defaultCache
            maxEntriesLocalHeap=<span class="code-quote">"5000"</span>
            timeToIdleSeconds=<span class="code-quote">"3600"</span>
            timeToLiveSeconds=<span class="code-quote">"3600"</span>
            overflowToDisk=<span class="code-quote">"true"</span>
            maxElementsOnDisk=<span class="code-quote">"10000000"</span>
            diskPersistent=<span class="code-quote">"true"</span>
            diskExpiryThreadIntervalSeconds=<span class="code-quote">"120"</span>
            memoryStoreEvictionPolicy=<span class="code-quote">"LRU"</span>
            /&gt;
<span class="code-tag">&lt;/ehcache&gt;</span>

Assuming this configuration is saved in WEB-INF/ehcache.xml, the EhCache provider can be configured
as follows:

{code:xml}
<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 value=<span class="code-quote">"/WEB-INF/ehcache.xml"</span>/&gt;</span>
<span class="code-tag">&lt;/bean&gt;</span>
</pre>
</div></div>

<h2><a name="SAMLWebSSO-DistributedStateManagement"></a>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 filters protecting
the individual servers and RACS will be shared.<br/>
One approach is to setup the Ehcache provider to use <a href="http://ehcache.org/documentation/configuration/distributed-cache-configuration"
class="external-link" 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 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"
class="external-link" rel="nofollow">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 panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-xml">
    <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.HTTPSPStateManager"</span>/&gt;</span>

    <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">"signaturePropertiesFile"</span>
value=<span class="code-quote">"serviceKeystore.properties"</span>/&gt;</span>
        <span class="code-tag">&lt;property name=<span class="code-quote">"callbackHandlerClass"</span>
value=<span class="code-quote">"oauth2.sso.SSOCallbackHandler"</span>/&gt;</span>
    <span class="code-tag">&lt;/bean&gt;</span>
    
    <span class="code-tag">&lt;jaxrs:server address=<span class="code-quote">"/"</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;ref bean=<span class="code-quote">"stateManager"</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>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/>
Here is an example of how the SPStateManagers at the individual SSO filter end can use this
HTTP endpoint:</p>

<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-xml">

&lt;jaxrs:client id=<span class="code-quote">"stateManager"</span>
         address=<span class="code-quote">"https://localhost:${racs.port}/racs"</span>
         serviceClass=<span class="code-quote">"org.apache.cxf.rs.security.saml.sso.state.HTTPSPStateManager"</span>/&gt;
         
 <span class="code-tag">&lt;bean id=<span class="code-quote">"ssoRedirectURI"</span>
class=<span class="code-quote">"org.apache.cxf.rs.security.saml.sso.SamlRedirectBindingFilter"</span>&gt;</span>
    <span class="code-tag">&lt;property name=<span class="code-quote">"idpServiceAddress"</span>
value=<span class="code-quote">"${idp.address}"</span>/&gt;</span>
    &lt;property name=<span class="code-quote">"assertionConsumerServiceAddress"</span>

               value=<span class="code-quote">"https://localhost:${racs.port}/racs/sso"</span>/&gt;
    <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">"addWebAppContext"</span>
value=<span class="code-quote">"false"</span>/&gt;</span> 
 <span class="code-tag">&lt;/bean&gt;</span>

</pre>
</div></div>


<p>Note that a JAX-RS Client proxy to the HTTPSPStateManager endpoint is used as SPStateManager
reference.</p>

<p>The alternative to having a distributed state cache be set up is to simply have a
RACS endpoint collocated with every individual web application constituting the bigger application,
see the earlier section describing SSO filters on how this can be easily set up. One possible
downside of it is that there will be no centralized store managing the state required by different
filters and RACS which in turn can make it more difficult to audit and log all the SSO-related
activities spanning across all the bigger application.  </p>
    </div>
        <div id="commentsSection" class="wiki-content pageSection">
        <div style="float: right;">
            <a href="https://cwiki.apache.org/confluence/users/viewnotifications.action"
class="grey">Change Notification Preferences</a>
        </div>
        <a href="https://cwiki.apache.org/confluence/display/CXF20DOC/SAML+Web+SSO">View
Online</a>
        |
        <a href="https://cwiki.apache.org/confluence/pages/diffpagesbyversion.action?pageId=27850442&revisedVersion=12&originalVersion=11">View
Changes</a>
                |
        <a href="https://cwiki.apache.org/confluence/display/CXF20DOC/SAML+Web+SSO?showComments=true&amp;showCommentArea=true#addcomment">Add
Comment</a>
            </div>
</div>
</div>
</div>
</div>
</body>
</html>

Mime
View raw message