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 2022/01/28 09:42:54 UTC
svn commit: r1078234 - in /websites/production/cxf/content: cache/docs.pageCache docs/40-migration-guide.html docs/jax-rs-jose.html
Author: buildbot
Date: Fri Jan 28 09:42:54 2022
New Revision: 1078234
Log:
Production update by buildbot for cxf
Modified:
websites/production/cxf/content/cache/docs.pageCache
websites/production/cxf/content/docs/40-migration-guide.html
websites/production/cxf/content/docs/jax-rs-jose.html
Modified: websites/production/cxf/content/cache/docs.pageCache
==============================================================================
Binary files - no diff available.
Modified: websites/production/cxf/content/docs/40-migration-guide.html
==============================================================================
--- websites/production/cxf/content/docs/40-migration-guide.html (original)
+++ websites/production/cxf/content/docs/40-migration-guide.html Fri Jan 28 09:42:54 2022
@@ -98,7 +98,7 @@ Apache CXF -- 4.0 Migration Guide
<td height="100%">
<!-- Content -->
<div class="wiki-content">
-<div id="ConfluenceContent"></div>
+<div id="ConfluenceContent"><h3 id="id-4.0MigrationGuide-NewFeatures:">New Features:</h3><h3 id="id-4.0MigrationGuide-MajorDependencyChanges:">Major Dependency Changes:</h3><h3 id="id-4.0MigrationGuide-RemovedFeatures:">Removed Features:</h3><h3 id="id-4.0MigrationGuide-ImportantNotes:">Important Notes:</h3><ul><li>The default authentication scheme for the JwtAuthenticationFilter <a shape="rect" class="external-link" href="https://issues.apache.org/jira/browse/CXF-8645">has changed</a> from "JWT" to "Bearer".</li></ul></div>
</div>
<!-- Content -->
</td>
Modified: websites/production/cxf/content/docs/jax-rs-jose.html
==============================================================================
--- websites/production/cxf/content/docs/jax-rs-jose.html (original)
+++ websites/production/cxf/content/docs/jax-rs-jose.html Fri Jan 28 09:42:54 2022
@@ -111,11 +111,11 @@ Apache CXF -- JAX-RS JOSE
<!-- Content -->
<div class="wiki-content">
<div id="ConfluenceContent"><p><style type="text/css">/*<![CDATA[*/
-div.rbtoc1641921718283 {padding: 0px;}
-div.rbtoc1641921718283 ul {list-style: disc;margin-left: 0px;}
-div.rbtoc1641921718283 li {margin-left: 0px;padding-left: 0px;}
+div.rbtoc1643362969337 {padding: 0px;}
+div.rbtoc1643362969337 ul {list-style: disc;margin-left: 0px;}
+div.rbtoc1643362969337 li {margin-left: 0px;padding-left: 0px;}
-/*]]>*/</style></p><div class="toc-macro rbtoc1641921718283">
+/*]]>*/</style></p><div class="toc-macro rbtoc1643362969337">
<ul class="toc-indentation"><li><a shape="rect" href="#JAXRSJOSE-Introduction">Introduction</a></li><li><a shape="rect" href="#JAXRSJOSE-MavenDependencies">Maven Dependencies</a></li><li><a shape="rect" href="#JAXRSJOSE-JavaandJCEPolicy">Java and JCE Policy </a></li><li><a shape="rect" href="#JAXRSJOSE-JOSEOverviewandImplementation">JOSE Overview and Implementation</a>
<ul class="toc-indentation"><li><a shape="rect" href="#JAXRSJOSE-JWAAlgorithms">JWA Algorithms</a></li><li><a shape="rect" href="#JAXRSJOSE-JWKKeys">JWK Keys</a></li><li><a shape="rect" href="#JAXRSJOSE-JWSSignature">JWS Signature</a>
<ul class="toc-indentation"><li><a shape="rect" href="#JAXRSJOSE-SignatureandVerificationProviders">Signature and Verification Providers</a></li><li><a shape="rect" href="#JAXRSJOSE-JWSCompact">JWS Compact</a></li><li><a shape="rect" href="#JAXRSJOSE-JWSJSON">JWS JSON</a></li><li><a shape="rect" href="#JAXRSJOSE-JWSwithDetachedContent">JWS with Detached Content</a></li><li><a shape="rect" href="#JAXRSJOSE-JWSwithUnencodedPayload">JWS with Unencoded Payload</a></li></ul>
@@ -670,7 +670,7 @@ Payload:
"ciphertext":"alKm_g",
"tag":"DkW2pZCd7lhR0KqIGQ69-A"
}</pre>
-</div></div><p>Note the Base64Url encoded protected headers go first, followed by the 'recipients' array, with each element containing the encrypted content encryption key which can be decrypted by the recipient private key, with the array of recipients followed by the IV, ciphertext and authentication tag Base64Url sequences.</p><h2 id="JAXRSJOSE-LinkingJWTauthenticationstoJWSorJWEcontent">Linking JWT authentications to JWS or JWE content</h2><p>CXF introduced a "JWT" HTTP authentication scheme, with a Base64Url encoded JWT token representing a user authentication against an IDP capable of issuing JWT assertions (or simply JWT tokens). JWT assertion is like SAML assertion except that it is in a JSON format. If you'd like to cryptographically bind this JWT token to a data secured by JWS and/or JWE processors then simply add <a shape="rect" class="external-link" href="https://github.com/apache/cxf/blob/master/rt/rs/security/jose-parent/jose-jaxrs/src/main/java/org/apache/cxf/rs/secur
ity/jose/jaxrs/JwtAuthenticationClientFilter.java" rel="nofollow">JwtAuthenticationClientFilter</a> on the client side and <a shape="rect" class="external-link" href="https://github.com/apache/cxf/blob/master/rt/rs/security/jose-parent/jose-jaxrs/src/main/java/org/apache/cxf/rs/security/jose/jaxrs/JwtAuthenticationFilter.java" rel="nofollow">JwtAuthenticationFilter</a> on the server side. These filters link the authentication token with a randomly generated secure value which is added to both the token and the body JWS/JWE protected headers.</p><p>This approach is more effective compared to the ones where the body hash is calculated before it is submitted to a signature creation function, with the signature added as HTTP header.</p><h2 id="JAXRSJOSE-JWTauthorization">JWT authorization</h2><p>CXF supports both role and claims based authorization for JAX-RS endpoints based on information contained in a received JWT. Please see the <a shape="rect" href="jax-rs-token-authorization.html"
>JAX-RS Token Authorization</a> page for more information.</p><h2 id="JAXRSJOSE-OptionalprotectionofHTTPheaders">Optional protection of HTTP headers</h2><p>Starting from CXF 3.1.12 it is possible to use JWS, JWS JSON, JWE and JWE JSON filters to protect the selected set of HTTP headers. The JOSE payloads produced by these filters guarantee that the JOSE headers are integrity protected. Given this, if one enables a 'protectHttpHeaders' boolean property on the request filters, then, by default, HTTP Content-Type and Accept header values will be registered as JOSE header properties prefixed with "http.", example, "http.Accept":"text/plain". The list of the headers to be protected can be customized using a 'protectedHttpHeaders' set property.</p><p>These properties will be compared against the current HTTP headers on the receiving end.</p><p>This approach does not prevent the streaming of the outgoing data (which will also be protected by the filters) and offers a way to secure the HTTP
headers which are really important for the correct processing of the incoming payloads</p><h1 id="JAXRSJOSE-JOSEinJAX-RSapplicationcode">JOSE in JAX-RS application code</h1><p>In some cases you may need to create or process the JOSE data directly in the service or client application code. For example, one of the properties in the request or response payload needs to be JWS signed/verified and/or JWE encrypted/decrypted. The following 2 options can be tried.</p><h2 id="JAXRSJOSE-Option1:ProcessJOSEdirectly">Option 1:  Process JOSE directly</h2><p>This option is about using the CXF JOSE library to sign, encrypt, or/and decrypt and verify the data as <a shape="rect" href="https://cwiki.apache.org/confluence/pages/viewpage.action?pageId=85460327">documented above</a>. This option should be preferred if one needs to keep a closer control, for example, set the custom JWS or JWE headers, etc.</p><h2 id="JAXRSJOSE-Option2:UseJOSElibraryhelpersandEndpointConfiguration">Option 2: 
Use JOSE library helpers and Endpoint Configuration</h2><p>This option makes it straighforward to do JOSE in the application code. One has to extend or delegate to a specific JOSE helper instance and configure the endpoint with the location of the JOSE properties file where the JWS or JWE algorithm and key store properties are set.</p><h3 id="JAXRSJOSE-ProduceJOSEdata">Produce JOSE data</h3><p>If you need to protect some non JWT property - extend or delegate to <strong>JoseProducer</strong>:</p><div class="code panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl">
+</div></div><p>Note the Base64Url encoded protected headers go first, followed by the 'recipients' array, with each element containing the encrypted content encryption key which can be decrypted by the recipient private key, with the array of recipients followed by the IV, ciphertext and authentication tag Base64Url sequences.</p><h2 id="JAXRSJOSE-LinkingJWTauthenticationstoJWSorJWEcontent">Linking JWT authentications to JWS or JWE content</h2><p>CXF introduced a "JWT" HTTP authentication scheme, with a Base64Url encoded JWT token representing a user authentication against an IDP capable of issuing JWT assertions (or simply JWT tokens). JWT assertion is like SAML assertion except that it is in a JSON format. If you'd like to cryptographically bind this JWT token to a data secured by JWS and/or JWE processors then simply add <a shape="rect" class="external-link" href="https://github.com/apache/cxf/blob/master/rt/rs/security/jose-parent/jose-jaxrs/src/main/java/org/apache/cxf/rs/secur
ity/jose/jaxrs/JwtAuthenticationClientFilter.java" rel="nofollow">JwtAuthenticationClientFilter</a> on the client side and <a shape="rect" class="external-link" href="https://github.com/apache/cxf/blob/master/rt/rs/security/jose-parent/jose-jaxrs/src/main/java/org/apache/cxf/rs/security/jose/jaxrs/JwtAuthenticationFilter.java" rel="nofollow">JwtAuthenticationFilter</a> on the server side. These filters link the authentication token with a randomly generated secure value which is added to both the token and the body JWS/JWE protected headers.</p><p>This approach is more effective compared to the ones where the body hash is calculated before it is submitted to a signature creation function, with the signature added as HTTP header.</p><p>Note that the "JWT" scheme is not standard, and from CXF 4.0.0 the default scheme <a shape="rect" class="external-link" href="https://issues.apache.org/jira/browse/CXF-8645">has changed</a> to "Bearer".</p><h2 id="JAXRSJOSE-JWTauthorization">JWT author
ization</h2><p>CXF supports both role and claims based authorization for JAX-RS endpoints based on information contained in a received JWT. Please see the <a shape="rect" href="jax-rs-token-authorization.html">JAX-RS Token Authorization</a> page for more information.</p><h2 id="JAXRSJOSE-OptionalprotectionofHTTPheaders">Optional protection of HTTP headers</h2><p>Starting from CXF 3.1.12 it is possible to use JWS, JWS JSON, JWE and JWE JSON filters to protect the selected set of HTTP headers. The JOSE payloads produced by these filters guarantee that the JOSE headers are integrity protected. Given this, if one enables a 'protectHttpHeaders' boolean property on the request filters, then, by default, HTTP Content-Type and Accept header values will be registered as JOSE header properties prefixed with "http.", example, "http.Accept":"text/plain". The list of the headers to be protected can be customized using a 'protectedHttpHeaders' set property.</p><p>These properties will be compared
against the current HTTP headers on the receiving end.</p><p>This approach does not prevent the streaming of the outgoing data (which will also be protected by the filters) and offers a way to secure the HTTP headers which are really important for the correct processing of the incoming payloads</p><h1 id="JAXRSJOSE-JOSEinJAX-RSapplicationcode">JOSE in JAX-RS application code</h1><p>In some cases you may need to create or process the JOSE data directly in the service or client application code. For example, one of the properties in the request or response payload needs to be JWS signed/verified and/or JWE encrypted/decrypted. The following 2 options can be tried.</p><h2 id="JAXRSJOSE-Option1:ProcessJOSEdirectly">Option 1:  Process JOSE directly</h2><p>This option is about using the CXF JOSE library to sign, encrypt, or/and decrypt and verify the data as <a shape="rect" href="jax-rs-jose.html">documented above</a>. This option should be preferred if one needs to keep a closer co
ntrol, for example, set the custom JWS or JWE headers, etc.</p><h2 id="JAXRSJOSE-Option2:UseJOSElibraryhelpersandEndpointConfiguration">Option 2:  Use JOSE library helpers and Endpoint Configuration</h2><p>This option makes it straighforward to do JOSE in the application code. One has to extend or delegate to a specific JOSE helper instance and configure the endpoint with the location of the JOSE properties file where the JWS or JWE algorithm and key store properties are set.</p><h3 id="JAXRSJOSE-ProduceJOSEdata">Produce JOSE data</h3><p>If you need to protect some non JWT property - extend or delegate to <strong>JoseProducer</strong>:</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.jose.common.JoseProducer;
@Path("service")
public class SecureService extends JoseProducer {
@@ -819,7 +819,7 @@ public class SecureService extends Abstr
return jose.processJwt(data);
}
}</pre>
-</div></div><p>In both cases this composite producer-consumer will use the internal producer and/or consumer helpers which will detect the endpoint specific configuration but which can also be injected with some specific JWE and/or JWS handlers.</p><h3 id="JAXRSJOSE-Configuretheendpoint">Configure the endpoint</h3><p>These properties will contain a location of the key store, signature and/or encryption algorithm properties, etc. See the <a shape="rect" href="https://cwiki.apache.org/confluence/pages/viewpage.action?pageId=85460327">Configuration section</a> for all the available configuration options.</p><div class="code panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl">
+</div></div><p>In both cases this composite producer-consumer will use the internal producer and/or consumer helpers which will detect the endpoint specific configuration but which can also be injected with some specific JWE and/or JWS handlers.</p><h3 id="JAXRSJOSE-Configuretheendpoint">Configure the endpoint</h3><p>These properties will contain a location of the key store, signature and/or encryption algorithm properties, etc. See the <a shape="rect" href="jax-rs-jose.html">Configuration section</a> for all the available configuration options.</p><div class="code panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl">
<pre class="brush: xml; gutter: false; theme: Default"><beans xmlns="http://www.springframework.org/schema/beans" xmlns:jaxrs="http://cxf.apache.org/jaxrs">
<bean id="serviceBean" class="org.apache.cxf.systest.jaxrs.security.jose.SecureService"/>
<jaxrs:server address="/secure">