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 2013/06/04 15:48:10 UTC
svn commit: r864354 - in /websites/production/cxf/content: cache/docs.pageCache docs/jax-rs-oauth2.html

Author: buildbot
Date: Tue Jun  4 13:48:10 2013
New Revision: 864354

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 Tue Jun  4 13:48:10 2013
@@ -125,13 +125,13 @@ 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><ul><li><a shape="rect" href="#JAX-RSOAuth2-EndUserNameinAuthorizationForm">EndUser Name in Authorization Form</a></li></ul><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><li><a shape="rect" href="#JAX-RSOAuth2-CustomandEncryptedtokens">Custom and Encrypted tokens</a></li></ul><li><a shape="rect" href="#JAX-RSOAuth2-AccessTokenValidationService">AccessTokenValidationService
 </a></li></ul><li><a shape="rect" href="#JAX-RSOAuth2-SupportedGrants">Supported Grants</a></li><ul><li><a shape="rect" href="#JAX-RSOAuth2-AuthorizationCode">Authorization Code</a></li><li><a shape="rect" href="#JAX-RSOAuth2-Implicit">Implicit</a></li><li><a shape="rect" href="#JAX-RSOAuth2-ClientCredentials">Client Credentials</a></li><li><a shape="rect" href="#JAX-RSOAuth2-ResourceOwnerPasswordCredentials">Resource Owner Password Credentials</a></li><li><a shape="rect" href="#JAX-RSOAuth2-RefreshToken">Refresh Token</a></li><li><a shape="rect" href="#JAX-RSOAuth2-Assertions">Assertions</a></li><li><a shape="rect" href="#JAX-RSOAuth2-CustomGrants">Custom Grants</a></li></ul><li><a shape="rect" href="#JAX-RSOAuth2-PreAuthorizedaccesstokens">PreAuthorized access tokens</a></li><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-ThirdPartyClientAuthentication">Third Party Client Authentication</a></li><li><a shape="rect" href="#JAX-RSOAuth2-UserSessionAuthenticity">User Session Authenticity</a></li><li><a shape="rect" href="#JAX-RSOAuth2-CustomizingEndUserSubjectinitialization">Customizing End User Subject initialization</a></li><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-ClientRegistration">Client Registration</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><ul><li><a shape="rect" href="#JAX-RSOAuth2-EndUserNameinAuthorizationForm">EndUser Name in Authorization Form</a></li><li><a shape="rect" href="#JAX-RSOAuth2-PublicClients%28Devices%29andOOBResponse">Public Clients (Devices) and OOB Response</a></li></ul><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-MA
 C">MAC</a></li><li><a shape="rect" href="#JAX-RSOAuth2-CustomandEncryptedtokens">Custom and Encrypted tokens</a></li></ul><li><a shape="rect" href="#JAX-RSOAuth2-AccessTokenValidationService">AccessTokenValidationService</a></li></ul><li><a shape="rect" href="#JAX-RSOAuth2-SupportedGrants">Supported Grants</a></li><ul><li><a shape="rect" href="#JAX-RSOAuth2-AuthorizationCode">Authorization Code</a></li><li><a shape="rect" href="#JAX-RSOAuth2-Implicit">Implicit</a></li><li><a shape="rect" href="#JAX-RSOAuth2-ClientCredentials">Client Credentials</a></li><li><a shape="rect" href="#JAX-RSOAuth2-ResourceOwnerPasswordCredentials">Resource Owner Password Credentials</a></li><li><a shape="rect" href="#JAX-RSOAuth2-RefreshToken">Refresh Token</a></li><li><a shape="rect" href="#JAX-RSOAuth2-Assertions">Assertions</a></li><li><a shape="rect" href="#JAX-RSOAuth2-CustomGrants">Custom Grants</a></li></ul><li><a shape="rect" href="#JAX-RSOAuth2-PreAuthorizedaccesstokens">PreAuthorized acc
 ess tokens</a></li><li><a shape="rect" href="#JAX-RSOAuth2-Preregisteredscopes">Pre-registered scopes</a></li><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-ThirdPartyClientAuthentication">Third Party Client Authentication</a></li><li><a shape="rect" href="#JAX-RSOAuth2-UserSessionAuthenticity">User Session Authenticity</a></li><li><a shape="rect" href="#JAX-RSOAuth2-CustomizingEndUserSubjectinitialization">Customizing End User Subject initialization</a></li><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-WhatI
 sNext">What Is Next</a></li></ul></div>
 
 <h1><a shape="rect" name="JAX-RSOAuth2-Introduction"></a>Introduction</h1>
 
