cxf-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From build...@apache.org
Subject svn commit: r864354 - in /websites/production/cxf/content: cache/docs.pageCache docs/jax-rs-oauth2.html
Date Tue, 04 Jun 2013 13:48:10 GMT
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>



Mime
View raw message