Author: buildbot
Date: Thu Apr 12 13:48:03 2012
New Revision: 812532
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 Thu Apr 12 13:48:03
2012
@@ -125,7 +125,7 @@ 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-DevelopingOAuthServers">Developing OAuth
Servers</a></li><ul><li><a shape="rect"
href="#JAX-RSOAuth2-RequestTokenService">RequestTokenService</a></li><li><a
shape="rect"
href="#JAX-RSOAuth2-AuthorizationRequestService">AuthorizationRequestService</a></li><li><a
shape="rect"
href="#JAX-RSOAuth2-AccessTokenService">AccessTokenService</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-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><l
i><a shape="rect" href="#JAX-RSOAuth2-Clientsidesupport">Client-side
support</a></li><li><a shape="rect" href="#JAX-RSOAuth2-2legOAuthFlow">2-leg
OAuth Flow</a></li><ul><li><a shape="rect"
href="#JAX-RSOAuth2-ClientrequestsPreAuthorizedRequestToken">Client requests
PreAuthorized RequestToken</a></li><li><a shape="rect"
href="#JAX-RSOAuth2-SignaturewithConsumerKeyandSecret">Signature with Consumer
Key and Secret</a></li><li><a shape="rect"
href="#JAX-RSOAuth2-OnlyConsumerKeyandSecretinAuthorizationheader">Only
Consumer Key and Secret in Authorization header</a></li></ul><li><a
shape="rect" href="#JAX-RSOAuth2-OAuthWithoutaBrowser">OAuth Without a
Browser</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-Sharingthesameaccesspathbetweenendusersandconsumers
">Sharing the same access path between end users and consumers</a></li><li><a
shape="rect"
href="#JAX-RSOAuth2-Providingdifferentaccesspointstoendusersandconsumers">Providing
different access points to end users and consumers</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-DevelopingOAuth2Servers">Developing OAuth2
Servers</a></li><ul><li><a shape="rect"
href="#JAX-RSOAuth2-AuthorizationService">Authorization Service</a></li><li><a
shape="rect"
href="#JAX-RSOAuth2-AccessTokenService">AccessTokenService</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-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="r
ect" href="#JAX-RSOAuth2-2legOAuthFlow">2-leg OAuth Flow</a></li><ul><li><a
shape="rect"
href="#JAX-RSOAuth2-ClientrequestsPreAuthorizedRequestToken">Client requests
PreAuthorized RequestToken</a></li><li><a shape="rect"
href="#JAX-RSOAuth2-SignaturewithConsumerKeyandSecret">Signature with Consumer
Key and Secret</a></li><li><a shape="rect"
href="#JAX-RSOAuth2-OnlyConsumerKeyandSecretinAuthorizationheader">Only
Consumer Key and Secret in Authorization header</a></li></ul><li><a
shape="rect" href="#JAX-RSOAuth2-OAuthWithoutaBrowser">OAuth Without a
Browser</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-Sharingthesameaccesspathbetweenendusersandconsumers">Sharing
the same access path between end users and consumers</a></li><li><a
shape="rect" href="#JA
X-RSOAuth2-Providingdifferentaccesspointstoendusersandconsumers">Providing
different access points to end users and consumers</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>
<h1><a shape="rect" name="JAX-RSOAuth2-Introduction"></a>Introduction</h1>
@@ -170,7 +170,7 @@ Apache CXF -- JAX-RS OAuth2
</pre>
</div></div>
-<h1><a shape="rect" name="JAX-RSOAuth2-DevelopingOAuthServers"></a>Developing
OAuth Servers</h1>
+<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">
1. Authorizing request tokens by asking the end users to let consumers access
some of their resources and returning the<br clear="none">
@@ -185,98 +185,39 @@ Apache CXF -- JAX-RS OAuth2
<p>Writing your own OAuthDataProvider implementation is what is needed to get
the OAuth2 server up and running. In many cases all you need to do is to
persist or remove the Authorization Code Grant data, use one of the available
utility classes to create a new access token and also persist it or remove the
expired one, and finally convert the optional opaque scope values (if any are
supported) to a more view-able information.</p>
-<h2><a shape="rect"
name="JAX-RSOAuth2-RequestTokenService"></a>RequestTokenService </h2>
+<h2><a shape="rect" name="JAX-RSOAuth2-AuthorizationService"></a>Authorization
Service</h2>
-<p>The main responsibility of <a shape="rect" class="external-link"
href="http://svn.apache.org/repos/asf/cxf/trunk/rt/rs/security/oauth-parent/oauth/src/main/java/org/apache/cxf/rs/security/oauth/services/RequestTokenService.java";>RequestTokenService</a>
is to create a temporarily request token and return it back to the consumer.
It supports POST and GET requests and returns a form payload containing the new
request token and its secret.</p>
+<p>The main responsibility of OAuth2 Authorization Service is to present an
end user with a form asking the user to allow or deny the consumer accessing
some of the user resources. CXF offers <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/AuthorizationCodeGrantService.java";>AuthorizationCodeGrantService</a>
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/services/ImplicitGrantService.java";>ImplicitGrantService</a>
for accepting the redirection requests, challenging the end users with the
authorization forms, handling the end user decisions and returning the results
back to the clients. </p>
-<p>Here is an example request log:</p>
-<div class="code panel" style="border-width: 1px;"><div class="codeContent
panelContent">
-<pre class="code-xml">
-Address: http://localhost:8080/services/oauth/initiate
-Encoding: ISO-8859-1
-Http-Method: POST
-Content-Type: */*
-Headers: {
-Accept=[application/x-www-form-urlencoded],
-
-Content-Length=[0],
-
-Authorization=[OAuth oauth_callback=<span
class="code-quote">"http%3A%2F%2Flocalhost%3A8080%2Fservices%2Freservations%2Freserve%2Fcomplete"</span>,
- oauth_nonce=<span
class="code-quote">"e365fa02-772e-4e33-900d-00a766ccadf8"</span>,
- oauth_consumer_key=<span
class="code-quote">"123456789"</span>,
- oauth_signature_method=<span
class="code-quote">"HMAC-SHA1"</span>,
- oauth_timestamp=<span
class="code-quote">"1320748683"</span>,
- oauth_version=<span class="code-quote">"1.0"</span>,
- oauth_signature=<span
class="code-quote">"ztTQuqaJS7L6dNQwn%2Fqi1MdaqQQ%3D"</span>]
-}
-</pre>
-</div></div>
-
-<p>It is an empty POST request which includes an Authorization OAuth header.
The value of the header has a consumer key (obtained during the third-party
registration), callback URI pointing to where AuthorizationRequestService will
return an authorized token and a signature which was calculated using a
consumer key and secret pair as <a shape="rect" class="external-link"
href="http://tools.ietf.org/html/rfc5849#section-3.4.2";
rel="nofollow">described in the specification</a>.</p>
-
-<p>First RequestTokenService validates the signature and then it retrieves a
<a shape="rect" class="external-link"
href="http://svn.apache.org/repos/asf/cxf/trunk/rt/rs/security/oauth-parent/oauth/src/main/java/org/apache/cxf/rs/security/oauth/data/Client.java";>Client</a>
instance from OAuthDataProvider using a consumer key.</p>
-
-<p>Before asking OAuthDataProvider to generate a request token, it attempts to
validate a callback URI against a <a shape="rect" class="external-link"
href="http://svn.apache.org/repos/asf/cxf/trunk/rt/rs/security/oauth-parent/oauth/src/main/java/org/apache/cxf/rs/security/oauth/data/Client.java";>Client</a>'s
application URI.</p>
-
-<p>Finally it delegates to OAuthDataProvider to create a request token,
passing to it a populated <a shape="rect" class="external-link"
href="http://svn.apache.org/repos/asf/cxf/trunk/rt/rs/security/oauth-parent/oauth/src/main/java/org/apache/cxf/rs/security/oauth/data/RequestTokenRegistration.java";>RequestTokenRegistration</a>
bean. </p>
-
-<p>This bean references a Client instance, callback URI and a state. State is
something that a consumer may also include during the request token request
using a "state" parameter and will be returned back to the consumer alongside
the verifier after the request token has been authorized. For example, it may
represent a key that a consumer will use to retrieve the state of the request
that it was processing when requesting a token. For OAuth 1.0<br clear="none">
-consumers, the request token itself may represent a good enough key for such
purposes, but "state" may need to be used too and will become more useful for
OAuth 2.0.</p>
-
-<p>The bean also includes "issuedAt" and "lifetime" values which represent the
time a new token is about to be created and a configurable time in milliseconds
that this token will 'live' for. OAuthDataProvider will be free to reset those
values if needed before actually creating a request token.</p>
-
-<p>Finally, one more property that may be set on this bean instance: list of
scopes. List of scopes represents optional permissions that the consumer may
need to access the resources. These can be provided by an "x_oauth_scope"
("scope" in OAuth 2.0) request parameter, for example,</p>
-
-<div class="code panel" style="border-width: 1px;"><div class="codeContent
panelContent">
-<pre class="code-xml">
-Authorization=[OAuth ...,
- x_oauth_scope=<span class="code-quote">"readCalendar
updateCalendar"</span>]
-</pre>
-</div></div>
-
-<p>It's expected that each of the x_oauth_scope values such as "readCalendar"
and "updateCalendar" are translated into <a shape="rect" class="external-link"
href="http://svn.apache.org/repos/asf/cxf/trunk/rt/rs/security/oauth-parent/oauth/src/main/java/org/apache/cxf/rs/security/oauth/data/Permission.java";>OAuthPermission</a>s
during the creation of a new request token. If no x_oauth_scope parameter is
provided then the OAuth data provider will likely assign a default
OAuthPermission instance to the new token.</p>
-
-<p>After a new request token has been created by OAuthDataProvider,
RequestTokenService returns the token key and secret pair to the consumer:</p>
-
-<div class="code panel" style="border-width: 1px;"><div class="codeContent
panelContent">
-<pre class="code-xml">
-Response-Code: 200
-Content-Type: application/x-www-form-urlencoded
-Headers: {Date=[Tue, 08 Nov 2011 10:38:03 GMT]}
-Payload:
-oauth_callback_confirmed=true&oauth_token=6dfd5e52-236c-4939-8df8-a53212f7d2a2&oauth_token_secret=ca8273df-b9b0-43f9-9875-cfbb54ced550
-</pre>
-</div></div>
-
-<p>The consumer is now ready to redirect the current end user to <a
shape="rect" class="external-link"
href="http://svn.apache.org/repos/asf/cxf/trunk/rt/rs/security/oauth-parent/oauth/src/main/java/org/apache/cxf/rs/security/oauth/services/AuthorizationRequestService.java";>AuthorizationRequestService</a>.</p>
-
-<h2><a shape="rect"
name="JAX-RSOAuth2-AuthorizationRequestService"></a>AuthorizationRequestService</h2>
+<p>One of the differences between the AuthorizationCode and Implicit flows is
that in the latter case the grant is the actual access token which is returned
as the URI fragment value. The way the end user is asked to authorize the
client request is similar between the two flows. In this section we will assume
that the Authorization Code flow is being exercized.</p>
-<p>The main responsibility of AuthorizationRequestService is to present an end
user with a form asking the user to allow or deny the consumer accessing some
of the user resources. </p>
-
-<p>Remember that a third-party consumer redirects the current user to
AuthorizationRequestService, for example, here is how a redirection may
happen:</p>
+<p>A third-party client redirects the current user to
AuthorizationCodeGrantService, for example, here is how a redirection may
happen:</p>
<div class="code panel" style="border-width: 1px;"><div class="codeContent
panelContent">
<pre class="code-xml">
Response-Code: 303
-Headers:
{Location=[http://localhost:8080/services/social/authorize?oauth_token=f4415e16-56ea-465f-9df1-8bd769253a7d]}
+Headers:
{Location=[http://localhost:8080/services/social/authorize?client_id=123456789&scope=updateCalendar-7&response_type=code&redirect_uri=http%3A//localhost%3A8080/services/reservations/reserve/complete&state=1],
Date=[Thu, 12 Apr 2012 12:26:21 GMT], Content-Length=[0]}
+
</pre>
</div></div>
-<p>The consumer application asks the current user (the browser) to go to a new
address provided by the Location header and the follow-up request to
AuthorizationRequestService will look like this:</p>
+<p>The consumer application asks the current user (the browser) to go to a new
address provided by the Location header and the follow-up request to
AuthorizationCodeGrantService will look like this:</p>
<div class="code panel" style="border-width: 1px;"><div class="codeContent
panelContent">
<pre class="code-xml">
-Address:
http://localhost:8080/services/social/authorize?oauth_token=6dfd5e52-236c-4939-8df8-a53212f7d2a2
+Address:
http://localhost:8080/services/social/authorize?client_id=123456789&scope=updateCalendar-7&response_type=code&redirect_uri=http%3A//localhost%3A8080/services/reservations/reserve/complete&state=1
Http-Method: GET
-Content-Type:
Headers: {
-Accept=[text/html,application/xhtml+xml,application/xml;q=0.9,*/*;q=0.8],
-Referer=[http://localhost:8080/services/forms/reservation.jsp],
+Accept=[text/html,application/xhtml+xml,application/xml;q=0.9,*/*;q=0.8],
+Authorization=[Basic YmFycnlAc29jaWFsLmNvbToxMjM0],
+Cookie=[JSESSIONID=suj2wyl54c4g],
+Referer=[http://localhost:8080/services/forms/reservation.jsp]
...
}
</pre>
</div></div>
+<p>Note that the end user needs to authenticate. The Request URI includes the
client_id, custom scope value, response_type set to 'code', the current request
state and the redirect uri. Note the scope is optional - the Authorization
Service will usually allocate a default scope; however even if the client does
include an additional custom scope the end user may still not approve it. The
redirect uri is also optional, assuming one or more ones redirect URIs have
been provided at the client registration time.</p>
+
<p>First, AuthorizationRequestService will retrieve <a shape="rect"
class="external-link"
href="http://svn.apache.org/repos/asf/cxf/trunk/rt/rs/security/oauth-parent/oauth/src/main/java/org/apache/cxf/rs/security/oauth/data/RequestToken.java";>RequestToken</a>
(which extends the base <a shape="rect" class="external-link"
href="http://svn.apache.org/repos/asf/cxf/trunk/rt/rs/security/oauth-parent/oauth/src/main/java/org/apache/cxf/rs/security/oauth/data/Token.java";>Token</a>
class) from OAuthDataProvider using the value provided by the "oauth_token"
query parameter. </p>
<p>Next it uses this token (which also links to Client) to populate an
instance of <a shape="rect" class="external-link"
href="http://svn.apache.org/repos/asf/cxf/trunk/rt/rs/security/oauth-parent/oauth/src/main/java/org/apache/cxf/rs/security/oauth/data/OAuthAuthorizationData.java";>OAuthAuthorizationData</a>
bean and returns it. OAuthAuthorizationData contains application name and URI
properties, optional list of <a shape="rect" class="external-link"
href="http://svn.apache.org/repos/asf/cxf/trunk/rt/rs/security/oauth-parent/oauth/src/main/java/org/apache/cxf/rs/security/oauth/data/Permission.java";>Permission</a>s
and URIs. </p>