-<p>CXF 2.6.0 provides an initial implementation of <a shape="rect" class="external-link" href="http://tools.ietf.org/html/draft-ietf-oauth-v2" rel="nofollow">OAuth 2.0</a>. See also the <a shape="rect" href="jax-rs-oauth.html" title="JAX-RS OAuth">JAX-RS OAuth</a> page for information about OAuth 1.0.</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" title="JAX-RS OAuth">JAX-RS OAuth</a> page for information about OAuth 1.0.</p>
 
-<p>Authorization Code, Implicit, Client Credentials, Resource Owner Password Credentials and Refresh Token grants are currently supported with other grant handlers to be added later.</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>
 
@@ -167,11 +167,17 @@ Apache CXF -- JAX-RS OAuth2
 <span class="code-tag">&lt;dependency&gt;</span>
   <span class="code-tag">&lt;groupId&gt;</span>org.apache.cxf<span class="code-tag">&lt;/groupId&gt;</span>
   <span class="code-tag">&lt;artifactId&gt;</span>cxf-rt-rs-security-oauth2<span class="code-tag">&lt;/artifactId&gt;</span>
-  <span class="code-tag">&lt;version&gt;</span>2.6.0<span class="code-tag">&lt;/version&gt;</span>
+  <span class="code-tag">&lt;version&gt;</span>2.7.5<span class="code-tag">&lt;/version&gt;</span>
 <span class="code-tag">&lt;/dependency&gt;</span>
 </pre>
 </div></div>
 
+<h1><a shape="rect" name="JAX-RSOAuth2-ClientRegistration"></a>Client Registration</h1>
+
+<p>Client Registration is typically done out of band (OAuth2 experts are also finalizing the dynamic client registration).<br clear="none">
+The client registration service will offer an HTML form where the clients will enter their details, see 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/Client.java">Client</a> bean for the currently supported properties.  <br clear="none">
+Note CXF may offer an abstract client registration service in the future to minimize the effort to get the custom registration service created from scratch.  </p>
+
 <h1><a shape="rect" name="JAX-RSOAuth2-DevelopingOAuth2Servers"></a>Developing OAuth2 Servers</h1>
 
 <p>OAuth2 server is the core piece of the complete OAuth2-based solution. Typically it contains 2 services for:<br clear="none">
@@ -308,6 +314,21 @@ Cookie=[JSESSIONID=1c289vha0cxfe],
 <p>You may want to display a resource owner/end user name in the authorization form this user will be facing, you can get org.apache.cxf.rs.security.oauth2.provider.ResourceOwnerNameProvider registered with either AuthorizationCodeGrantService or ImplicitGrantService.<br clear="none">
 org.apache.cxf.rs.security.oauth2.provider.DefaultResourceOwnerNameProvider, if registered, will return an actual login name, the custom implementations may choose to return a  complete user name instead, etc.   </p>
 
+<h3><a shape="rect" name="JAX-RSOAuth2-PublicClients%28Devices%29andOOBResponse"></a>Public Clients (Devices) and OOB Response</h3>
+
+<p>Starting from CXF 2.7.6, the authorization code can be returned out-of-band (OOB), see <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/OOBAuthorizationResponse.java">OOBAuthorizationResponse</a> bean. By default, it is returned directly to the end user, unless a 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/provider/OOBResponseDeliverer.java">OOBResponseDeliverer</a> is registered with AuthorizationCodeGrantService which may deliver it to the client via some custom back channel. </p>
+
+<p>Authorization service will only return the code OOB if a Client has been registered as a public client with no client secret and redirect URI and the service itself has a "canSupportPublicClients" property enabled. The same property will also have to be enabled on AccessTokenService (described in the next section) for a public client without a secret be able to exchange a code grant for an access token.</p>
+
+<p>Having OOB responses supported is useful when a public client (typically a device which can not keep the client secrets) needs to get a code grant. what will happen is that a device owner will send a request to Authorization Service which may look like this:</p>
+<div class="preformatted panel" style="border-width: 1px;"><div class="preformattedContent panelContent">
+<pre>GET
+http://localhost:8080/services/social/authorize?client_id=mobileClient&amp;response_type=code   
+</pre>
+</div></div>
+
+<p>Assuming the 'mobileClient' has been registered as public one with no secret and the service has been set up to support such clients, the end user will get a chance to authorize this client the same way it can do confidential clients, and after this user gets back a code (delivered directly in the response HTML page by default) the user will enter the code securely into the device which will then replace it for a time-scoped access token by contacting AccessTokenService. </p>
+
 <h2><a shape="rect" name="JAX-RSOAuth2-AccessTokenService"></a>AccessTokenService </h2>
 
 <p>The role of AccessTokenService is to exchange a token grant for a new access token which will be used by the client to access the end user's resources. <br clear="none">
