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 2014/02/14 15:47:59 UTC
svn commit: r897909 - in /websites/production/cxf/content:
cache/docs.pageCache docs/jax-rs-oauth2.html
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"><![CDATA[String requestURI = "http://localhost:8080/calendar";
WebClient wc = WebClient.create(requestURI);