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 2014/02/12 17:48:13 UTC
svn commit: r897643 [3/8] - in /websites/production/cxf/content: ./ cache/
docs/
Modified: websites/production/cxf/content/docs/jax-rs-oauth2.html
==============================================================================
--- websites/production/cxf/content/docs/jax-rs-oauth2.html (original)
+++ websites/production/cxf/content/docs/jax-rs-oauth2.html Wed Feb 12 16:48:12 2014
@@ -118,11 +118,11 @@ Apache CXF -- JAX-RS OAuth2
<!-- Content -->
<div class="wiki-content">
<div id="ConfluenceContent"><h1 id="JAX-RSOAuth2-JAX-RS:OAuth2">JAX-RS: OAuth2</h1><p><style type="text/css">/*<![CDATA[*/
-div.rbtoc1387471155027 {padding: 0px;}
-div.rbtoc1387471155027 ul {list-style: disc;margin-left: 0px;}
-div.rbtoc1387471155027 li {margin-left: 0px;padding-left: 0px;}
+div.rbtoc1392223669688 {padding: 0px;}
+div.rbtoc1392223669688 ul {list-style: disc;margin-left: 0px;}
+div.rbtoc1392223669688 li {margin-left: 0px;padding-left: 0px;}
-/*]]>*/</style></p><div class="toc-macro rbtoc1387471155027">
+/*]]>*/</style></p><div class="toc-macro rbtoc1392223669688">
<ul class="toc-indentation"><li><a shape="rect" href="#JAX-RSOAuth2-JAX-RS:OAuth2">JAX-RS: OAuth2</a></li><li><a shape="rect" href="#JAX-RSOAuth2-Introduction">Introduction</a></li><li><a shape="rect" href="#JAX-RSOAuth2-Mavendependencies">Maven dependencies</a></li><li><a shape="rect" href="#JAX-RSOAuth2-ClientRegistration">Client Registration</a></li><li><a shape="rect" href="#JAX-RSOAuth2-DevelopingOAuth2Servers">Developing OAuth2 Servers</a>
<ul class="toc-indentation"><li><a shape="rect" href="#JAX-RSOAuth2-AuthorizationService">Authorization Service</a>
<ul class="toc-indentation"><li><a shape="rect" href="#JAX-RSOAuth2-EndUserNameinAuthorizationForm">EndUser Name in Authorization Form</a></li><li><a shape="rect" href="#JAX-RSOAuth2-PublicClients(Devices)">Public Clients (Devices)</a>
@@ -130,7 +130,9 @@ div.rbtoc1387471155027 li {margin-left:
</li></ul>
</li><li><a shape="rect" href="#JAX-RSOAuth2-AccessTokenService">AccessTokenService</a>
<ul class="toc-indentation"><li><a shape="rect" href="#JAX-RSOAuth2-AccessTokenTypes">Access Token Types</a>
-<ul class="toc-indentation"><li><a shape="rect" href="#JAX-RSOAuth2-Bearer">Bearer</a></li><li><a shape="rect" href="#JAX-RSOAuth2-MAC">MAC</a></li><li><a shape="rect" href="#JAX-RSOAuth2-CustomandEncryptedtokens">Custom and Encrypted tokens</a></li><li><a shape="rect" href="#JAX-RSOAuth2-SimpleTokensandAudience">Simple Tokens and Audience</a></li></ul>
+<ul class="toc-indentation"><li><a shape="rect" href="#JAX-RSOAuth2-Bearer">Bearer</a></li><li><a shape="rect" href="#JAX-RSOAuth2-MAC">MAC</a></li><li><a shape="rect" href="#JAX-RSOAuth2-Encryptedtokens">Encrypted tokens</a>
+<ul class="toc-indentation"><li><a shape="rect" href="#JAX-RSOAuth2-UsingSecretKeys">Using Secret Keys</a></li><li><a shape="rect" href="#JAX-RSOAuth2-UsingCertificates">Using Certificates</a></li><li><a shape="rect" href="#JAX-RSOAuth2-UsingCertificatesandSecretKeys">Using Certificates and Secret Keys</a></li></ul>
+</li><li><a shape="rect" href="#JAX-RSOAuth2-Customtokens">Custom tokens</a></li><li><a shape="rect" href="#JAX-RSOAuth2-SimpleTokensandAudience">Simple Tokens and Audience</a></li></ul>
</li><li><a shape="rect" href="#JAX-RSOAuth2-AccessTokenValidationService">AccessTokenValidationService</a></li></ul>
</li><li><a shape="rect" href="#JAX-RSOAuth2-TokenRevocationService">TokenRevocationService</a></li><li><a shape="rect" href="#JAX-RSOAuth2-SupportedGrants">Supported Grants</a>
<ul class="toc-indentation"><li><a shape="rect" href="#JAX-RSOAuth2-AuthorizationCode">Authorization Code</a></li><li><a shape="rect" href="#JAX-RSOAuth2-Implicit">Implicit</a></li><li><a shape="rect" href="#JAX-RSOAuth2-ClientCredentials">Client Credentials</a></li><li><a shape="rect" href="#JAX-RSOAuth2-ResourceOwnerPasswordCredentials">Resource Owner Password Credentials</a></li><li><a shape="rect" href="#JAX-RSOAuth2-RefreshToken">Refresh Token</a></li><li><a shape="rect" href="#JAX-RSOAuth2-Assertions">Assertions</a></li><li><a shape="rect" href="#JAX-RSOAuth2-CustomGrants">Custom Grants</a></li></ul>
@@ -140,7 +142,7 @@ div.rbtoc1387471155027 li {margin-left:
<ul class="toc-indentation"><li><a shape="rect" href="#JAX-RSOAuth2-Sharingthesameaccesspathbetweenendusersandclients">Sharing the same access path between end users and clients</a></li><li><a shape="rect" href="#JAX-RSOAuth2-Providingdifferentaccesspointstoendusersandclients">Providing different access points to end users and clients</a></li></ul>
</li><li><a shape="rect" href="#JAX-RSOAuth2-SingleSignOn">Single Sign On</a></li></ul>
</li></ul>
-</div><h1 id="JAX-RSOAuth2-Introduction">Introduction</h1><p>CXF provides the implementation of <a shape="rect" class="external-link" href="http://tools.ietf.org/html/rfc6749" rel="nofollow">OAuth 2.0</a>. See also the <a shape="rect" href="jax-rs-oauth.html">JAX-RS OAuth</a> page for information about OAuth 1.0.</p><p>Authorization Code, Implicit, Client Credentials, Resource Owner Password Credentials, Refresh Token and SAML2 Assertions grants are currently supported.</p><p>Custom grant handlers can be registered.</p><p>OAuth2 is a new protocol which offers a complex yet elegant solution toward helping end users (resource owners) authorize third-party providers to access their resources.</p><p>The OAuth2 flow which is closely related to the original OAuth 1.0 3-leg flow is called Authorization Code and involves 3 parties: the end user, the third party service (client) and the resource server which is protected by OAuth2 filters. Typically a client offers a service feature that an
end user requests and which requires the former to access one or more protected resources on behalf of this user which are located at the resource server. For example, the client may need to access the end user's photos in order to print them and post to the user or read and possibly update a user's calendar in order to make a booking.</p><p>In order to make it happen, the third-party service application/client needs to register itself with the OAuth2 server. This happens out-of-band and after the registration the client gets back a client key and secret pair. Typically the client is expected to provide the name and description of the application, the application logo URI, one or more redirect URIs, and other information that may help the OAuth2 authorization server to identify this client to the end user at the authorization time.</p><p>From then on, the authorization code flow works like this:<br clear="none"> 1. End User requests the third-party service using a browser.</p><p>2.
The client redirects the end user to OAuth2 Authorization Service, adding its client id, the state, redirect URI and the optional scope to the target URI. The state parameter represents the current end user's request, redirect URI - where the authorization code is expected to be returned to, and the scope is the list of opaque permissions that the client needs in order to access the protected resources.</p><p>3. Authorization Service will retrieve the information about the client using its client id, build an HTML form and return it to the end user. The form will ask the user if a given third-party application can be allowed to access some resources on behalf of this user.</p><p>4. If the user approves it then Authorization Service will generate an authorization code and redirect the user back to the redirect uri provided by the client, also adding a state parameter to the redirect URI.</p><p>5. The client requests an access token from OAuth2 Access Token Service by providing an aut
horization code grant.</p><p>6. After getting an access token token, the service finally proceeds with accessing the current user's resources and completes the user's request.</p><p>As you can see the flow can be complex yet it is very effective. A number of issues may need to be taken care along the way such as managing expired tokens, making sure that the OAuth2 security layer is functioning properly and is not interfering with the end user itself trying to access its own resources, etc.</p><p>Please check the <a shape="rect" class="external-link" href="http://tools.ietf.org/html/draft-ietf-oauth-v2" rel="nofollow">specification</a> and the <a shape="rect" class="external-link" href="http://en.wikipedia.org/wiki/OAuth#OAuth_2.0" rel="nofollow">Wikipedia article</a> as well as other resources available on the WEB for more information you may need to know about OAuth2.</p><p>CXF JAX-RS gives the best effort to making this process as simple as possible and requiring only a minimum ef
fort on behalf of OAuth2 server developers. It also offers the utility code for greatly simplifying the way the third-party application can interact with the OAuth2 service endpoints.</p><h1 id="JAX-RSOAuth2-Mavendependencies">Maven dependencies</h1><div class="code panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl">
+</div><h1 id="JAX-RSOAuth2-Introduction">Introduction</h1><p>New: CXF 3.0.0 makes it simpler to encrypt the token and other OAuth2 server model state; OAuthDataProvider has a new method, revokeToken, added to it to support the client-driven token revocation.</p><p> </p><p>CXF provides the implementation of <a shape="rect" class="external-link" href="http://tools.ietf.org/html/rfc6749" rel="nofollow">OAuth 2.0</a>. See also the <a shape="rect" href="jax-rs-oauth.html">JAX-RS OAuth</a> page for information about OAuth 1.0.</p><p>Authorization Code, Implicit, Client Credentials, Resource Owner Password Credentials, Refresh Token and SAML2 Assertions grants are currently supported.</p><p>Custom grant handlers can be registered.</p><p>OAuth2 is a new protocol which offers a complex yet elegant solution toward helping end users (resource owners) authorize third-party providers to access their resources.</p><p>The OAuth2 flow which is closely related to the original OAuth 1.0 3-leg fl
ow is called Authorization Code and involves 3 parties: the end user, the third party service (client) and the resource server which is protected by OAuth2 filters. Typically a client offers a service feature that an end user requests and which requires the former to access one or more protected resources on behalf of this user which are located at the resource server. For example, the client may need to access the end user's photos in order to print them and post to the user or read and possibly update a user's calendar in order to make a booking.</p><p>In order to make it happen, the third-party service application/client needs to register itself with the OAuth2 server. This happens out-of-band and after the registration the client gets back a client key and secret pair. Typically the client is expected to provide the name and description of the application, the application logo URI, one or more redirect URIs, and other information that may help the OAuth2 authorization server to
identify this client to the end user at the authorization time.</p><p>From then on, the authorization code flow works like this:<br clear="none"> 1. End User requests the third-party service using a browser.</p><p>2. The client redirects the end user to OAuth2 Authorization Service, adding its client id, the state, redirect URI and the optional scope to the target URI. The state parameter represents the current end user's request, redirect URI - where the authorization code is expected to be returned to, and the scope is the list of opaque permissions that the client needs in order to access the protected resources.</p><p>3. Authorization Service will retrieve the information about the client using its client id, build an HTML form and return it to the end user. The form will ask the user if a given third-party application can be allowed to access some resources on behalf of this user.</p><p>4. If the user approves it then Authorization Service will generate an authorization code an
d redirect the user back to the redirect uri provided by the client, also adding a state parameter to the redirect URI.</p><p>5. The client requests an access token from OAuth2 Access Token Service by providing an authorization code grant.</p><p>6. After getting an access token token, the service finally proceeds with accessing the current user's resources and completes the user's request.</p><p>As you can see the flow can be complex yet it is very effective. A number of issues may need to be taken care along the way such as managing expired tokens, making sure that the OAuth2 security layer is functioning properly and is not interfering with the end user itself trying to access its own resources, etc.</p><p>Please check the <a shape="rect" class="external-link" href="http://tools.ietf.org/html/draft-ietf-oauth-v2" rel="nofollow">specification</a> and the <a shape="rect" class="external-link" href="http://en.wikipedia.org/wiki/OAuth#OAuth_2.0" rel="nofollow">Wikipedia article</a> as
well as other resources available on the WEB for more information you may need to know about OAuth2.</p><p>CXF JAX-RS gives the best effort to making this process as simple as possible and requiring only a minimum effort on behalf of OAuth2 server developers. It also offers the utility code for greatly simplifying the way the third-party application can interact with the OAuth2 service endpoints.</p><h1 id="JAX-RSOAuth2-Mavendependencies">Maven dependencies</h1><div class="code panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl">
<script class="theme: Default; brush: xml; gutter: false" type="syntaxhighlighter"><![CDATA[<dependency>
<groupId>org.apache.cxf</groupId>
<artifactId>cxf-rt-rs-security-oauth2</artifactId>
@@ -205,7 +207,7 @@ Cookie=[JSESSIONID=1c289vha0cxfe],
<pre>GET
http://localhost:8080/services/social/authorize?client_id=mobileClient&response_type=code
</pre>
-</div></div><p>Assuming the 'mobileClient' has been registered as public one with no secret and the service has been set up to support such clients, the end user will get a chance to authorize this client the same way it can do confidential clients, and after this user gets back a code (delivered directly in the response HTML page by default) the user will enter the code securely into the device which will then replace it for a time-scoped access token by contacting AccessTokenService.</p><h4 id="JAX-RSOAuth2-SecurecodeacquisitionwithredirectURI">Secure code acquisition with redirect URI</h4><p>The following <a shape="rect" class="external-link" href="http://tools.ietf.org/html/draft-sakimura-oauth-tcse-01" rel="nofollow">extension</a> is supported to help public clients with redirect URIs to accept the code securely.<br clear="none"> Note this extension will likely introduce the HMAC calculation in the next drafts, but the current approach can already help.</p><h2 id="JAX-RSOAuth2-
AccessTokenService">AccessTokenService</h2><p>The role of AccessTokenService is to exchange a token grant for a new access token which will be used by the client to access the end user's resources. <br clear="none"> Here is an example request log:</p><div class="code panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl">
+</div></div><p>Assuming the 'mobileClient' has been registered as public one with no secret and the service has been set up to support such clients, the end user will get a chance to authorize this client the same way it can do confidential clients, and after this user gets back a code (delivered directly in the response HTML page by default) the user will enter the code securely into the device which will then replace it for a time-scoped access token by contacting AccessTokenService.</p><h4 id="JAX-RSOAuth2-SecurecodeacquisitionwithredirectURI">Secure code acquisition with redirect URI</h4><p>The following <a shape="rect" class="external-link" href="http://tools.ietf.org/html/draft-sakimura-oauth-tcse-02" rel="nofollow">extension</a> is supported to help public clients with redirect URIs to accept the code securely staring from CXF 3.0.0-milestone2.</p><p>The public (mobile) client will include a 'code_verifier' value when requesting the authorization code and it will be saved by
Authorization service, with the help of the registered AuthorizationCodeDataProvider into an instance of ServerAuthorizationCodeGrant. The client will next request a token providing the 'code' and 'code_challenge' - the latter will be compared by AuthorizationCodeGrantHandler with the original 'code_verifier'. By default, the 'code_challenge' is expected to be equal to the original 'code_verifier', but the grant handler can be registered with the custom org.apache.cxf.rs.security.oauth2.grants.code.CodeVerifierTransformer - CXF ships a DigestCodeVerifierTransformer which implements a transformation mentioned in the extension.</p><h2 id="JAX-RSOAuth2-AccessTokenService">AccessTokenService</h2><p>The role of AccessTokenService is to exchange a token grant for a new access token which will be used by the client to access the end user's resources. <br clear="none"> Here is an example request log:</p><div class="code panel pdl" style="border-width: 1px;"><div class="codeContent panelCont
ent pdl">
<script class="theme: Default; brush: xml; gutter: false" type="syntaxhighlighter"><![CDATA[Address: http://localhost:8080/services/oauth/token
Http-Method: POST
@@ -266,7 +268,7 @@ public class CustomOAuthDataProvider imp
// other methods are not shown
}
]]></script>
-</div></div><p>CustomOAuthDataProvider will also be asked by OAuthRequestFilter to validate the incoming Bearer tokens given that they typically act as database key or key alias, if no Bearer token validator is registered.</p><h4 id="JAX-RSOAuth2-MAC">MAC</h4><p>CXF 2.6.2 supports MAC tokens as specified in the latest <a shape="rect" class="external-link" href="http://tools.ietf.org/html/draft-ietf-oauth-v2-http-mac-01" rel="nofollow">MAC Access Authentication draft</a>. MAC tokens offer an option for clients to demonstrate they 'hold' the token secret issued to them by AccessTokenService.<br clear="none"> It is recommended that AccessTokenService endpoint issuing MAC tokens enforces a two-way TLS for an extra protection of the MAC token data returned to clients.</p><p>The following code fragment shows how a <a shape="rect" class="external-link" href="http://svn.apache.org/repos/asf/cxf/trunk/rt/rs/security/oauth-parent/oauth2/src/main/java/org/apache/cxf/rs/security/oauth2/tokens/m
ac/MacAccessToken.java">MacAccessToken</a> utility class can be used to create MAC tokens:</p><div class="code panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl">
+</div></div><p>CustomOAuthDataProvider will also be asked by OAuthRequestFilter to validate the incoming Bearer tokens given that they typically act as database key or key alias, if no Bearer token validator is registered.</p><h4 id="JAX-RSOAuth2-MAC">MAC</h4><p>CXF 2.6.2 supports MAC tokens as specified in the latest <a shape="rect" class="external-link" href="http://tools.ietf.org/html/draft-ietf-oauth-v2-http-mac-05" rel="nofollow">MAC Access Authentication draft</a> created by Eran Hammer and others. MAC tokens offer an option for clients to demonstrate they 'hold' the token secret issued to them by AccessTokenService.<br clear="none"> It is recommended that AccessTokenService endpoint issuing MAC tokens enforces a two-way TLS for an extra protection of the MAC token data returned to clients.</p><p>The following code fragment shows how a <a shape="rect" class="external-link" href="http://svn.apache.org/repos/asf/cxf/trunk/rt/rs/security/oauth-parent/oauth2/src/main/java/org/apac
he/cxf/rs/security/oauth2/tokens/mac/MacAccessToken.java">MacAccessToken</a> utility class can be used to create MAC tokens:</p><div class="code panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl">
<script class="theme: Default; brush: java; gutter: false" type="syntaxhighlighter"><![CDATA[import org.apache.cxf.rs.security.oauth2.common.AccessTokenRegistration;
import org.apache.cxf.rs.security.oauth2.common.ServerAccessToken;
import org.apache.cxf.rs.security.oauth2.tokens.mac.HmacAlgorithm;
@@ -328,7 +330,23 @@ Authorization: MAC id="5b5c8e677413
mac="W7bdMZbv9UWOTadASIQHagZyirA="
ts="12345678"
]]></script>
-</div></div><p>where 'ts' attribute is used to pass a timestamp value.</p><h4 id="JAX-RSOAuth2-CustomandEncryptedtokens">Custom and Encrypted tokens</h4><p>If needed, users can use their own custom token types, with the only restriction that the custom token type implementations have to extend org.apache.cxf.rs.security.oauth2.common.ServerAccessToken.</p><p>CXF implementations of Bearer and Access token types can also be extended if required. For example, typically the access token data will be persisted in the database. One possible option is to experiment with actually encrypting the state of the token within the token id itself and returning it to the client and then decrypting it when OAuthDataProvider is requested to get ServerAccessToken representation of the current token identifier.</p><p>The cost of encrypting and decrypting will add up to the processing time - however the provider will not be actually responsible for storing the access token details which can start making
a difference with a high number of clients.</p><h4 id="JAX-RSOAuth2-SimpleTokensandAudience">Simple Tokens and Audience</h4><p>Starting from CXF 2.7.7 an <a shape="rect" class="external-link" href="http://tools.ietf.org/html/draft-tschofenig-oauth-audience-00" rel="nofollow">audience</a> parameter is supported during the client token requests.</p><h3 id="JAX-RSOAuth2-AccessTokenValidationService">AccessTokenValidationService</h3><p>The <a shape="rect" class="external-link" href="http://svn.apache.org/repos/asf/cxf/trunk/rt/rs/security/oauth-parent/oauth2/src/main/java/org/apache/cxf/rs/security/oauth2/services/AccessTokenValidationService.java">AccessTokenValidationService</a> is a CXF specific OAuth2 service for accepting the remote access token validation requests. Typically, OAuthRequestFilter (see on it below) may choose to impersonate itself as a third-party client and will ask AccessTokenValidationService to return the information relevant to the current access token, before
setting up a security context. More on it below.</p><h2 id="JAX-RSOAuth2-TokenRevocationService">TokenRevocationService</h2><p><a shape="rect" class="external-link" href="http://svn.apache.org/repos/asf/cxf/trunk/rt/rs/security/oauth-parent/oauth2/src/main/java/org/apache/cxf/rs/security/oauth2/services/TokenRevocationService.java">TokenRevocationService</a> is a simple OAuth2 service supporting the clients wishing to revoke the access or refresh tokens they own themselves, please see <a shape="rect" class="external-link" href="http://tools.ietf.org/html/draft-ietf-oauth-revocation-09" rel="nofollow">OAuth2 Token Revocation Draft</a> for more information.</p><p>TokenRevocationService and AccessTokenService share the same code which enforces that the clients have been correctly authenticated.</p><p>Note, OAuthDataProvider implementations processing a revocation request should simply ignore the invalid tokens as recommended by the specification which will let TokenRevocationService re
turn HTTP 200 which is done to minimize a possible attack surface (specifically for bad clients not to see if their requests failed or succeeded) and throw the exceptions only if the token revocation feature is not currently supported.</p><h2 id="JAX-RSOAuth2-SupportedGrants">Supported Grants</h2><p>The following subsections briefly describe how the well-known grant types can be supported on the server side. Please also check the "Client Side Support" section on how to use the related <a shape="rect" class="external-link" href="http://svn.apache.org/repos/asf/cxf/trunk/rt/rs/security/oauth-parent/oauth2/src/main/java/org/apache/cxf/rs/security/oauth2/common/AccessTokenGrant.java">AccessTokenGrant</a> implementations to request the access tokens.</p><h3 id="JAX-RSOAuth2-AuthorizationCode">Authorization Code</h3><p>As described above, <a shape="rect" class="external-link" href="http://svn.apache.org/repos/asf/cxf/trunk/rt/rs/security/oauth-parent/oauth2/src/main/java/org/apache/cxf/rs
/security/oauth2/services/AuthorizationCodeGrantService.java">AuthorizationCodeGrantService</a> service and <a shape="rect" class="external-link" href="http://svn.apache.org/repos/asf/cxf/trunk/rt/rs/security/oauth-parent/oauth2/src/main/java/org/apache/cxf/rs/security/oauth2/grants/code/AuthorizationCodeDataProvider.java">AuthorizationCodeDataProvider</a> data provider can support a redirection-based Authorization Code flow.</p><p>The code that the client receives in the end of the redirection process will need to be exchanged for a new access token with AccessTokenService. CXF-based clients can use a helper <a shape="rect" class="external-link" href="http://svn.apache.org/repos/asf/cxf/trunk/rt/rs/security/oauth-parent/oauth2/src/main/java/org/apache/cxf/rs/security/oauth2/grants/code/AuthorizationCodeGrant.java">AuthorizationCodeGrant</a> bean to request a new access token with OAuthClientUtils.</p><h3 id="JAX-RSOAuth2-Implicit">Implicit</h3><p>Implicit grant is supported the sam
e way Authorization Code grant is except that the response to the client running within a web browser is formatted differently, using URI fragments.</p><p><a shape="rect" class="external-link" href="http://svn.apache.org/repos/asf/cxf/trunk/rt/rs/security/oauth-parent/oauth2/src/main/java/org/apache/cxf/rs/security/oauth2/services/ImplicitGrantService.java">ImplicitGrantService</a> service and <a shape="rect" class="external-link" href="http://svn.apache.org/repos/asf/cxf/trunk/rt/rs/security/oauth-parent/oauth2/src/main/java/org/apache/cxf/rs/security/oauth2/grants/code/AuthorizationCodeDataProvider.java">AuthorizationCodeDataProvider</a> data provider can support a redirection-based Implicit flow.</p><p>Note the only difference is the use of ImplicitGrantService instead of AuthorizationCodeGrantService.</p><p>Also note that when an Implicit grant client (running within a browser) replaces the code grant for a new access token and tries to access the end user's resource, Cross Orig
in Resource Sharing (CORS) support will most likely need to be enabled on the end user's resource server.<br clear="none"> The simplest approach is to register a CXF <a shape="rect" href="http://cxf.apache.org/docs/jax-rs-cors.html">CORS filter</a>, right before OAuth2 filter (see on it below).</p><p>Starting from CXF 2.7.5 it is possible to request ImplicitGrantService to return a registered Client id to the browser-hosted client. This is recommended so that the client can verify that the token is meant to be delivered to this client.</p><h3 id="JAX-RSOAuth2-ClientCredentials">Client Credentials</h3><p>Register <a shape="rect" class="external-link" href="http://svn.apache.org/repos/asf/cxf/trunk/rt/rs/security/oauth-parent/oauth2/src/main/java/org/apache/cxf/rs/security/oauth2/grants/clientcred/ClientCredentialsGrantHandler.java">ClientCredentialsGrantHandler</a> handler with AccessTokenService for this grant be supported.</p><p>CXF-based clients can use a helper <a shape="rect" cl
ass="external-link" href="http://svn.apache.org/repos/asf/cxf/trunk/rt/rs/security/oauth-parent/oauth2/src/main/java/org/apache/cxf/rs/security/oauth2/grants/clientcred/ClientCredentialsGrant.java">ClientCredentialsGrant</a> bean to request a new access token with OAuthClientUtils.</p><h3 id="JAX-RSOAuth2-ResourceOwnerPasswordCredentials">Resource Owner Password Credentials</h3><p>Register <a shape="rect" class="external-link" href="http://svn.apache.org/repos/asf/cxf/trunk/rt/rs/security/oauth-parent/oauth2/src/main/java/org/apache/cxf/rs/security/oauth2/grants/owner/ResourceOwnerGrantHandler.java">ResourceOwnerGrantHandler</a> handler with AccessTokenService for this grant be supported.</p><p>CXF-based clients can use a helper <a shape="rect" class="external-link" href="http://svn.apache.org/repos/asf/cxf/trunk/rt/rs/security/oauth-parent/oauth2/src/main/java/org/apache/cxf/rs/security/oauth2/grants/owner/ResourceOwnerGrant.java">ResourceOwnerGrant</a> bean to request a new access
token with OAuthClientUtils.</p><h3 id="JAX-RSOAuth2-RefreshToken">Refresh Token</h3><p>The client can issue a refresh token grant if the current access token it owns has expired or been revoked and the refresh token was issued alongside with the access token which is now invalid and get the new, 'refreshed' access token. This can allow the client to avoid seeking a new authorization approval from the end user.</p><p>Register <a shape="rect" class="external-link" href="http://svn.apache.org/repos/asf/cxf/trunk/rt/rs/security/oauth-parent/oauth2/src/main/java/org/apache/cxf/rs/security/oauth2/grants/refresh/RefreshTokenGrantHandler.java">RefreshTokenGrantHandler</a> handler with AccessTokenService for this grant be supported. Note this grant handler is only useful for refreshing the existing access token, so one or more of the other grant handlers (Authorization Code, Implicit, etc) will also have to be registered with AccessTokenService.</p><p>CXF-based clients can use a helper <a
shape="rect" class="external-link" href="http://svn.apache.org/repos/asf/cxf/trunk/rt/rs/security/oauth-parent/oauth2/src/main/java/org/apache/cxf/rs/security/oauth2/grants/refresh/RefreshTokenGrant.java">RefreshTokenGrant</a> bean to request a new access token with OAuthClientUtils.</p><h3 id="JAX-RSOAuth2-Assertions">Assertions</h3><p>SAML2 Bearer and JWT assertions can be used as token grants.</p><p>Please see <a shape="rect" href="jaxrs-oauth2-assertions.html">JAXRS OAuth2 Assertions</a> section for more information.</p><h3 id="JAX-RSOAuth2-CustomGrants">Custom Grants</h3><p>If you need to customize the way the well-known grant requests are handled then consider extending one of the grant handlers listed in the previous sub-sections.</p><p>Alternatively create a custom <a shape="rect" class="external-link" href="http://svn.apache.org/repos/asf/cxf/trunk/rt/rs/security/oauth-parent/oauth2/src/main/java/org/apache/cxf/rs/security/oauth2/provider/AccessTokenGrantHandler.java">Acces
sTokenGrantHandler</a> and register it with AccessTokenService. Additionally, consider providing a related <a shape="rect" class="external-link" href="http://svn.apache.org/repos/asf/cxf/trunk/rt/rs/security/oauth-parent/oauth2/src/main/java/org/apache/cxf/rs/security/oauth2/common/AccessTokenGrant.java">AccessTokenGrant</a> implementation for making it easy for the client code to request a new access token with this custom grant.</p><h2 id="JAX-RSOAuth2-PreAuthorizedaccesstokens">PreAuthorized access tokens</h2><p>When working with the flows which require the end users/resource owners explicitly authorizing clients (for example, as in the case of redirection-based flows), using pre-authorized access tokens is one option to minimize the need for the end-user intervention. <br clear="none"> OAuthDataProvider is always checked first if the pre-authorized access token for a given Client exists and if yes then it will be returned immediately, without starting the authorization process i
nvolving the end user (as required by some flows).</p><p>Consider providing a user interface which will let the end users/resource owners to pre-authorize specific clients early. Note, a CXF service for supporting the users pre-authorizing the clients or revoking the tokens for some of the clients may be introduced in the future.</p><p>Also note that using a refresh token grant may further help with minimizing the end user involvement, in cases when the current access token has expired.</p><h2 id="JAX-RSOAuth2-Pre-registeredscopes">Pre-registered scopes</h2><p>Clients can register custom scopes they will be expected to use and then avoid specifying the scopes when requesting the code grants or access tokens.<br clear="none"> Alternatively it makes it easier to support so called wild-card scopes. For example, a client pre-registers a scope "update" and actually uses an "update-7" scope: Redirection-based services and access token grants can be configured to do a partial scope match,
in this case, validate that "update-7" starts from "update"</p><h2 id="JAX-RSOAuth2-WritingOAuthDataProvider">Writing OAuthDataProvider</h2><p>Using CXF OAuth service implementations will help a lot with setting up an OAuth server. As you can see from the above sections, these services rely on a custom <a shape="rect" class="external-link" href="http://svn.apache.org/repos/asf/cxf/trunk/rt/rs/security/oauth-parent/oauth2/src/main/java/org/apache/cxf/rs/security/oauth2/provider/OAuthDataProvider.java">OAuthDataProvider</a> implementation.</p><p>The main task of OAuthDataProvider is to persist and generate access tokens. Additionally, as noted above, AuthorizationCodeDataProvider needs to persist and remove the code grant registrations. The way it's done is really application-specific. Consider starting with a basic memory based implementation and then move on to keeping the data in some DB.</p><p>Note that OAuthDataProvider supports retrieving <a shape="rect" class="external-link" hr
ef="http://svn.apache.org/repos/asf/cxf/trunk/rt/rs/security/oauth-parent/oauth2/src/main/java/org/apache/cxf/rs/security/oauth2/common/Client.java">Client</a> instances but it has no methods for creating or removing Clients. The reason for it is that the process of registering third-party clients is very specific to a particular OAuth2 application, so CXF does not offer a registration support service and hence OAuthDataProvider has no Client create/update methods. You will likely need to do something like this:</p><div class="code panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl">
+</div></div><p>where 'ts' attribute is used to pass a timestamp value.</p><h4 id="JAX-RSOAuth2-Encryptedtokens">Encrypted tokens</h4><p>Typically, the tokens are persisted in the storage. The alternative approach is to completely encrypt the token state and return the encrypted representation back to a client: the processing time to do with the encryption and decryption might increase but the server wins on avoiding the DB / storage lookups.    </p><p>CXF 3.0.0-milestone2 introduces the utility support for encrypting the state of BearerAccessToken and RefreshToken.</p><p>The tokens can be encrypted and decrypted with symmetric (secret) keys or certificates (public and private keys) and the combination of certificates and secret keys.</p><p><a shape="rect" class="external-link" href="http://svn.apache.org/repos/asf/cxf/trunk/rt/rs/security/oauth-parent/oauth2/src/main/java/org/apache/cxf/rs/security/oauth2/utils/ModelEncryptionSupport.java">ModelEncryptionSupport</a> c
an be used to encrypt the tokens using the custom serialization format. <a shape="rect" class="external-link" href="http://svn.apache.org/repos/asf/cxf/trunk/rt/rs/security/oauth-parent/oauth2/src/main/java/org/apache/cxf/rs/security/oauth2/utils/EncryptionUtils.java">EncryptionUtils</a> can be used directly if the alternative serialization format is preferred.  </p><p>Note that ServerAuthorizationGrant and Client can also be encrypted.</p><h5 id="JAX-RSOAuth2-UsingSecretKeys">Using Secret Keys</h5><p>The simplest strategy is to encrypt and decrypt the tokens with the symmetric/secret keys. Every new token can be encrypted with a unique secret key or all of them can be encrypted with a single secret key. The utilities provide few methods for creating secret keys with the default and advanced properties, in addition there are many examples around on how to create the keys with the specific properties.</p><p>For example, see <a shape="rect" class="external-link" href="http://svn.
apache.org/repos/asf/cxf/trunk/rt/rs/security/oauth-parent/oauth2/src/test/java/org/apache/cxf/rs/security/oauth2/utils/EncryptingDataProvider.java">EncryptingDataProvider</a>:</p><p> </p><div class="code panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl">
+<script class="theme: Default; brush: java; gutter: false" type="syntaxhighlighter"><![CDATA[SecretKey key = EncryptionUtils.getSecretKey();
+
+// create a new token, encrypt its state and return
+
+ServerAccessToken token = new BearerAccessToken(client, 3600L);
+
+String encryptedToken = ModelEncryptionSupport.encryptAccessToken(token, key);
+
+token.setTokenKey(encryptedToken);
+
+return token;
+
+// decrypt a token given a token key
+
+ModelEncryptionSupport.decryptAccessToken(this, encryptedToken, key);]]></script>
+</div></div><pre> </pre><h5 id="JAX-RSOAuth2-UsingCertificates">Using Certificates</h5><p>Working with the certificates to encrypt the state is similar to working with the symmetric keys. Please check the code examples in <a shape="rect" class="external-link" href="http://svn.apache.org/repos/asf/cxf/trunk/rt/rs/security/oauth-parent/oauth2/src/test/java/org/apache/cxf/rs/security/oauth2/utils/EncryptionUtilsTest.java">EncryptionsUtilsTest</a>.</p><p>One needs to load a Certificate, use its public key to encrypt and the private key to decrypt. using the certificate to encrypt the whole serialized token representation might be marginally slower compared to using the symmetric keys, however given that the sequence is about 300+ characters maximum the performance can be reasonable.</p><h5 id="JAX-RSOAuth2-UsingCertificatesandSecretKeys">Using Certificates and Secret Keys</h5><p>The other approach is to generate a secret key, use this key to encrypt the token and then use the certi
ficate to encrypt the key. The encrypted token and the actual encrypted secret key can be returned to the client as a token parameter, for example, as a 'key' parameter. This 'key' parameter will need to be returned to the OAuth2 server, via the HTTP header or the custom authorization scheme. The data providers using this mechanism will need to implement AccessTokenValidator and decrypt the encrypted key with the private certificate key, and decrypt the token with the decrypted secret key. Please check the code example in <a shape="rect" class="external-link" href="http://svn.apache.org/repos/asf/cxf/trunk/rt/rs/security/oauth-parent/oauth2/src/test/java/org/apache/cxf/rs/security/oauth2/utils/EncryptionUtilsTest.java">EncryptionsUtilsTest</a>.</p><p> </p><h4 id="JAX-RSOAuth2-Customtokens">Custom tokens</h4><p>If needed, users can use their own custom token types, with the only restriction that the custom token type implementations have to extend org.apache.cxf.rs.security.oaut
h2.common.ServerAccessToken.</p><h4 id="JAX-RSOAuth2-SimpleTokensandAudience">Simple Tokens and Audience</h4><p>Starting from CXF 2.7.7 an <a shape="rect" class="external-link" href="http://tools.ietf.org/html/draft-tschofenig-oauth-audience-00" rel="nofollow">audience</a> parameter is supported during the client token requests.</p><h3 id="JAX-RSOAuth2-AccessTokenValidationService">AccessTokenValidationService</h3><p>The <a shape="rect" class="external-link" href="http://svn.apache.org/repos/asf/cxf/trunk/rt/rs/security/oauth-parent/oauth2/src/main/java/org/apache/cxf/rs/security/oauth2/services/AccessTokenValidationService.java">AccessTokenValidationService</a> is a CXF specific OAuth2 service for accepting the remote access token validation requests. Typically, OAuthRequestFilter (see on it below) may choose to impersonate itself as a third-party client and will ask AccessTokenValidationService to return the information relevant to the current access token, before setting up a sec
urity context. More on it below.</p><h2 id="JAX-RSOAuth2-TokenRevocationService">TokenRevocationService</h2><p><a shape="rect" class="external-link" href="http://svn.apache.org/repos/asf/cxf/trunk/rt/rs/security/oauth-parent/oauth2/src/main/java/org/apache/cxf/rs/security/oauth2/services/TokenRevocationService.java">TokenRevocationService</a> is a simple OAuth2 service supporting the clients wishing to revoke the access or refresh tokens they own themselves, please see <a shape="rect" class="external-link" href="http://tools.ietf.org/html/draft-ietf-oauth-revocation-09" rel="nofollow">OAuth2 Token Revocation Draft</a> for more information.</p><p>TokenRevocationService and AccessTokenService share the same code which enforces that the clients have been correctly authenticated.</p><p>Note, OAuthDataProvider implementations processing a revocation request should simply ignore the invalid tokens as recommended by the specification which will let TokenRevocationService return HTTP 200 wh
ich is done to minimize a possible attack surface (specifically for bad clients not to see if their requests failed or succeeded) and throw the exceptions only if the token revocation feature is not currently supported.</p><h2 id="JAX-RSOAuth2-SupportedGrants">Supported Grants</h2><p>The following subsections briefly describe how the well-known grant types can be supported on the server side. Please also check the "Client Side Support" section on how to use the related <a shape="rect" class="external-link" href="http://svn.apache.org/repos/asf/cxf/trunk/rt/rs/security/oauth-parent/oauth2/src/main/java/org/apache/cxf/rs/security/oauth2/common/AccessTokenGrant.java">AccessTokenGrant</a> implementations to request the access tokens.</p><h3 id="JAX-RSOAuth2-AuthorizationCode">Authorization Code</h3><p>As described above, <a shape="rect" class="external-link" href="http://svn.apache.org/repos/asf/cxf/trunk/rt/rs/security/oauth-parent/oauth2/src/main/java/org/apache/cxf/rs/security/oauth2
/services/AuthorizationCodeGrantService.java">AuthorizationCodeGrantService</a> service and <a shape="rect" class="external-link" href="http://svn.apache.org/repos/asf/cxf/trunk/rt/rs/security/oauth-parent/oauth2/src/main/java/org/apache/cxf/rs/security/oauth2/grants/code/AuthorizationCodeDataProvider.java">AuthorizationCodeDataProvider</a> data provider can support a redirection-based Authorization Code flow.</p><p>The code that the client receives in the end of the redirection process will need to be exchanged for a new access token with AccessTokenService. CXF-based clients can use a helper <a shape="rect" class="external-link" href="http://svn.apache.org/repos/asf/cxf/trunk/rt/rs/security/oauth-parent/oauth2/src/main/java/org/apache/cxf/rs/security/oauth2/grants/code/AuthorizationCodeGrant.java">AuthorizationCodeGrant</a> bean to request a new access token with OAuthClientUtils.</p><h3 id="JAX-RSOAuth2-Implicit">Implicit</h3><p>Implicit grant is supported the same way Authorizat
ion Code grant is except that the response to the client running within a web browser is formatted differently, using URI fragments.</p><p><a shape="rect" class="external-link" href="http://svn.apache.org/repos/asf/cxf/trunk/rt/rs/security/oauth-parent/oauth2/src/main/java/org/apache/cxf/rs/security/oauth2/services/ImplicitGrantService.java">ImplicitGrantService</a> service and <a shape="rect" class="external-link" href="http://svn.apache.org/repos/asf/cxf/trunk/rt/rs/security/oauth-parent/oauth2/src/main/java/org/apache/cxf/rs/security/oauth2/grants/code/AuthorizationCodeDataProvider.java">AuthorizationCodeDataProvider</a> data provider can support a redirection-based Implicit flow.</p><p>Note the only difference is the use of ImplicitGrantService instead of AuthorizationCodeGrantService.</p><p>Also note that when an Implicit grant client (running within a browser) replaces the code grant for a new access token and tries to access the end user's resource, Cross Origin Resource Shar
ing (CORS) support will most likely need to be enabled on the end user's resource server.<br clear="none"> The simplest approach is to register a CXF <a shape="rect" href="http://cxf.apache.org/docs/jax-rs-cors.html">CORS filter</a>, right before OAuth2 filter (see on it below).</p><p>Starting from CXF 2.7.5 it is possible to request ImplicitGrantService to return a registered Client id to the browser-hosted client. This is recommended so that the client can verify that the token is meant to be delivered to this client.</p><h3 id="JAX-RSOAuth2-ClientCredentials">Client Credentials</h3><p>Register <a shape="rect" class="external-link" href="http://svn.apache.org/repos/asf/cxf/trunk/rt/rs/security/oauth-parent/oauth2/src/main/java/org/apache/cxf/rs/security/oauth2/grants/clientcred/ClientCredentialsGrantHandler.java">ClientCredentialsGrantHandler</a> handler with AccessTokenService for this grant be supported.</p><p>CXF-based clients can use a helper <a shape="rect" class="external-li
nk" href="http://svn.apache.org/repos/asf/cxf/trunk/rt/rs/security/oauth-parent/oauth2/src/main/java/org/apache/cxf/rs/security/oauth2/grants/clientcred/ClientCredentialsGrant.java">ClientCredentialsGrant</a> bean to request a new access token with OAuthClientUtils.</p><h3 id="JAX-RSOAuth2-ResourceOwnerPasswordCredentials">Resource Owner Password Credentials</h3><p>Register <a shape="rect" class="external-link" href="http://svn.apache.org/repos/asf/cxf/trunk/rt/rs/security/oauth-parent/oauth2/src/main/java/org/apache/cxf/rs/security/oauth2/grants/owner/ResourceOwnerGrantHandler.java">ResourceOwnerGrantHandler</a> handler with AccessTokenService for this grant be supported.</p><p>CXF-based clients can use a helper <a shape="rect" class="external-link" href="http://svn.apache.org/repos/asf/cxf/trunk/rt/rs/security/oauth-parent/oauth2/src/main/java/org/apache/cxf/rs/security/oauth2/grants/owner/ResourceOwnerGrant.java">ResourceOwnerGrant</a> bean to request a new access token with OAut
hClientUtils.</p><h3 id="JAX-RSOAuth2-RefreshToken">Refresh Token</h3><p>The client can issue a refresh token grant if the current access token it owns has expired or been revoked and the refresh token was issued alongside with the access token which is now invalid and get the new, 'refreshed' access token. This can allow the client to avoid seeking a new authorization approval from the end user.</p><p>Register <a shape="rect" class="external-link" href="http://svn.apache.org/repos/asf/cxf/trunk/rt/rs/security/oauth-parent/oauth2/src/main/java/org/apache/cxf/rs/security/oauth2/grants/refresh/RefreshTokenGrantHandler.java">RefreshTokenGrantHandler</a> handler with AccessTokenService for this grant be supported. Note this grant handler is only useful for refreshing the existing access token, so one or more of the other grant handlers (Authorization Code, Implicit, etc) will also have to be registered with AccessTokenService.</p><p>CXF-based clients can use a helper <a shape="rect" cla
ss="external-link" href="http://svn.apache.org/repos/asf/cxf/trunk/rt/rs/security/oauth-parent/oauth2/src/main/java/org/apache/cxf/rs/security/oauth2/grants/refresh/RefreshTokenGrant.java">RefreshTokenGrant</a> bean to request a new access token with OAuthClientUtils.</p><h3 id="JAX-RSOAuth2-Assertions">Assertions</h3><p>SAML2 Bearer and JWT assertions can be used as token grants.</p><p>Please see <a shape="rect" href="jaxrs-oauth2-assertions.html">JAXRS OAuth2 Assertions</a> section for more information.</p><h3 id="JAX-RSOAuth2-CustomGrants">Custom Grants</h3><p>If you need to customize the way the well-known grant requests are handled then consider extending one of the grant handlers listed in the previous sub-sections.</p><p>Alternatively create a custom <a shape="rect" class="external-link" href="http://svn.apache.org/repos/asf/cxf/trunk/rt/rs/security/oauth-parent/oauth2/src/main/java/org/apache/cxf/rs/security/oauth2/provider/AccessTokenGrantHandler.java">AccessTokenGrantHandl
er</a> and register it with AccessTokenService. Additionally, consider providing a related <a shape="rect" class="external-link" href="http://svn.apache.org/repos/asf/cxf/trunk/rt/rs/security/oauth-parent/oauth2/src/main/java/org/apache/cxf/rs/security/oauth2/common/AccessTokenGrant.java">AccessTokenGrant</a> implementation for making it easy for the client code to request a new access token with this custom grant.</p><h2 id="JAX-RSOAuth2-PreAuthorizedaccesstokens">PreAuthorized access tokens</h2><p>When working with the flows which require the end users/resource owners explicitly authorizing clients (for example, as in the case of redirection-based flows), using pre-authorized access tokens is one option to minimize the need for the end-user intervention. <br clear="none"> OAuthDataProvider is always checked first if the pre-authorized access token for a given Client exists and if yes then it will be returned immediately, without starting the authorization process involving the end
user (as required by some flows).</p><p>Consider providing a user interface which will let the end users/resource owners to pre-authorize specific clients early. Note, a CXF service for supporting the users pre-authorizing the clients or revoking the tokens for some of the clients may be introduced in the future.</p><p>Also note that using a refresh token grant may further help with minimizing the end user involvement, in cases when the current access token has expired.</p><h2 id="JAX-RSOAuth2-Pre-registeredscopes">Pre-registered scopes</h2><p>Clients can register custom scopes they will be expected to use and then avoid specifying the scopes when requesting the code grants or access tokens.<br clear="none"> Alternatively it makes it easier to support so called wild-card scopes. For example, a client pre-registers a scope "update" and actually uses an "update-7" scope: Redirection-based services and access token grants can be configured to do a partial scope match, in this case, va
lidate that "update-7" starts from "update"</p><h2 id="JAX-RSOAuth2-WritingOAuthDataProvider">Writing OAuthDataProvider</h2><p>Using CXF OAuth service implementations will help a lot with setting up an OAuth server. As you can see from the above sections, these services rely on a custom <a shape="rect" class="external-link" href="http://svn.apache.org/repos/asf/cxf/trunk/rt/rs/security/oauth-parent/oauth2/src/main/java/org/apache/cxf/rs/security/oauth2/provider/OAuthDataProvider.java">OAuthDataProvider</a> implementation.</p><p>The main task of OAuthDataProvider is to persist and generate access tokens. Additionally, as noted above, AuthorizationCodeDataProvider needs to persist and remove the code grant registrations. The way it's done is really application-specific. Consider starting with a basic memory based implementation and then move on to keeping the data in some DB.</p><p>Note that OAuthDataProvider supports retrieving <a shape="rect" class="external-link" href="http://svn.a
pache.org/repos/asf/cxf/trunk/rt/rs/security/oauth-parent/oauth2/src/main/java/org/apache/cxf/rs/security/oauth2/common/Client.java">Client</a> instances but it has no methods for creating or removing Clients. The reason for it is that the process of registering third-party clients is very specific to a particular OAuth2 application, so CXF does not offer a registration support service and hence OAuthDataProvider has no Client create/update methods. You will likely need to do something like this:</p><div class="code panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl">
<script class="theme: Default; brush: java; gutter: false" type="syntaxhighlighter"><![CDATA[public class CustomOAuthProvider implements OAuthDataProvider {
public Client registerClient(String applicationName, String applicationURI, ...) {}
public void removeClient(String cliendId) {}
Modified: websites/production/cxf/content/docs/jax-rs-xml-security.html
==============================================================================
--- websites/production/cxf/content/docs/jax-rs-xml-security.html (original)
+++ websites/production/cxf/content/docs/jax-rs-xml-security.html Wed Feb 12 16:48:12 2014
@@ -118,53 +118,26 @@ Apache CXF -- JAX-RS XML Security
<td height="100%">
<!-- Content -->
<div class="wiki-content">
-<div id="ConfluenceContent"><p><span style="font-size:2em;font-weight:bold"> JAX-RS: XML Security </span></p><p></p>
+<div id="ConfluenceContent"><span style="font-size:2em;font-weight:bold"> JAX-RS: XML Security </span><p> </p><p><style type="text/css">/*<![CDATA[*/
+div.rbtoc1392223669335 {padding: 0px;}
+div.rbtoc1392223669335 ul {list-style: disc;margin-left: 0px;}
+div.rbtoc1392223669335 li {margin-left: 0px;padding-left: 0px;}
-
-<style type="text/css">/*<![CDATA[*/
-div.rbtoc1387471152188 {padding: 0px;}
-div.rbtoc1387471152188 ul {list-style: disc;margin-left: 0px;}
-div.rbtoc1387471152188 li {margin-left: 0px;padding-left: 0px;}
-
-/*]]>*/</style><div class="toc-macro rbtoc1387471152188">
+/*]]>*/</style></p><div class="toc-macro rbtoc1392223669335">
<ul class="toc-indentation"><li><a shape="rect" href="#JAX-RSXMLSecurity-Introduction">Introduction</a></li><li><a shape="rect" href="#JAX-RSXMLSecurity-Mavendependencies">Maven dependencies</a></li><li><a shape="rect" href="#JAX-RSXMLSecurity-XMLSignature">XML Signature</a>
-<ul class="toc-indentation"><li><a shape="rect" href="#JAX-RSXMLSecurity-Envelopedsignatures">Enveloped signatures</a></li><li><a shape="rect" href="#JAX-RSXMLSecurity-Envelopingsignatures">Enveloping signatures</a></li><li><a shape="rect" href="#JAX-RSXMLSecurity-Detachedsignatures">Detached signatures</a></li><li><a shape="rect" href="#JAX-RSXMLSecurity-Customizingthesignature">Customizing the signature</a></li></ul>
+<ul class="toc-indentation"><li><a shape="rect" href="#JAX-RSXMLSecurity-Envelopedsignatures">Enveloped signatures</a></li><li><a shape="rect" href="#JAX-RSXMLSecurity-Envelopingsignatures">Enveloping signatures</a></li><li><a shape="rect" href="#JAX-RSXMLSecurity-Detachedsignatures">Detached signatures</a></li><li><a shape="rect" href="#JAX-RSXMLSecurity-Customizingthesignature">Customizing the signature</a></li><li><a shape="rect" href="#JAX-RSXMLSecurity-SignatureKeyInfoValidation">Signature Key Info Validation</a></li></ul>
</li><li><a shape="rect" href="#JAX-RSXMLSecurity-XMLEncryption">XML Encryption</a>
<ul class="toc-indentation"><li><a shape="rect" href="#JAX-RSXMLSecurity-Usingtherequestsignaturecertificatesfortheencryption">Using the request signature certificates for the encryption</a></li><li><a shape="rect" href="#JAX-RSXMLSecurity-Customizingtheencryption">Customizing the encryption</a></li><li><a shape="rect" href="#JAX-RSXMLSecurity-GCMAlgorithmandBouncyCastleprovider">GCM Algorithm and BouncyCastle provider</a></li></ul>
</li><li><a shape="rect" href="#JAX-RSXMLSecurity-Restrictingencryptionandsignaturealgorithms">Restricting encryption and signature algorithms</a></li><li><a shape="rect" href="#JAX-RSXMLSecurity-Interoperability">Interoperability</a></li></ul>
-</div>
-
-<h1 id="JAX-RSXMLSecurity-Introduction">Introduction</h1>
-
-<p>CXF 2.5.0 introduces an initial support for securing JAX-RS clients and endpoints with <a shape="rect" class="external-link" href="http://www.w3.org/TR/xmldsig-core/" rel="nofollow">XML Signature</a> and <a shape="rect" class="external-link" href="http://www.w3.org/TR/xmlenc-core/" rel="nofollow">XML Encryption</a>. <br clear="none">
-This is a work in progress and the enhancements will be applied regularly. Support for the alternative signature and encryption technologies will also be provided in due time.</p>
-
-<h1 id="JAX-RSXMLSecurity-Mavendependencies">Maven dependencies</h1>
-
-<div class="code panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl">
-<script class="theme: Default; brush: xml; gutter: false" type="syntaxhighlighter"><![CDATA[
-<dependency>
+</div><h1 id="JAX-RSXMLSecurity-Introduction">Introduction</h1><p>CXF 2.5.0 introduces an initial support for securing JAX-RS clients and endpoints with <a shape="rect" class="external-link" href="http://www.w3.org/TR/xmldsig-core/" rel="nofollow">XML Signature</a> and <a shape="rect" class="external-link" href="http://www.w3.org/TR/xmlenc-core/" rel="nofollow">XML Encryption</a>. <br clear="none"> This is a work in progress and the enhancements will be applied regularly. Support for the alternative signature and encryption technologies will also be provided in due time.</p><h1 id="JAX-RSXMLSecurity-Mavendependencies">Maven dependencies</h1><div class="code panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl">
+<script class="theme: Default; brush: xml; gutter: false" type="syntaxhighlighter"><![CDATA[<dependency>
<groupId>org.apache.cxf</groupId>
<artifactId>cxf-rt-rs-security-xml</artifactId>
<version>2.5.2</version>
</dependency>
]]></script>
-</div></div>
-
-<h1 id="JAX-RSXMLSecurity-XMLSignature">XML Signature</h1>
-
-<p><a shape="rect" class="external-link" href="http://www.w3.org/TR/xmldsig-core/" rel="nofollow">XML Signature</a> defines 3 types of signatures: enveloped, enveloping and detached. All the three types are supported by CXF JAX-RS.</p>
-
-<p><strong>New</strong> Starting from CXF 2.5.2 it is also possible to add XML Signatures on the server side and get them validated on the client side.</p>
-
-
-<h2 id="JAX-RSXMLSecurity-Envelopedsignatures">Enveloped signatures</h2>
-
-<p>Payload:</p>
-
-<div class="code panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl">
-<script class="theme: Default; brush: xml; gutter: false" type="syntaxhighlighter"><![CDATA[
-<Book ID="4bd59819-7b78-47a5-bb61-cc08348e9d48">
+</div></div><h1 id="JAX-RSXMLSecurity-XMLSignature">XML Signature</h1><p><a shape="rect" class="external-link" href="http://www.w3.org/TR/xmldsig-core/" rel="nofollow">XML Signature</a> defines 3 types of signatures: enveloped, enveloping and detached. All the three types are supported by CXF JAX-RS.</p><p><strong>New</strong> Starting from CXF 2.5.2 it is also possible to add XML Signatures on the server side and get them validated on the client side.</p><h2 id="JAX-RSXMLSecurity-Envelopedsignatures">Enveloped signatures</h2><p>Payload:</p><div class="code panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl">
+<script class="theme: Default; brush: xml; gutter: false" type="syntaxhighlighter"><![CDATA[<Book ID="4bd59819-7b78-47a5-bb61-cc08348e9d48">
<id>126</id>
<name>CXF</name>
@@ -198,16 +171,8 @@ This is a work in progress and the enhan
</Book>
]]></script>
-</div></div>
-
-<p>Note that the Book root element is signed including its name and id children, and a signature ds:Reference links to Book. </p>
-
-<p>Server Configuration fragment:</p>
-
-<div class="code panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl">
-<script class="theme: Default; brush: xml; gutter: false" type="syntaxhighlighter"><![CDATA[
-
-<bean id="serviceBean" class="org.apache.cxf.systest.jaxrs.security.BookStore"/>
+</div></div><p>Note that the Book root element is signed including its name and id children, and a signature ds:Reference links to Book.</p><p>Server Configuration fragment:</p><div class="code panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl">
+<script class="theme: Default; brush: xml; gutter: false" type="syntaxhighlighter"><![CDATA[<bean id="serviceBean" class="org.apache.cxf.systest.jaxrs.security.BookStore"/>
<bean id="xmlSigHandler" class="org.apache.cxf.rs.security.xml.XmlSigInHandler"/>
<bean id="xmlSigOutHandler" class="org.apache.cxf.rs.security.xml.XmlSigOutInterceptor"/>
@@ -238,18 +203,8 @@ This is a work in progress and the enhan
</jaxrs:server>
]]></script>
-</div></div>
-
-<p>Note that org.apache.cxf.rs.security.xml.XmlSigInHandler is responsible for validating the signature attached to the inbound payload and is capable of processing all 3 types of XML Signature. </p>
-
-<p>org.apache.cxf.rs.security.xml.XmlSigOutInterceptor is responsible for adding a new signature to the outbound payload. </p>
-
-
-<p>Client code:</p>
-<div class="code panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl">
-<script class="theme: Default; brush: java; gutter: false" type="syntaxhighlighter"><![CDATA[
-
-String address = "https://localhost:8080/xmlsig/bookstore/books";
+</div></div><p>Note that org.apache.cxf.rs.security.xml.XmlSigInHandler is responsible for validating the signature attached to the inbound payload and is capable of processing all 3 types of XML Signature.</p><p>org.apache.cxf.rs.security.xml.XmlSigOutInterceptor is responsible for adding a new signature to the outbound payload.</p><p>Client code:</p><div class="code panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl">
+<script class="theme: Default; brush: java; gutter: false" type="syntaxhighlighter"><![CDATA[String address = "https://localhost:8080/xmlsig/bookstore/books";
JAXRSClientFactoryBean bean = new JAXRSClientFactoryBean();
bean.setAddress(address);
@@ -280,18 +235,8 @@ bean.setBus(bus);
WebClient wc = bean.createWebClient();
Book book = wc.post(new Book("CXF", 126L), Book.class);
]]></script>
-</div></div>
-
-<p>Spring configuration can also be used.<br clear="none">
-Please also check <a shape="rect" href="secure-jax-rs-services.html">Secure JAX-RS Services</a> on how HTTPS can be configured from Spring.</p>
-
-<h2 id="JAX-RSXMLSecurity-Envelopingsignatures">Enveloping signatures</h2>
-
-<p>Payload:</p>
-
-<div class="code panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl">
-<script class="theme: Default; brush: xml; gutter: false" type="syntaxhighlighter"><![CDATA[
-<ds:Signature xmlns:ds="http://www.w3.org/2000/09/xmldsig#">
+</div></div><p>Spring configuration can also be used.<br clear="none"> Please also check <a shape="rect" href="secure-jax-rs-services.html">Secure JAX-RS Services</a> on how HTTPS can be configured from Spring.</p><h2 id="JAX-RSXMLSecurity-Envelopingsignatures">Enveloping signatures</h2><p>Payload:</p><div class="code panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl">
+<script class="theme: Default; brush: xml; gutter: false" type="syntaxhighlighter"><![CDATA[<ds:Signature xmlns:ds="http://www.w3.org/2000/09/xmldsig#">
<ds:SignedInfo>
<ds:CanonicalizationMethod Algorithm="http://www.w3.org/TR/2001/REC-xml-c14n-20010315"/>
<ds:SignatureMethod Algorithm="http://www.w3.org/2000/09/xmldsig#rsa-sha1"/>
@@ -322,30 +267,14 @@ Please also check <a shape="rect" href="
</ds:Object>
</ds:Signature>
]]></script>
-</div></div>
-
-<p>This time the signature is enveloping the Book element using a ds:Object wrapper which ds:Reference links to.</p>
-
-<p>Server Configuration fragment is identical to the one shown in the Enveloped signatures section.</p>
-
-<p>Client code is nearly identical to the one shown in the Enveloped signatures section except that XmlSigOutInterceptor need to have an additional property set:</p>
-<div class="code panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl">
-<script class="theme: Default; brush: java; gutter: false" type="syntaxhighlighter"><![CDATA[
-
-// add the interceptor dealing with adding a signature
+</div></div><p>This time the signature is enveloping the Book element using a ds:Object wrapper which ds:Reference links to.</p><p>Server Configuration fragment is identical to the one shown in the Enveloped signatures section.</p><p>Client code is nearly identical to the one shown in the Enveloped signatures section except that XmlSigOutInterceptor need to have an additional property set:</p><div class="code panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl">
+<script class="theme: Default; brush: java; gutter: false" type="syntaxhighlighter"><![CDATA[// add the interceptor dealing with adding a signature
XmlSigOutInterceptor sigInterceptor = new XmlSigOutInterceptor();
sigInterceptor.setStyle("enveloping");
]]></script>
-</div></div>
-
-<h2 id="JAX-RSXMLSecurity-Detachedsignatures">Detached signatures</h2>
-
-<p>Payload:</p>
-
-<div class="code panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl">
-<script class="theme: Default; brush: xml; gutter: false" type="syntaxhighlighter"><![CDATA[
-<env:Envelope xmlns:env="http://org.apache.cxf/rs/env">
+</div></div><h2 id="JAX-RSXMLSecurity-Detachedsignatures">Detached signatures</h2><p>Payload:</p><div class="code panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl">
+<script class="theme: Default; brush: xml; gutter: false" type="syntaxhighlighter"><![CDATA[<env:Envelope xmlns:env="http://org.apache.cxf/rs/env">
<Book ID="e9836bc2-cb5a-453f-b967-a9ddbaf9a6de">
<id>125</id>
@@ -391,43 +320,14 @@ sigInterceptor.setStyle("enveloping
</saml2:Assertion>
</env:Envelope>
]]></script>
-</div></div>
-
-<p>Note that the whole payload is enveloped by a configurable element wrapper. The Book instance is one part of the envelope and it's signed by a detached signature (see the first ds:Signature, with its ds:Reference linking to Book). The envelope also has an embedded SAML assertion which has its own enveloped signature.</p>
-
-<p>The instance of org.apache.cxf.rs.security.xml.XmlSigInHandler will handle a detached XML signature of the Book XML fragment on the server side. See the <a shape="rect" href="jax-rs-saml.html">JAX-RS SAML</a> for more info on how to deal with SAML assertions.</p>
-
-<p>Client code is nearly identical to the one shown in the Enveloped signatures section except that XmlSigOutInterceptor need to have an additional property set:</p>
-
-<div class="code panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl">
-<script class="theme: Default; brush: java; gutter: false" type="syntaxhighlighter"><![CDATA[
-
-// add the interceptor dealing with adding a signature
+</div></div><p>Note that the whole payload is enveloped by a configurable element wrapper. The Book instance is one part of the envelope and it's signed by a detached signature (see the first ds:Signature, with its ds:Reference linking to Book). The envelope also has an embedded SAML assertion which has its own enveloped signature.</p><p>The instance of org.apache.cxf.rs.security.xml.XmlSigInHandler will handle a detached XML signature of the Book XML fragment on the server side. See the <a shape="rect" href="jax-rs-saml.html">JAX-RS SAML</a> for more info on how to deal with SAML assertions.</p><p>Client code is nearly identical to the one shown in the Enveloped signatures section except that XmlSigOutInterceptor need to have an additional property set:</p><div class="code panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl">
+<script class="theme: Default; brush: java; gutter: false" type="syntaxhighlighter"><![CDATA[// add the interceptor dealing with adding a signature
XmlSigOutInterceptor sigInterceptor = new XmlSigOutInterceptor();
sigInterceptor.setStyle("detached");
]]></script>
-</div></div>
-
-<h2 id="JAX-RSXMLSecurity-Customizingthesignature">Customizing the signature</h2>
-
-<p>org.apache.cxf.rs.security.xml.XmlSigOutInterceptor manages the creation of the signature on the client side.<br clear="none">
-The following properties can be set on it at the moment:</p>
-
-<p>"style": possible values are "enveloped" (default), "enveloping" and "detached"<br clear="none">
-"envelopedName": only used with the "detached" style, default is "{<a shape="rect" class="external-link" href="http://org.apache.cxf/rs/env" rel="nofollow">http://org.apache.cxf/rs/env</a>}Envelope"<br clear="none">
-"signatureAlgorithm": default is "http://www.w3.org/2000/09/xmldsig#rsa-sha1"<br clear="none">
-"digestAlgorithm": default is "http://www.w3.org/2000/09/xmldsig#sha1"</p>
-
-<h1 id="JAX-RSXMLSecurity-XMLEncryption">XML Encryption</h1>
-
-<p>Encrypting XML payloads makes it possible to drop a requirement for HTTPS.</p>
-
-<p>Here is a payload example:</p>
-
-<div class="code panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl">
-<script class="theme: Default; brush: xml; gutter: false" type="syntaxhighlighter"><![CDATA[
-<xenc:EncryptedData xmlns:xenc="http://www.w3.org/2001/04/xmlenc#">
+</div></div><h2 id="JAX-RSXMLSecurity-Customizingthesignature">Customizing the signature</h2><p>org.apache.cxf.rs.security.xml.XmlSigOutInterceptor manages the creation of the signature on the client side.<br clear="none"> The following properties can be set on it at the moment:</p><p>"style": possible values are "enveloped" (default), "enveloping" and "detached"<br clear="none"> "envelopedName": only used with the "detached" style, default is "{<a shape="rect" class="external-link" href="http://org.apache.cxf/rs/env" rel="nofollow">http://org.apache.cxf/rs/env</a>}Envelope"<br clear="none"> "signatureAlgorithm": default is "http://www.w3.org/2000/09/xmldsig#rsa-sha1"<br clear="none"> "digestAlgorithm": default is "http://www.w3.org/2000/09/xmldsig#sha1"</p><h2 id="JAX-RSXMLSecurity-SignatureKeyInfoValidation">Signature Key Info Validation</h2><p>By default ds:Signature is expected to contain ds:KeyInfo element.</p><p>Setting a "keyInfoMustBeAvailable" property to false on the out i
nterceptors will lead to KeyInfo not included.</p><p>If the same property is set to false on the in interceptors then either an authenticated Principal name or a default store alias will be used to load the certificate for validating the signature.</p><h1 id="JAX-RSXMLSecurity-XMLEncryption">XML Encryption</h1><p>Encrypting XML payloads makes it possible to drop a requirement for HTTPS.</p><p>Here is a payload example:</p><div class="code panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl">
+<script class="theme: Default; brush: xml; gutter: false" type="syntaxhighlighter"><![CDATA[<xenc:EncryptedData xmlns:xenc="http://www.w3.org/2001/04/xmlenc#">
<xenc:EncryptionMethod Algorithm="http://www.w3.org/2001/04/xmlenc#aes128-cbc"/>
<ds:KeyInfo xmlns:ds="http://www.w3.org/2000/09/xmldsig#">
<ds:RetrievalMethod Type="http://www.w3.org/2001/04/xmlenc#EncryptedKey"/>
@@ -447,13 +347,8 @@ The following properties can be set on i
</xenc:CipherData>
</xenc:EncryptedData>
]]></script>
-</div></div>
-
-<p>Here is a server configuration fragment:</p>
-
-<div class="code panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl">
-<script class="theme: Default; brush: xml; gutter: false" type="syntaxhighlighter"><![CDATA[
-<bean id="serviceBean" class="org.apache.cxf.systest.jaxrs.security.BookStore"/>
+</div></div><p>Here is a server configuration fragment:</p><div class="code panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl">
+<script class="theme: Default; brush: xml; gutter: false" type="syntaxhighlighter"><![CDATA[<bean id="serviceBean" class="org.apache.cxf.systest.jaxrs.security.BookStore"/>
<bean id="xmlSigInHandler" class="org.apache.cxf.rs.security.xml.XmlSigInHandler"/>
<bean id="xmlEncInHandler" class="org.apache.cxf.rs.security.xml.XmlEncInHandler"/>
@@ -476,15 +371,8 @@ The following properties can be set on i
</jaxrs:server>
]]></script>
-</div></div>
-
-<p>This configuration supports receiving signed and then encrypted XML payloads.</p>
-
-<p>The code:</p>
-
-<div class="code panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl">
-<script class="theme: Default; brush: java; gutter: false" type="syntaxhighlighter"><![CDATA[
-String address = "https://localhost:8080/xmlencryption/bookstore/books";
+</div></div><p>This configuration supports receiving signed and then encrypted XML payloads.</p><p>The code:</p><div class="code panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl">
+<script class="theme: Default; brush: java; gutter: false" type="syntaxhighlighter"><![CDATA[String address = "https://localhost:8080/xmlencryption/bookstore/books";
JAXRSClientFactoryBean bean = new JAXRSClientFactoryBean();
bean.setAddress(address);
@@ -520,15 +408,8 @@ WebClient wc = bean.createWebClient();
Response r = wc.post(new Book("CXF", 126L), Book.class);
assertEquals(200, r.getStatus());
]]></script>
-</div></div>
-
-<p>Note that XmlEncOutInterceptor interceptor has a "symmetricEncAlgorithm" property set to a weaker type just to get CXF tests passing.</p>
-
-<p>The actual application client code does not expect a payload such as Book back but if it did then configuring the server to encrypt the response would be straightforward:</p>
-
-<div class="code panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl">
-<script class="theme: Default; brush: xml; gutter: false" type="syntaxhighlighter"><![CDATA[
-<bean id="serviceBean" class="org.apache.cxf.systest.jaxrs.security.BookStore"/>
+</div></div><p>Note that XmlEncOutInterceptor interceptor has a "symmetricEncAlgorithm" property set to a weaker type just to get CXF tests passing.</p><p>The actual application client code does not expect a payload such as Book back but if it did then configuring the server to encrypt the response would be straightforward:</p><div class="code panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl">
+<script class="theme: Default; brush: xml; gutter: false" type="syntaxhighlighter"><![CDATA[<bean id="serviceBean" class="org.apache.cxf.systest.jaxrs.security.BookStore"/>
<bean id="xmlSigInHandler" class="org.apache.cxf.rs.security.xml.XmlSigInHandler"/>
<bean id="xmlSigOutHandler" class="org.apache.cxf.rs.security.xml.XmlSigOutInterceptor"/>
@@ -560,30 +441,15 @@ assertEquals(200, r.getStatus());
</jaxrs:properties>
</jaxrs:server>
]]></script>
-</div></div>
-
-<p>Now the client code can be updated to expect an encrypted and signed Book back:</p>
-
-<div class="code panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl">
-<script class="theme: Default; brush: java; gutter: false" type="syntaxhighlighter"><![CDATA[
-// Use the previous code fragment, add the in interceptors:
+</div></div><p>Now the client code can be updated to expect an encrypted and signed Book back:</p><div class="code panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl">
+<script class="theme: Default; brush: java; gutter: false" type="syntaxhighlighter"><![CDATA[// Use the previous code fragment, add the in interceptors:
XmlEncInInterceptor encInInterceptor = new XmlEncInInterceptor();
bean.getInInterceptors().add(encInInterceptor);
XmlSigInInterceptor sigInInterceptor = new XmlSigInInterceptor();
bean.getInInterceptors().add(sigInInterceptor);
]]></script>
-</div></div>
-
-
-<h2 id="JAX-RSXMLSecurity-Usingtherequestsignaturecertificatesfortheencryption">Using the request signature certificates for the encryption</h2>
-
-<p><strong>From CXF 2.6.1 and 2.5.4:</strong></p>
-
-<p>When multiple clients are posting the encrypted and signed payloads, the following configuration will lead to the request signature certificates being utilized for encrypting the symmetric key used to encrypt the response:</p>
-
-<div class="code panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl">
-<script class="theme: Default; brush: xml; gutter: false" type="syntaxhighlighter"><![CDATA[
-<!-- server -->
+</div></div><h2 id="JAX-RSXMLSecurity-Usingtherequestsignaturecertificatesfortheencryption">Using the request signature certificates for the encryption</h2><p><strong>From CXF 2.6.1 and 2.5.4:</strong></p><p>When multiple clients are posting the encrypted and signed payloads, the following configuration will lead to the request signature certificates being utilized for encrypting the symmetric key used to encrypt the response:</p><div class="code panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl">
+<script class="theme: Default; brush: xml; gutter: false" type="syntaxhighlighter"><![CDATA[<!-- server -->
<jaxrs:server>
<jaxrs:properties>
<entry key="ws-security.callback-handler"
@@ -609,37 +475,8 @@ bean.getInInterceptors().add(sigInInterc
</jaxrs:properties>
</jaxrs:client>
]]></script>
-</div></div>
-
-<p>The "ws-security.encryption.username" server property is set to "useReqSigCert".</p>
-
-<p>Note that the client configuration assumes Alice (with its alice.properties) represents a given client, Bob (with its bob.properties) - the receiver/server. </p>
-
-<p>On the server side the encryption properties point to alice.properties and signature.properties to bob.properties. This is because the outbound signature needs to be done with the Bob's certificate and the encryption - with either the specific Alice's certificate or the certificate from the inbound signature. Note that the in encryption handler will check the signature properties first - this will ensure that the Bob's certificate used to encrypt the data on the client side can be validated, similarly for the in signature handler. </p>
-
-<h2 id="JAX-RSXMLSecurity-Customizingtheencryption">Customizing the encryption</h2>
-
-<p>org.apache.cxf.rs.security.xml.XmlEncOutInterceptor manages the encryption process.<br clear="none">
-The following properties can be set on it at the moment:<br clear="none">
-"symmetricEncAlgorithm": default is "http://www.w3.org/2001/04/xmlenc#aes256-cbc", complete URIs or short identifiers are supported, for example, "aes128-cbc" or "http://www.w3.org/2001/04/xmlenc#aes256-cbc". <br clear="none">
-"digestAlgorithm": optional, example "http://www.w3.org/2001/04/xmlenc#sha256" can be set.<br clear="none">
-"keyEncAlgorithm": default is "http://www.w3.org/2001/04/xmlenc#rsa-oaep-mgf1p"<br clear="none">
-"keyIdentifierType": default is "X509_KEY", "X509_ISSUER_SERIAL" is also supported - useful when the whole x509Certificate should not be embedded </p>
-
-<h2 id="JAX-RSXMLSecurity-GCMAlgorithmandBouncyCastleprovider">GCM Algorithm and BouncyCastle provider</h2>
-
-<p>Please see Colm's <a shape="rect" class="external-link" href="http://coheigea.blogspot.com/2012/04/note-on-cve-2011-1096.html" rel="nofollow">blog</a> for the information about the possible attack against XML Encryption and the GCM algorithm which needs to be used in order to prevent it.</p>
-
-
-<h1 id="JAX-RSXMLSecurity-Restrictingencryptionandsignaturealgorithms">Restricting encryption and signature algorithms</h1>
-
-<p><strong>From CXF 2.6.1 and 2.5.4:</strong></p>
-
-<p>It is possible to configure the in encryption and signature handlers with the properties restricting the encryption and signature algorithms that clients can use, for example:</p>
-
-<div class="code panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl">
-<script class="theme: Default; brush: xml; gutter: false" type="syntaxhighlighter"><![CDATA[
- <bean id="sigProps" class="org.apache.cxf.rs.security.xml.SignatureProperties">
+</div></div><p>The "ws-security.encryption.username" server property is set to "useReqSigCert".</p><p>Note that the client configuration assumes Alice (with its alice.properties) represents a given client, Bob (with its bob.properties) - the receiver/server.</p><p>On the server side the encryption properties point to alice.properties and signature.properties to bob.properties. This is because the outbound signature needs to be done with the Bob's certificate and the encryption - with either the specific Alice's certificate or the certificate from the inbound signature. Note that the in encryption handler will check the signature properties first - this will ensure that the Bob's certificate used to encrypt the data on the client side can be validated, similarly for the in signature handler.</p><h2 id="JAX-RSXMLSecurity-Customizingtheencryption">Customizing the encryption</h2><p>org.apache.cxf.rs.security.xml.XmlEncOutInterceptor manages the encryption process.<br clear="none"> The f
ollowing properties can be set on it at the moment:<br clear="none"> "symmetricEncAlgorithm": default is "http://www.w3.org/2001/04/xmlenc#aes256-cbc", complete URIs or short identifiers are supported, for example, "aes128-cbc" or "http://www.w3.org/2001/04/xmlenc#aes256-cbc". <br clear="none"> "digestAlgorithm": optional, example "http://www.w3.org/2001/04/xmlenc#sha256" can be set.<br clear="none"> "keyEncAlgorithm": default is "http://www.w3.org/2001/04/xmlenc#rsa-oaep-mgf1p"<br clear="none"> "keyIdentifierType": default is "X509_KEY", "X509_ISSUER_SERIAL" is also supported - useful when the whole x509Certificate should not be embedded</p><h2 id="JAX-RSXMLSecurity-GCMAlgorithmandBouncyCastleprovider">GCM Algorithm and BouncyCastle provider</h2><p>Please see Colm's <a shape="rect" class="external-link" href="http://coheigea.blogspot.com/2012/04/note-on-cve-2011-1096.html" rel="nofollow">blog</a> for the information about the possible attack against XML Encryption and the GCM algor
ithm which needs to be used in order to prevent it.</p><h1 id="JAX-RSXMLSecurity-Restrictingencryptionandsignaturealgorithms">Restricting encryption and signature algorithms</h1><p><strong>From CXF 2.6.1 and 2.5.4:</strong></p><p>It is possible to configure the in encryption and signature handlers with the properties restricting the encryption and signature algorithms that clients can use, for example:</p><div class="code panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl">
+<script class="theme: Default; brush: xml; gutter: false" type="syntaxhighlighter"><![CDATA[ <bean id="sigProps" class="org.apache.cxf.rs.security.xml.SignatureProperties">
<property name="signatureAlgo"
value="http://www.w3.org/2000/09/xmldsig#rsa-sha1"/>
<property name="signatureDigestAlgo"
@@ -674,22 +511,7 @@ The following properties can be set on i
<property name="encryptionProperties" ref="encProps"/>
</bean>
]]></script>
-</div></div>
-
-<p>Getting the same SignatureProperties and EncryptionProperties beans (with "sigProps" and "encProps" ids) registered with the outbound<br clear="none">
-handlers will ensure that the algorithms used by the current client have not only been validated on the inbound side but also used on the outbound side for encrypting and signing the data.</p>
-
-<p>Note that from CXF 2.7.1, 2.6.4 and 2.5.7, the XmlEncInHandler will require that the RSA-OAEP algorithm be used as the key transport encryption algorithm by default. As this algorithm is used by default by the XmlEncOutInterceptor, no action is required unless you are specifying a different algorithm on the outbound side. In this case, an EncryptionProperties object will need to be configured on XmlEncInHandler with the desired key transport algorithm.</p>
-
-<h1 id="JAX-RSXMLSecurity-Interoperability">Interoperability</h1>
-
-<p>The payloads containing the enveloping XML Signatures are structured according to the XML Signature specification and as such can be consumed by any XML Signature aware consumers capable of handling the enveloping signatures and extracting the signed payload. </p>
-
-<p>Same applies to enveloped signatures, for example, a signed SAML assertion always contains an enveloped signature.</p>
-
-<p>The way CXF creates detached XML Signatures is experimental, so at the moment CXF will be required on both ends for the detached signatures be created and validated.</p>
-
-<p>The current XML Encryption support is in line with the specification and thus the capable non-CXF consumers will be able to decrypt the payloads. </p></div>
+</div></div><p>Getting the same SignatureProperties and EncryptionProperties beans (with "sigProps" and "encProps" ids) registered with the outbound<br clear="none"> handlers will ensure that the algorithms used by the current client have not only been validated on the inbound side but also used on the outbound side for encrypting and signing the data.</p><p>Note that from CXF 2.7.1, 2.6.4 and 2.5.7, the XmlEncInHandler will require that the RSA-OAEP algorithm be used as the key transport encryption algorithm by default. As this algorithm is used by default by the XmlEncOutInterceptor, no action is required unless you are specifying a different algorithm on the outbound side. In this case, an EncryptionProperties object will need to be configured on XmlEncInHandler with the desired key transport algorithm.</p><h1 id="JAX-RSXMLSecurity-Interoperability">Interoperability</h1><p>The payloads containing the enveloping XML Signatures are structured according to the XML Signature specific
ation and as such can be consumed by any XML Signature aware consumers capable of handling the enveloping signatures and extracting the signed payload.</p><p>Same applies to enveloped signatures, for example, a signed SAML assertion always contains an enveloped signature.</p><p>The way CXF creates detached XML Signatures is experimental, so at the moment CXF will be required on both ends for the detached signatures be created and validated.</p><p>The current XML Encryption support is in line with the specification and thus the capable non-CXF consumers will be able to decrypt the payloads.</p></div>
</div>
<!-- Content -->
</td>