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"><dependency></span>
<span class="code-tag"><groupId></span>org.apache.cxf<span
class="code-tag"></groupId></span>
<span
class="code-tag"><artifactId></span>cxf-rt-rs-security-oauth2<span
class="code-tag"></artifactId></span>
- <span class="code-tag"><version></span>2.6.0<span
class="code-tag"></version></span>
+ <span class="code-tag"><version></span>2.7.5<span
class="code-tag"></version></span>
<span class="code-tag"></dependency></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&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>
