You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@cxf.apache.org by bu...@apache.org on 2018/09/11 16:58:03 UTC
svn commit: r1034996 - in /websites/production/cxf/content:
cache/docs.pageCache docs/33-migration-guide.html docs/jax-rs-saml.html
Author: buildbot
Date: Tue Sep 11 16:58:03 2018
New Revision: 1034996
Log:
Production update by buildbot for cxf
Modified:
websites/production/cxf/content/cache/docs.pageCache
websites/production/cxf/content/docs/33-migration-guide.html
websites/production/cxf/content/docs/jax-rs-saml.html
Modified: websites/production/cxf/content/cache/docs.pageCache
==============================================================================
Binary files - no diff available.
Modified: websites/production/cxf/content/docs/33-migration-guide.html
==============================================================================
--- websites/production/cxf/content/docs/33-migration-guide.html (original)
+++ websites/production/cxf/content/docs/33-migration-guide.html Tue Sep 11 16:58:03 2018
@@ -107,7 +107,7 @@ Apache CXF -- 3.3 Migration Guide
<td height="100%">
<!-- Content -->
<div class="wiki-content">
-<div id="ConfluenceContent"><h3 id="id-3.3MigrationGuide-MajorNotes:">Major Notes:</h3><h3 id="id-3.3MigrationGuide-NewFeatures:">New Features:</h3><h3 id="id-3.3MigrationGuide-Majordependencychanges:">Major dependency changes:</h3></div>
+<div id="ConfluenceContent"><h3 id="id-3.3MigrationGuide-MajorNotes:">Major Notes:</h3><ul><li>The claimType of the <a shape="rect" class="external-link" href="https://github.com/apache/cxf/blob/master/rt/security/src/main/java/org/apache/cxf/rt/security/claims/Claim.java" rel="nofollow">Claim</a> class is now a "String" instead of a "URI".  This might break existing ClaimsHandler implementations in the STS. In addition, the ClaimsHandler interface now returns a List<String> for getSupportedClaimTypes() instead of List<URI>.</li></ul><h3 id="id-3.3MigrationGuide-NewFeatures:">New Features:</h3><h3 id="id-3.3MigrationGuide-Majordependencychanges:">Major dependency changes:</h3></div>
</div>
<!-- Content -->
</td>
Modified: websites/production/cxf/content/docs/jax-rs-saml.html
==============================================================================
--- websites/production/cxf/content/docs/jax-rs-saml.html (original)
+++ websites/production/cxf/content/docs/jax-rs-saml.html Tue Sep 11 16:58:03 2018
@@ -121,11 +121,11 @@ Apache CXF -- JAX-RS SAML
<br clear="none"></p><p><style type="text/css">/*<![CDATA[*/
-div.rbtoc1536598610095 {padding: 0px;}
-div.rbtoc1536598610095 ul {list-style: disc;margin-left: 0px;}
-div.rbtoc1536598610095 li {margin-left: 0px;padding-left: 0px;}
+div.rbtoc1536685043361 {padding: 0px;}
+div.rbtoc1536685043361 ul {list-style: disc;margin-left: 0px;}
+div.rbtoc1536685043361 li {margin-left: 0px;padding-left: 0px;}
-/*]]>*/</style></p><div class="toc-macro rbtoc1536598610095">
+/*]]>*/</style></p><div class="toc-macro rbtoc1536685043361">
<ul class="toc-indentation"><li><a shape="rect" href="#JAX-RSSAML-Introduction">Introduction</a></li><li><a shape="rect" href="#JAX-RSSAML-Backwardscompatibilityconfigurationnote">Backwards compatibility configuration note</a></li><li><a shape="rect" href="#JAX-RSSAML-Mavendependencies">Maven dependencies</a></li><li><a shape="rect" href="#JAX-RSSAML-EnvelopedSAMLassertions">Enveloped SAML assertions</a></li><li><a shape="rect" href="#JAX-RSSAML-SAMLassertionsinAuthorizationheader">SAML assertions in Authorization header</a></li><li><a shape="rect" href="#JAX-RSSAML-SAMLassertionsasFormvalues">SAML assertions as Form values</a></li><li><a shape="rect" href="#JAX-RSSAML-CreatingSAMLAssertions">Creating SAML Assertions</a></li><li><a shape="rect" href="#JAX-RSSAML-SAMLAssertionValidation">SAML Assertion Validation</a></li><li><a shape="rect" href="#JAX-RSSAML-SAMLAuthorization">SAML Authorization</a>
<ul class="toc-indentation"><li><a shape="rect" href="#JAX-RSSAML-ClaimsBasedAccessControl">Claims Based Access Control</a></li><li><a shape="rect" href="#JAX-RSSAML-RoleBasedAccessControl">Role Based Access Control</a></li></ul>
</li><li><a shape="rect" href="#JAX-RSSAML-SAMLWebSSOProfile">SAML Web SSO Profile</a></li></ul>
@@ -359,7 +359,7 @@ Payload: name=CXF&id=125&SAMLTok
</div></div><p>The client code is the same as in the SAML assertions in Authorization header section except than an instance of SamlFormOutInterceptor has to be registered:</p><div class="code panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl">
<pre class="brush: java; gutter: false; theme: Default">bean.getOutInterceptors().add(new SamlFormOutInterceptor());
</pre>
-</div></div><h1 id="JAX-RSSAML-CreatingSAMLAssertions">Creating SAML Assertions</h1><p>If you use CXF JAX-RS client API to experiment with SAML then all you need to do is to register an appropriate out interceptor as shown in the above code fragments. The interceptor will ensure that a SAML assertion is created and added inside the XML envelope, as a form or HTTP header value.<br clear="none"> All of the SAML output interceptors depend on a "security.saml-callback-handler" property linking to a custom javax.security.auth.callback.Callback implementation which in its handle(Callbacks) method provides the information which is needed to create a SAML assertion to a org.apache.ws.security.saml.ext.SAMLCallback Callback instance, for example, see this <a shape="rect" class="external-link" href="http://svn.apache.org/repos/asf/cxf/trunk/systests/rs-security/src/test/java/org/apache/cxf/systest/jaxrs/security/saml/SamlCallbackHandler.java">custom implementation</a>.</p><p>More involved cas
es with SAML assertions being created by identity providers will be supported, with the help of CXF (WS) STSClient when needed.</p><h1 id="JAX-RSSAML-SAMLAssertionValidation">SAML Assertion Validation</h1><p>When SAML assertions are received on the server side, they are validated to make sure that the enveloped signatures are correct. SubjectConfirmation methods (sender-vouches, holder-of-key, bearer) are also checked. <br clear="none"> The validation can be delegated to STS if needed. By default, server side SAML handlers have a "samlValidator" property set to an instance of org.apache.ws.security.validate.SamlAssertionValidator which does a thorough validation of the assertion. If needed org.apache.cxf.ws.security.trust.STSTokenValidator can be set instead which will use STS to validate the assertion.<br clear="none"> Custom validators extending WSS4J SamlAssertionValidator and doing the additional application-specific validation can be registered if needed.</p><p>Note the fact th
at the default validation relies a lot on the code heavily utilized by the WS-Security implementation should be of no concern - it is an example of the integration on its own in order to get the validation done. For example, WS-* STS are heavily used in the enterprise today and it simply makes a complete sense to rely on it to validate a SAML assertion if it is possible.</p><p>SubjectConfirmation sender-vouches and holder-of-key methods can be easily validated with enveloped SAML assertions given that the embedded SAML signatures and key info can be checked against the signature used to sign the envelope or a custom payload like Book.</p><p>At the moment these methods can not be properly validated when the assertion is provided in a header or in the form, the additional signature signing the encoded SAML token will be needed - this will be supported in due time. Use "bearer" in those cases.</p><h1 id="JAX-RSSAML-SAMLAuthorization">SAML Authorization</h1><p>SAML assertions may contai
n so-called claims which are represented by a sequence of SAML AttributeStatements containing one or more Attributes, for example:</p><div class="code panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl">
+</div></div><h1 id="JAX-RSSAML-CreatingSAMLAssertions">Creating SAML Assertions</h1><p>If you use CXF JAX-RS client API to experiment with SAML then all you need to do is to register an appropriate out interceptor as shown in the above code fragments. The interceptor will ensure that a SAML assertion is created and added inside the XML envelope, as a form or HTTP header value.<br clear="none"> All of the SAML output interceptors depend on a "security.saml-callback-handler" property linking to a custom javax.security.auth.callback.Callback implementation which in its handle(Callbacks) method provides the information which is needed to create a SAML assertion to a org.apache.ws.security.saml.ext.SAMLCallback Callback instance, for example, see this <a shape="rect" class="external-link" href="https://github.com/apache/cxf/blob/master/systests/rs-security/src/test/java/org/apache/cxf/systest/jaxrs/security/saml/SamlCallbackHandler.java" rel="nofollow">custom implementation</a>.</p><p>Mo
re involved cases with SAML assertions being created by identity providers will be supported, with the help of CXF (WS) STSClient when needed.</p><h1 id="JAX-RSSAML-SAMLAssertionValidation">SAML Assertion Validation</h1><p>When SAML assertions are received on the server side, they are validated to make sure that the enveloped signatures are correct. SubjectConfirmation methods (sender-vouches, holder-of-key, bearer) are also checked. <br clear="none"> The validation can be delegated to STS if needed. By default, server side SAML handlers have a "samlValidator" property set to an instance of org.apache.ws.security.validate.SamlAssertionValidator which does a thorough validation of the assertion. If needed org.apache.cxf.ws.security.trust.STSTokenValidator can be set instead which will use STS to validate the assertion.<br clear="none"> Custom validators extending WSS4J SamlAssertionValidator and doing the additional application-specific validation can be registered if needed.</p><p>N
ote the fact that the default validation relies a lot on the code heavily utilized by the WS-Security implementation should be of no concern - it is an example of the integration on its own in order to get the validation done. For example, WS-* STS are heavily used in the enterprise today and it simply makes a complete sense to rely on it to validate a SAML assertion if it is possible.</p><p>SubjectConfirmation sender-vouches and holder-of-key methods can be easily validated with enveloped SAML assertions given that the embedded SAML signatures and key info can be checked against the signature used to sign the envelope or a custom payload like Book.</p><p>At the moment these methods can not be properly validated when the assertion is provided in a header or in the form, the additional signature signing the encoded SAML token will be needed - this will be supported in due time. Use "bearer" in those cases.</p><h1 id="JAX-RSSAML-SAMLAuthorization">SAML Authorization</h1><p>SAML assert
ions may contain so-called claims which are represented by a sequence of SAML AttributeStatements containing one or more Attributes, for example:</p><div class="code panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl">
<pre class="brush: java; gutter: false; theme: Default"><saml2:Assertion>
<!-- ... -->
<saml2:AttributeStatement>
@@ -376,7 +376,7 @@ Payload: name=CXF&id=125&SAMLTok
<!-- ... -->
</saml2:Assertion>
</pre>
-</div></div><p>An individual claim is scoped by NameFormat and Name attribute. NameFormat is similar to a namespace, while Name identifies what the value of this claim represents, for example, in the above fragment two claims are provided, one has a value "user" which represents a role of the assertion's Subject, another one has a value of "password" which identifies the way Subject authenticated itself, i.e, Subject provided its password (presumably to IDP).</p><p>Now, what is interesting is to see if it is possible to use these claims with Role-Based Access-Control (for example, with endpoints relying on @RolesAllowed annotations) as well as with the more complex authorization logic (for example, let this resource be invoked only if Subject used a password to get authenticated at IDP).</p><h2 id="JAX-RSSAML-ClaimsBasedAccessControl">Claims Based Access Control</h2><p>CXF JAX-RS offers an extension letting users to enforce a new fine-grained Claims Based Access Control (CBAC) based
on <a shape="rect" class="external-link" href="http://svn.apache.org/repos/asf/cxf/trunk/api/src/main/java/org/apache/cxf/security/claims/authorization/Claim.java">Claim</a> and <a shape="rect" class="external-link" href="http://svn.apache.org/repos/asf/cxf/trunk/api/src/main/java/org/apache/cxf/security/claims/authorization/Claims.java">Claims</a> annotations as well as <a shape="rect" class="external-link" href="http://svn.apache.org/repos/asf/cxf/trunk/api/src/main/java/org/apache/cxf/security/claims/authorization/ClaimMode.java">ClaimMode</a> enum class.</p><p><strong>Note</strong> a package for Claim, Claims and ClaimMode annotations has changed from "org.apache.cxf.rs.security.saml.authorization" to "org.apache.cxf.security.claims.authorization". Starting from CXF 2.7.1, the default name format for claims is "urn:oasis:names:tc:SAML:2.0:attrname-format:unspecified" instead of "http://schemas.xmlsoap.org/ws/2005/05/identity/claims".</p><p>Here is a simple code fragment:</p><di
v class="code panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl">
+</div></div><p>An individual claim is scoped by NameFormat and Name attribute. NameFormat is similar to a namespace, while Name identifies what the value of this claim represents, for example, in the above fragment two claims are provided, one has a value "user" which represents a role of the assertion's Subject, another one has a value of "password" which identifies the way Subject authenticated itself, i.e, Subject provided its password (presumably to IDP).</p><p>Now, what is interesting is to see if it is possible to use these claims with Role-Based Access-Control (for example, with endpoints relying on @RolesAllowed annotations) as well as with the more complex authorization logic (for example, let this resource be invoked only if Subject used a password to get authenticated at IDP).</p><h2 id="JAX-RSSAML-ClaimsBasedAccessControl">Claims Based Access Control</h2><p>CXF JAX-RS offers an extension letting users to enforce a new fine-grained Claims Based Access Control (CBAC) based
on <a shape="rect" class="external-link" href="https://github.com/apache/cxf/blob/master/core/src/main/java/org/apache/cxf/security/claims/authorization/Claim.java" rel="nofollow">Claim</a> and <a shape="rect" class="external-link" href="https://github.com/apache/cxf/blob/master/core/src/main/java/org/apache/cxf/security/claims/authorization/Claims.java" rel="nofollow">Claims</a> annotations as well as <a shape="rect" class="external-link" href="https://github.com/apache/cxf/blob/master/core/src/main/java/org/apache/cxf/security/claims/authorization/ClaimMode.java" rel="nofollow">ClaimMode</a> enum class.</p><p><strong>Note</strong> a package for Claim, Claims and ClaimMode annotations has changed from "org.apache.cxf.rs.security.saml.authorization" to "org.apache.cxf.security.claims.authorization". Starting from CXF 2.7.1, the default name format for claims is "urn:oasis:names:tc:SAML:2.0:attrname-format:unspecified" instead of "http://schemas.xmlsoap.org/ws/2005/05/identity/claim
s".</p><p>Here is a simple code fragment:</p><div class="code panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl">
<pre class="brush: java; gutter: false; theme: Default">import org.apache.cxf.rs.security.saml.authorization.Claim;
import org.apache.cxf.rs.security.saml.authorization.Claims;
@@ -466,7 +466,7 @@ public class SecureClaimBookStore {
</div></div><p>In the above example, getBookList() can be invoked if Subject has a Claim with the value "user"; addBook() has it overridden - "admin" is expected and the authentication format Claim too; getBook() can be invoked if Subject has a Claim with the value "user" and it also must have the authentication format Claim with the value "password" - or no such Claim at all.</p><p>org.apache.cxf.rs.security.saml.authorization.ClaimsAuthorizingInterceptor enforces the CBAC rules. This filter can be overridden and configured with the rules directly which can be useful if no Claim-related annotations are expected in the code. Map nameAliases and formatAliases properties are supported to make @Claim annotations look a bit simpler, for example:</p><div class="code panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl">
<pre class="brush: java; gutter: false; theme: Default">@Claim(name = "auth-format", format = "authentication", value = {"password" })
</pre>
-</div></div><p>where "auth-format" and "authentication" are aliases for "http://claims/authentication-format" and "http://claims/authentication" respectively.</p><p>Given the above example, the question is how to extract the information available in a SAML Assertion for the current request to succeed in passing through the security filter enforcing the CBAC rules.</p><p>The first and most important thing which needs to be done is to verify that an assertion Subject can be mapped to a recognized identity instance.</p><p>There is a number of ways a Subject can be validated.</p><p>If STS is asked to validate the assertion then a successful response from IDP will likely be good enough for CXF to trust the identity of the provider.<br clear="none"> If the assertion signature is verified locally using the public key of IDP then it could a good enough confirmation too.</p><p>Alternatively, a custom validator, extending either org.apache.ws.security.validate.SamlAssertionValidator or CXF SA
ML <a shape="rect" class="external-link" href="http://svn.apache.org/repos/asf/cxf/trunk/rt/rs/security/xml/src/main/java/org/apache/cxf/rs/security/saml/authorization/SecurityContextProvider.java">SecurityContextProvider</a> <a shape="rect" class="external-link" href="http://svn.apache.org/repos/asf/cxf/trunk/rt/rs/security/xml/src/main/java/org/apache/cxf/rs/security/saml/authorization/SecurityContextProviderImpl.java">implementation</a> can be registered with the server side SAML handler.</p><p>The latter option is preferred because not only one can validate Subject - but also ensure that a resulting SecurityContext will return a user Principal with a proper name - given that the actual Subject name available in the assertion may need to be translated to a name recognized by the local security stores or application. A combination of the assertion's Subject and AttributeStatement elements may need to be checked to establish a real name.</p><p>In cases like this you may want to reg
ister a custom SecurityContextProvider even if you have STS validating the assertion. Yet another reason is to retrieve the information about roles for a given Subject or map the assertion claims to roles for working with the RBAC to succeed, see the next section for more information.</p><p>Have a look please at this server configuration example:</p><div class="code panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl">
+</div></div><p>where "auth-format" and "authentication" are aliases for "http://claims/authentication-format" and "http://claims/authentication" respectively.</p><p>Given the above example, the question is how to extract the information available in a SAML Assertion for the current request to succeed in passing through the security filter enforcing the CBAC rules.</p><p>The first and most important thing which needs to be done is to verify that an assertion Subject can be mapped to a recognized identity instance.</p><p>There is a number of ways a Subject can be validated.</p><p>If STS is asked to validate the assertion then a successful response from IDP will likely be good enough for CXF to trust the identity of the provider.<br clear="none"> If the assertion signature is verified locally using the public key of IDP then it could a good enough confirmation too.</p><p>Alternatively, a custom validator, extending either org.apache.ws.security.validate.SamlAssertionValidator or CXF SA
ML <a shape="rect" class="external-link" href="https://github.com/apache/cxf/blob/master/rt/rs/security/xml/src/main/java/org/apache/cxf/rs/security/saml/authorization/SecurityContextProvider.java" rel="nofollow">SecurityContextProvider</a> <a shape="rect" class="external-link" href="https://github.com/apache/cxf/blob/master/rt/rs/security/xml/src/main/java/org/apache/cxf/rs/security/saml/authorization/SecurityContextProviderImpl.java" rel="nofollow">implementation</a> can be registered with the server side SAML handler.</p><p>The latter option is preferred because not only one can validate Subject - but also ensure that a resulting SecurityContext will return a user Principal with a proper name - given that the actual Subject name available in the assertion may need to be translated to a name recognized by the local security stores or application. A combination of the assertion's Subject and AttributeStatement elements may need to be checked to establish a real name.</p><p>In cases
like this you may want to register a custom SecurityContextProvider even if you have STS validating the assertion. Yet another reason is to retrieve the information about roles for a given Subject or map the assertion claims to roles for working with the RBAC to succeed, see the next section for more information.</p><p>Have a look please at this server configuration example:</p><div class="code panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl">
<pre class="brush: java; gutter: false; theme: Default"><bean id="serviceBeanClaims" class="org.apache.cxf.systest.jaxrs.security.saml.SecureClaimBookStore"/>
<bean id="samlEnvHandler" class="org.apache.cxf.rs.security.saml.SamlEnvelopedInHandler">
<property name="securityContextProvider">
@@ -489,7 +489,7 @@ public class SecureClaimBookStore {
</jaxrs:providers>
</jaxrs:server>
</pre>
-</div></div><p>An instance of org.apache.cxf.rs.security.saml.authorization.ClaimsAuthorizingFilter is used to enforce CBAC. It's a simple JAX-RS filter wrapper around ClaimsAuthorizingInterceptor. SamlEnvelopedInHandler processes and validates SAML assertions and it also relies on a simple <a shape="rect" class="external-link" href="http://svn.apache.org/repos/asf/cxf/trunk/systests/rs-security/src/test/java/org/apache/cxf/systest/jaxrs/security/saml/CustomSecurityContextProvider.java">CustomSecurityContextProvider</a> to help it to figure out what the actual Subject name is. A more involved implementation can do some additional validation as well as override few more super class methods, more on it next. The claims themselves have already been parsed and will be made available to a resulting SecurityContext which ClaimsAuthorizingFilter will rely upon.</p><h2 id="JAX-RSSAML-RoleBasedAccessControl">Role Based Access Control</h2><p>If you have an existing RBAC system (based on javax
.annotation.security.RolesAllowed or even org.springframework.security.annotation.Secured annotations) in place and have SAML assertions with claims that are known to represent roles, then making those claims work with the RBAC system can be achieved easily.</p><p>For example, given this code:</p><div class="code panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl">
+</div></div><p>An instance of org.apache.cxf.rs.security.saml.authorization.ClaimsAuthorizingFilter is used to enforce CBAC. It's a simple JAX-RS filter wrapper around ClaimsAuthorizingInterceptor. SamlEnvelopedInHandler processes and validates SAML assertions and it also relies on a simple <a shape="rect" class="external-link" href="https://github.com/apache/cxf/blob/master/systests/rs-security/src/test/java/org/apache/cxf/systest/jaxrs/security/saml/CustomSecurityContextProvider.java" rel="nofollow">CustomSecurityContextProvider</a> to help it to figure out what the actual Subject name is. A more involved implementation can do some additional validation as well as override few more super class methods, more on it next. The claims themselves have already been parsed and will be made available to a resulting SecurityContext which ClaimsAuthorizingFilter will rely upon.</p><h2 id="JAX-RSSAML-RoleBasedAccessControl">Role Based Access Control</h2><p>If you have an existing RBAC system
(based on javax.annotation.security.RolesAllowed or even org.springframework.security.annotation.Secured annotations) in place and have SAML assertions with claims that are known to represent roles, then making those claims work with the RBAC system can be achieved easily.</p><p>For example, given this code:</p><div class="code panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl">
<pre class="brush: java; gutter: false; theme: Default">import org.springframework.security.annotation.Secured;
@Path("/bookstore")