cxf-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From build...@apache.org
Subject svn commit: r897909 - in /websites/production/cxf/content: cache/docs.pageCache docs/jax-rs-oauth2.html
Date Fri, 14 Feb 2014 14:47:59 GMT
Author: buildbot
Date: Fri Feb 14 14:47:59 2014
New Revision: 897909

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 Feb 14 14:47:59 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.rbtoc1392223669688 {padding: 0px;}
-div.rbtoc1392223669688 ul {list-style: disc;margin-left: 0px;}
-div.rbtoc1392223669688 li {margin-left: 0px;padding-left: 0px;}
+div.rbtoc1392389258213 {padding: 0px;}
+div.rbtoc1392389258213 ul {list-style: disc;margin-left: 0px;}
+div.rbtoc1392389258213 li {margin-left: 0px;padding-left: 0px;}
 
-/*]]>*/</style></p><div class="toc-macro rbtoc1392223669688">
+/*]]>*/</style></p><div class="toc-macro rbtoc1392389258213">
 <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,7 @@ div.rbtoc1392223669688 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-Encryptedtokens">Encrypted tokens</a>
+<ul class="toc-indentation"><li><a shape="rect" href="#JAX-RSOAuth2-Bearer">Bearer</a></li><li><a
shape="rect" href="#JAX-RSOAuth2-HAWK">HAWK</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>
@@ -142,7 +142,7 @@ div.rbtoc1392223669688 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>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>&#160;</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">
+</div><h1 id="JAX-RSOAuth2-Introduction">Introduction</h1><p>New:</p><ul
style="list-style-type: square;"><li>CXF 3.0.0-milestone2 makes it simpler to encrypt
the token and other OAuth2 server model state</li><li>OAuthDataProvider has a
new revokeToken() method added&#160; to support the client-driven token revocation</li><li>AccessTokenValidationService
has been enhanced to ensure the validation can proceed only if the authenticated Principal
is available.&#160; &#160;</li><li>OAuthRequestInterceptor has been added
to make it easier for non-JAXRS endpoints to use OAuth2 tokens</li></ul><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 current
 ly 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 serve
 r. 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 infor
 mation 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 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[&lt;dependency&gt;
   &lt;groupId&gt;org.apache.cxf&lt;/groupId&gt;
   &lt;artifactId&gt;cxf-rt-rs-security-oauth2&lt;/artifactId&gt;
@@ -261,14 +261,14 @@ public class CustomOAuthDataProvider imp
 		token.setSubject(reg.getSubject());
 		token.setGrantType(reg.getGrantType());
 		
-                // persist as needed and then return
+        // persist or encrypt and return
 
 		return token;
    }
    // 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-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">
+</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-HAWK">HAWK</h4><p>Starting
from CXF 3.0.0-milestone2 the <a shape="rect" class="external-link" href="https://github.com/hueniverse/hawk"
rel="nofollow">Hawk</a> scheme is supported instead of MAC (described in the next
section). The way it is supported is identical to the way MAC scheme is supported in earlier
CXF versions. The only differences are: 'Hawk' replaces 'Mac' in the Authorization header,
the Hawk token returned by the server will have 'secret' and 'algorithm' parameters instead
of 'mac_key' and 'mac_algorithm' parameters.</p><h4 id="JAX-RSOAuth2-MAC">MAC</h4><p>The
text below applies to CXF up to 3.0.0-milestone2. Starting from 3.0.0-milestone2 MAC scheme
is not supported, see above about the Hawk scheme. Support for the MAC sch
 eme will be re-introduced once the OAuth2 working group finishes <a shape="rect" class="external-link"
href="http://tools.ietf.org/html/draft-ietf-oauth-v2-http-mac-05" rel="nofollow">this effort</a>.</p><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/branches/2.7.x//rt/rs/security/oauth-parent/oauth2/src/main/java/org/apache/cxf/rs/security/oauth2/tokens/mac/MacAccess
 Token.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;
@@ -306,7 +306,7 @@ Payload: 
 
 {&quot;access_token&quot;:&quot;5b5c8e677413277c4bb8b740d522b378&quot;, &quot;token_type&quot;:&quot;mac&quot;,
&quot;mac_key&quot;=&quot;1234568&quot;, &quot;mac_algorithm&quot;=&quot;hmac-sha-1&quot;}
 ]]></script>
-</div></div><p>Note that 'access_token' is the MAC key identifier.</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/re
 pos/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
pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl">
+</div></div><p>Note that 'access_token' is the MAC key identifier.</p><p><a
shape="rect" class="external-link" href="http://svn.apache.org/repos/asf/cxf/branches/2.7.x/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.apac
 he.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
pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl">
 <script class="theme: Default; brush: java; gutter: false" type="syntaxhighlighter"><![CDATA[String
requestURI = &quot;http://localhost:8080/calendar&quot;;
 WebClient wc = WebClient.create(requestURI);
 



Mime
View raw message