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>
