cxf-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From build...@apache.org
Subject svn commit: r830021 - in /websites/production/cxf/content: cache/docs.pageCache docs/jax-rs-oauth2.html
Date Fri, 24 Aug 2012 12:47:29 GMT
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&lt;<span class="code-object">String</span>&gt; 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>
 



Mime
View raw message