@@ -527,7 +548,7 @@ Authorization: MAC id=<span class="code-
 
 <h3><a shape="rect" name="JAX-RSOAuth2-Implicit"></a>Implicit</h3>
 
-<p>Implicit grant is supported the same way Authorization Code grant is except that the response to the client running within a web browser is formatted differently, using URI fragments.</p>
+<p>Implicit grant is supported the same way Authorization Code grant is except that the response to the client running within a web browser is formatted differently, using URI fragments. </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/services/ImplicitGrantService.java">ImplicitGrantService</a> service 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/grants/code/AuthorizationCodeDataProvider.java">AuthorizationCodeDataProvider</a> data provider can support a redirection-based Implicit flow. </p>
 
@@ -536,6 +557,8 @@ Authorization: MAC id=<span class="code-
 <p>Also note that when an Implicit grant client (running within a browser) replaces the code grant for a new access token and tries to access the end user's resource, Cross Origin Resource Sharing (CORS) support will most likely need to be enabled on the end user's resource server.<br clear="none">
 The simplest approach is to register a CXF <a shape="rect" href="http://cxf.apache.org/docs/jax-rs-cors.html">CORS filter</a>, right before OAuth2 filter (see on it below).</p>
 
+<p>Starting from CXF 2.7.5 it is possible to request ImplicitGrantService to return a registered Client id to the browser-hosted client. This is recommended so that the client can verify that the token is meant to be delivered to this client. </p>
+
 <h3><a shape="rect" name="JAX-RSOAuth2-ClientCredentials"></a>Client Credentials</h3>
 
 <p>Register <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/clientcred/ClientCredentialsGrantHandler.java">ClientCredentialsGrantHandler</a> handler with AccessTokenService for this grant be supported.</p>
@@ -580,6 +603,10 @@ OAuthDataProvider is always checked firs
 
 <p>Also note that using a refresh token grant may further help with minimizing the end user involvement, in cases when the current access token has expired.</p>
 
+<h2><a shape="rect" name="JAX-RSOAuth2-Preregisteredscopes"></a>Pre-registered scopes</h2>
+
+<p>Clients can register custom scopes they will be expected to use and then avoid specifying the scopes when requesting the code grants or access tokens.<br clear="none">
+Alternatively it makes it easier to support so called wild-card scopes. For example, a client pre-registers a scope "update" and actually uses an "update-7" scope: Redirection-based services and access token grants can be configured to do a partial scope match, in this case, validate that "update-7" starts from "update"</p>
 
 <h2><a shape="rect" name="JAX-RSOAuth2-WritingOAuthDataProvider"></a>Writing OAuthDataProvider</h2>
 
@@ -824,6 +851,28 @@ how one can access a user login name tha
 
 <p>The injected MessageContext provides an access to <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/OAuthContext.java">OAuthContext</a> which has been set by OAuth2 filters described in the previous section. OAuthContext will act as a container of the information which can be useful to the custom application code which do not need to deal with the OAuth2 internals. OAuthContextUtils provides a number of utility methods for retrieving and working with OAuthContext.</p>
 
+<p>Note that starting from CXF 2.7.6 it is also possible to inject OAuthContext as JAX-RS context:</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.OAuthContext;
+
+@Path(<span class="code-quote">"/userResource"</span>)
+<span class="code-keyword">public</span> class ThirdPartyAccessService {
+
+    @Context 
+    <span class="code-keyword">private</span> OAuthContext context;
+	
+    @GET
+    <span class="code-keyword">public</span> UserResource getUserResource() {
+	<span class="code-comment">//....
+</span>    }
+}
+</pre>
+</div></div> 
+
+<p>org.apache.cxf.rs.security.oauth2.provider.OAuthContextProvider will have to be registered as jaxrs:provider for it to work.</p>
+
 <h1><a shape="rect" name="JAX-RSOAuth2-Clientsidesupport"></a>Client-side support</h1>
 
 <p>When developing a third party application which needs to participate in OAuth2 flows one has to write the code that will redirect users to OAuth2 AuthorizationCodeGrantService, interact with AccessTokenService in order to exchange code grants for access tokens as well as correctly build Authorization OAuth2 headers when accessing the end users' resources. JAX-RS makes it straightforward to support the redirection, while <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/OAuthClientUtils.java">OAuthClientUtils</a> class makes it possible to encapsulate most of the complexity away from the client application code.   </p>