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> </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  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. 
 </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[<dependency>
<groupId>org.apache.cxf</groupId>
<artifactId>cxf-rt-rs-security-oauth2</artifactId>
@@ -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:
{"access_token":"5b5c8e677413277c4bb8b740d522b378",
"token_type":"mac",
"mac_key"="1234568",
"mac_algorithm"="hmac-sha-1"}
]]></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"><