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 2012/08/24 14:47:29 UTC
svn commit: r830021 - in /websites/production/cxf/content:
cache/docs.pageCache docs/jax-rs-oauth2.html
Author: buildbot
Date: Fri Aug 24 12:47:29 2012
New Revision: 830021
Log:
Production update by buildbot for cxf
Modified:
websites/production/cxf/content/cache/docs.pageCache
websites/production/cxf/content/docs/jax-rs-oauth2.html
Modified: websites/production/cxf/content/cache/docs.pageCache
==============================================================================
Binary files - no diff available.
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 Fri Aug 24 12:47:29 2012
@@ -125,7 +125,7 @@ Apache CXF -- JAX-RS OAuth2
<div>
-<ul><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-DevelopingOAuth2Servers">Developing OAuth2 Servers</a></li><ul><li><a shape="rect" href="#JAX-RSOAuth2-AuthorizationService">Authorization Service</a></li><li><a shape="rect" href="#JAX-RSOAuth2-AccessTokenService">AccessTokenService</a></li><ul><li><a shape="rect" href="#JAX-RSOAuth2-AccessTokenValidationService">AccessTokenValidationService</a></li></ul><li><a shape="rect" href="#JAX-RSOAuth2-WritingOAuthDataProvider">Writing OAuthDataProvider</a></li><li><a shape="rect" href="#JAX-RSOAuth2-OAuthServerJAXRSendpoints">OAuth Server JAX-RS endpoints</a></li></ul><li><a shape="rect" href="#JAX-RSOAuth2-ProtectingresourceswithOAuthfilters">Protecting resources with OAuth filters</a></li><li><a shape="rect" href="#JAX-RSOAuth2-Howtogettheuserloginname">How to get the user login
name</a></li><li><a shape="rect" href="#JAX-RSOAuth2-Clientsidesupport">Client-side support</a></li><li><a shape="rect" href="#JAX-RSOAuth2-OAuth2withouttheExplicitAuthorization">OAuth2 without the Explicit Authorization</a></li><li><a shape="rect" href="#JAX-RSOAuth2-OAuthWithoutaBrowser">OAuth Without a Browser</a></li><li><a shape="rect" href="#JAX-RSOAuth2-Reportingerrordetails">Reporting error details</a></li><li><a shape="rect" href="#JAX-RSOAuth2-Designconsiderations">Design considerations</a></li><ul><li><a shape="rect" href="#JAX-RSOAuth2-ControllingtheAccesstoResourceServer">Controlling the Access to Resource Server</a></li><ul><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><a shape="rect"
href="#JAX-RSOAuth2-SingleSignOn">Single Sign On</a></li></ul><li><a shape="rect" href="#JAX-RSOAuth2-WhatIsNext">What Is Next</a></li></ul></div>
+<ul><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-DevelopingOAuth2Servers">Developing OAuth2 Servers</a></li><ul><li><a shape="rect" href="#JAX-RSOAuth2-AuthorizationService">Authorization Service</a></li><li><a shape="rect" href="#JAX-RSOAuth2-AccessTokenService">AccessTokenService</a></li><ul><li><a shape="rect" href="#JAX-RSOAuth2-AccessTokenTypes">Access Token Types</a></li><ul><li><a shape="rect" href="#JAX-RSOAuth2-Bearer">Bearer</a></li><li><a shape="rect" href="#JAX-RSOAuth2-MAC">MAC</a></li></ul><li><a shape="rect" href="#JAX-RSOAuth2-AccessTokenValidationService">AccessTokenValidationService</a></li></ul><li><a shape="rect" href="#JAX-RSOAuth2-WritingOAuthDataProvider">Writing OAuthDataProvider</a></li><li><a shape="rect" href="#JAX-RSOAuth2-OAuthServerJAXRSendpoints">OAuth Server JAX-RS endpoints</a></li></ul><l
i><a shape="rect" href="#JAX-RSOAuth2-ProtectingresourceswithOAuthfilters">Protecting resources with OAuth filters</a></li><li><a shape="rect" href="#JAX-RSOAuth2-Howtogettheuserloginname">How to get the user login name</a></li><li><a shape="rect" href="#JAX-RSOAuth2-Clientsidesupport">Client-side support</a></li><li><a shape="rect" href="#JAX-RSOAuth2-OAuth2withouttheExplicitAuthorization">OAuth2 without the Explicit Authorization</a></li><li><a shape="rect" href="#JAX-RSOAuth2-OAuthWithoutaBrowser">OAuth Without a Browser</a></li><li><a shape="rect" href="#JAX-RSOAuth2-Reportingerrordetails">Reporting error details</a></li><li><a shape="rect" href="#JAX-RSOAuth2-Designconsiderations">Design considerations</a></li><ul><li><a shape="rect" href="#JAX-RSOAuth2-ControllingtheAccesstoResourceServer">Controlling the Access to Resource Server</a></li><ul><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><a shape="rect" href="#JAX-RSOAuth2-SingleSignOn">Single Sign On</a></li></ul><li><a shape="rect" href="#JAX-RSOAuth2-WhatIsNext">What Is Next</a></li></ul></div>
<h1><a shape="rect" name="JAX-RSOAuth2-Introduction"></a>Introduction</h1>
@@ -329,9 +329,9 @@ plus the redirect URI the authorization
Note that the alternative client authentication methods are also possible, in this case the token service will expect a mapping between the client credentials and the client_id representing the client registration available.</p>
<p>After validating the request, the service will find a matching <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">AccessTokenGrantHandler</a> and request to create 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/common/ServerAccessToken.java">ServerAccessToken</a> which is a server-side representation of the access token.<br clear="none">
-The grant handlers, such as <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/AuthorizationCodeGrantHandler.java">AuthorizationCodeGrantHandler</a> may delegate the creation of the actual access token to data providers, which may use the available utility classes such as <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/bearer/BearerAccessToken.java">BearerAccessToken</a> shipped with CXF or depend on other 3rd party libraries to create the tokens.</p>
+The grant handlers, such as <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/AuthorizationCodeGrantHandler.java">AuthorizationCodeGrantHandler</a> may delegate the creation of the actual access token to data providers, which may create Bearer or MAC tokens with the help of utility classes shipped with CXF or depend on other 3rd party token libraries.</p>
-<p>The data providers are also do not strictly required to persist the data such as access tokens, instead the token key may an encrypted bag capturing all the relevant information.</p>
+<p>The data providers do not strictly required to persist the data such as access tokens, instead the token key may act as an encrypted bag capturing all the relevant information.</p>
<p>Now that the token has been created, it is mapped by the service to 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/common/ClientAccessToken.java">client representation</a> and is returned back as a JSON payload:</p>
@@ -367,6 +367,137 @@ Headers:
<p>Note that the access token key is passed as the Bearer scheme value. Other token types such as MAC ones, etc, can be represented differently.</p>
+<h3><a shape="rect" name="JAX-RSOAuth2-AccessTokenTypes"></a>Access Token Types</h3>
+
+<p>As mentioned above, AccessTokenService can work with whatever token is created by a given data provider. This section provides more information on how CXF may help with supporting Bearer and MAC tokens.</p>
+
+<h4><a shape="rect" name="JAX-RSOAuth2-Bearer"></a>Bearer</h4>
+
+<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/bearer/BearerAccessToken.java">BearerAccessToken</a> utility class can be used to create Bearer tokens:</p>
+
+<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
+<pre class="code-java">
+<span class="code-keyword">import</span> org.apache.cxf.rs.security.oauth2.common.AccessTokenRegistration;
+<span class="code-keyword">import</span> org.apache.cxf.rs.security.oauth2.common.ServerAccessToken;
+<span class="code-keyword">import</span> org.apache.cxf.rs.security.oauth2.tokens.bearer.BearerAccessToken;
+
+<span class="code-keyword">public</span> class CustomOAuthDataProvider <span class="code-keyword">implements</span> AuthorizationCodeDataProvider {
+
+ <span class="code-keyword">public</span> ServerAccessToken createAccessToken(AccessTokenRegistration reg)
+ <span class="code-keyword">throws</span> OAuthServiceException {
+
+ ServerAccessToken token = <span class="code-keyword">new</span> BearerAccessToken(reg.getClient(), 3600L);
+
+ List<<span class="code-object">String</span>> scope = reg.getApprovedScope().isEmpty() ? reg.getRequestedScope()
+ : reg.getApprovedScope();
+ token.setScopes(convertScopeToPermissions(reg.getClient(), scope));
+ token.setSubject(reg.getSubject());
+ token.setGrantType(reg.getGrantType());
+
+ <span class="code-comment">// persist as needed and then <span class="code-keyword">return</span>
+</span>
+ <span class="code-keyword">return</span> token;
+ }
+ <span class="code-comment">// other methods are not shown
+</span>}
+</pre>
+</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><a shape="rect" name="JAX-RSOAuth2-MAC"></a>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-hammer-oauth-v2-mac-token-05" 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/mac/MacAccessToken.java">MacAccessToken</a> utility class can be used to create MAC tokens:</p>
+
+<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
+<pre class="code-java">
+<span class="code-keyword">import</span> org.apache.cxf.rs.security.oauth2.common.AccessTokenRegistration;
+<span class="code-keyword">import</span> org.apache.cxf.rs.security.oauth2.common.ServerAccessToken;
+<span class="code-keyword">import</span> org.apache.cxf.rs.security.oauth2.tokens.mac.HmacAlgorithm;
+<span class="code-keyword">import</span> org.apache.cxf.rs.security.oauth2.tokens.mac.MacAccessToken;
+
+<span class="code-keyword">public</span> class CustomOAuthDataProvider <span class="code-keyword">implements</span> AuthorizationCodeDataProvider {
+
+ <span class="code-keyword">public</span> ServerAccessToken createAccessToken(AccessTokenRegistration reg)
+ <span class="code-keyword">throws</span> OAuthServiceException {
+
+ <span class="code-comment">// generate
+</span> ServerAccessToken token = <span class="code-keyword">new</span> MacAccessToken(reg.getClient(),
+ HmacAlgorithm.HmacSHA1,
+ 3600L);
+
+ <span class="code-comment">// set other token fields as shown in the Bearer section
+</span>
+ <span class="code-comment">// persist as needed and then <span class="code-keyword">return</span>
+</span>
+ <span class="code-keyword">return</span> token;
+ }
+ <span class="code-comment">// other methods are not shown
+</span>}
+</pre>
+</div></div>
+
+<p>One can expect the following response:</p>
+
+<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
+<pre class="code-xml">
+Response-Code: 200
+Content-Type: application/json
+Headers: {
+ Cache-Control=[no-store],
+ Pragma=[no-cache],
+ Date=[Thu, 12 Apr 2012 14:36:29 GMT]
+}
+
+Payload:
+
+{<span class="code-quote">"access_token"</span>:<span class="code-quote">"5b5c8e677413277c4bb8b740d522b378"</span>, <span class="code-quote">"token_type"</span>:<span class="code-quote">"mac"</span>, <span class="code-quote">"secret"</span>=<span class="code-quote">"1234568"</span>, algorithm=<span class="code-quote">"hmac-sha-1"</span>}
+</pre>
+</div></div>
+
+<p>Note that 'access_token' is the MAC key identifier, 'secret' - MAC key.</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/tokens/mac/MacAccessTokenValidator.java">MacAccessTokenValidator</a> has to be registered with OAuthRequestFilter for validating the incoming MAC tokens. This validator can get a reference to 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/tokens/mac/NonceVerifier.java">NonceVerifier</a> with CXF possibly shipping a default implementation in the future.</p>
+
+<p>The client can use CXF OAuthClientUtils to create Authorization MAC headers. All is needed is to provide references to ClientAccessToken representing the MAC token issued by AccessTokenService 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/client/HttpRequestProperties.java">HttpRequestProperties</a> capturing the information about the current request URI:</p>
+
+<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
+<pre class="code-java">
+<span class="code-object">String</span> requestURI = <span class="code-quote">"http:<span class="code-comment">//localhost:8080/calendar"</span>;
+</span>WebClient wc = WebClient.create(requestURI);
+
+<span class="code-comment">// represents client registration
+</span>OAuthClientUtils.Consumer consumer = getConsumer();
+<span class="code-comment">// the token issued by AccessTokenService
+</span>ClientAccessToken token = getToken();
+
+HttpRequestProperties httpProps = <span class="code-keyword">new</span> HttpRequestProperties(wc, <span class="code-quote">"GET"</span>);
+<span class="code-object">String</span> authHeader = OAuthClientUtils.createAuthorizationHeader(consumer, token, httpProps);
+wc.header(<span class="code-quote">"Authorization"</span>, authHeader);
+
+Calendar calendar = wc.get(Calendar.class);
+</pre>
+</div></div>
+
+<p>This code will result in something like:</p>
+
+<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
+<pre class="code-xml">
+GET /calendar HTTP/1.1
+Host: localhost
+Accept: application/xml
+Authorization: MAC id=<span class="code-quote">"5b5c8e677413277c4bb8b740d522b378"</span>,
+ nonce=<span class="code-quote">"273156:di3hvdf8"</span>,
+ mac=<span class="code-quote">"W7bdMZbv9UWOTadASIQHagZyirA="</span>
+ ext=<span class="code-quote">"12345678"</span>
+</pre>
+</div></div>
+
+<p>where 'ext' attribute is used to pass a timestamp value.</p>
+
<h3><a shape="rect" name="JAX-RSOAuth2-AccessTokenValidationService"></a>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>