Modified: websites/production/cxf/content/docs/jax-rs-oauth.html ============================================================================== --- websites/production/cxf/content/docs/jax-rs-oauth.html (original) +++ websites/production/cxf/content/docs/jax-rs-oauth.html Mon Jun 24 17:10:51 2013 @@ -25,6 +25,18 @@ <meta http-equiv="Content-type" content="text/html;charset=UTF-8"> <meta name="keywords" content="business integration, EAI, SOA, Service Oriented Architecture, web services, SOAP, JBI, JMS, WSDL, XML, EDI, Electronic Data Interchange, standards support, integration standards, application integration, middleware, software, solutions, services, CXF, open source"> <meta name="description" content="Apache CXF, Services Framework - JAX-RS OAuth"> + + <link href='http://cxf.apache.org/resources/highlighter/styles/shCore.css' rel='stylesheet' type='text/css' /> + <link href='http://cxf.apache.org/resources/highlighter/styles/shThemeCXF.css' rel='stylesheet' type='text/css' /> + <script src='http://cxf.apache.org/resources/highlighter/scripts/shCore.js' type='text/javascript'></script> + <script src='http://cxf.apache.org/resources/highlighter/scripts/shBrushJava.js' type='text/javascript'></script> + <script src='http://cxf.apache.org/resources/highlighter/scripts/shBrushXml.js' type='text/javascript'></script> + + <script type="text/javascript"> + SyntaxHighlighter.defaults['toolbar'] = false; + SyntaxHighlighter.all(); + </script> + <title> Apache CXF -- JAX-RS OAuth </title> @@ -42,19 +54,15 @@ Apache CXF -- JAX-RS OAuth <td id="cell-1-0"> </td> <td id="cell-1-1"> </td> <td id="cell-1-2"> - <div style="padding: 5px;"> - <div id="banner"> - <!-- Banner --> -<div id="banner-content"> + <!-- Banner --> +<div class="banner" id="banner"><p> <table border="0" cellpadding="0" cellspacing="0" width="100%"><tr><td align="left" colspan="1" nowrap> <a shape="rect" href="http://cxf.apache.org/"; title="Apache CXF"><span style="font-weight: bold; font-size: 170%; color: white">Apache CXF</span></a> </td><td align="right" colspan="1" nowrap> <a shape="rect" href="http://www.apache.org/"; title="The Apache Sofware Foundation"><img border="0" alt="ASF Logo" src="http://cxf.apache.org/images/asf-logo.png";></a> </td></tr></table> -</div> - <!-- Banner --> - </div> - </div> +</p></div> + <!-- Banner --> <div id="top-menu"> <table border="0" cellpadding="1" cellspacing="0" width="100%"> <tr> @@ -94,7 +102,7 @@ Apache CXF -- JAX-RS OAuth <hr> -<ul class="alternate" type="square"><li>Search +<ul class="alternate" type="square"><li>Search<br clear="none"> <form enctype="application/x-www-form-urlencoded" method="get" id="cse-search-box" action="http://www.google.com/cse";> <div> @@ -166,13 +174,13 @@ Apache CXF -- JAX-RS OAuth <h1><a shape="rect" name="JAX-RSOAuth-Mavendependencies"></a>Maven dependencies</h1> <div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent"> -<pre class="code-xml"> -<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-oauth<span class="code-tag"></artifactId></span> - <span class="code-tag"><version></span>2.5.0<span class="code-tag"></version></span> -<span class="code-tag"></dependency></span> -</pre> +<script class="theme: Default; brush: xml; gutter: false" type="syntaxhighlighter"><![CDATA[ +<dependency> + <groupId>org.apache.cxf</groupId> + <artifactId>cxf-rt-rs-security-oauth</artifactId> + <version>2.5.0</version> +</dependency> +]]></script> </div></div> <h1><a shape="rect" name="JAX-RSOAuth-DevelopingOAuth1.0Servers"></a>Developing OAuth 1.0 Servers</h1> @@ -192,7 +200,7 @@ Apache CXF -- JAX-RS OAuth <p>Here is an example request log:</p> <div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent"> -<pre class="code-xml"> +<script class="theme: Default; brush: xml; gutter: false" type="syntaxhighlighter"><![CDATA[ Address: http://localhost:8080/services/oauth/initiate Encoding: ISO-8859-1 Http-Method: POST @@ -202,15 +210,15 @@ Accept=[application/x-www-form-urlencode 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>] +Authorization=[OAuth oauth_callback="http%3A%2F%2Flocalhost%3A8080%2Fservices%2Freservations%2Freserve%2Fcomplete", + oauth_nonce="e365fa02-772e-4e33-900d-00a766ccadf8", + oauth_consumer_key="123456789", + oauth_signature_method="HMAC-SHA1", + oauth_timestamp="1320748683", + oauth_version="1.0", + oauth_signature="ztTQuqaJS7L6dNQwn%2Fqi1MdaqQQ%3D"] } -</pre> +]]></script> </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> @@ -229,10 +237,10 @@ consumers, the request token itself may <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"> +<script class="theme: Default; brush: xml; gutter: false" type="syntaxhighlighter"><![CDATA[ Authorization=[OAuth ..., - x_oauth_scope=<span class="code-quote">"readCalendar updateCalendar"</span>] -</pre> + x_oauth_scope="readCalendar updateCalendar"] +]]></script> </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> @@ -240,13 +248,13 @@ Authorization=[OAuth ..., <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"> +<script class="theme: Default; brush: xml; gutter: false" type="syntaxhighlighter"><![CDATA[ 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> +]]></script> </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> @@ -257,16 +265,16 @@ oauth_callback_confirmed=true&oauth_ <p>Remember that a third-party consumer redirects the current user to AuthorizationRequestService, 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"> +<script class="theme: Default; brush: xml; gutter: false" type="syntaxhighlighter"><![CDATA[ Response-Code: 303 Headers: {Location=[http://localhost:8080/services/social/authorize?oauth_token=f4415e16-56ea-465f-9df1-8bd769253a7d]} -</pre> +]]></script> </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> <div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent"> -<pre class="code-xml"> +<script class="theme: Default; brush: xml; gutter: false" type="syntaxhighlighter"><![CDATA[ Address: http://localhost:8080/services/social/authorize?oauth_token=6dfd5e52-236c-4939-8df8-a53212f7d2a2 Http-Method: GET Content-Type: @@ -275,7 +283,7 @@ Accept=[text/html,application/xhtml+xml, Referer=[http://localhost:8080/services/forms/reservation.jsp], ... } -</pre> +]]></script> </div></div> <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> @@ -292,15 +300,15 @@ Referer=[http://localhost:8080/services/ <p>Assuming RequestDispatcherProvider is used, the following example log shows the initial response from AuthorizationRequestService:</p> <div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent"> -<pre class="code-xml"> +<script class="theme: Default; brush: xml; gutter: false" type="syntaxhighlighter"><![CDATA[ 08-Nov-2011 13:32:40 org.apache.cxf.jaxrs.provider.RequestDispatcherProvider logRedirection -INFO: Setting an instance of <span class="code-quote">"org.apache.cxf.rs.security.oauth.data.OAuthAuthorizationData"</span> as HttpServletRequest attribute <span class="code-quote">"data"</span> and redirecting the response to <span class="code-quote">"/forms/oauthAuthorize.jsp"</span>. +INFO: Setting an instance of "org.apache.cxf.rs.security.oauth.data.OAuthAuthorizationData" as HttpServletRequest attribute "data" and redirecting the response to "/forms/oauthAuthorize.jsp". 08-Nov-2011 13:32:40 org.apache.cxf.interceptor.LoggingOutInterceptor --------------------------- Response-Code: 200 Content-Type: text/html -</pre> +]]></script> </div></div> <p>Note that a "/forms/oauthAuthorize.jsp" view handler will create an HTML view - this is a custom JSP handler and whatever HTML view is required can be created there, using the OAuthAuthorizationData bean for building the view. Most likely you will want to present a form asking the user to allow or deny the consumer accessing some of this user's resources. If OAuthAuthorizationData has a list of Permissions set then addig the information about the permissions is needed, same for a list of URIs.</p> @@ -308,7 +316,7 @@ Content-Type: text/html <p>Next the user makes a decision and selects a button allowing or denying the consumer accessing the resources. AuthorizationRequestService does not need to know how a user has been asked to make the decision, but it expects to receive a form-based submission containing the following 3 parameters, named "session_authenticity_token" and "oauth_token" with values matching those of OAuthAuthorizationData's "authenticityToken" and "oauthToken" properties, and "oAuthDecision" with either "allow" or "deny" values: </p> <div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent"> -<pre class="code-xml"> +<script class="theme: Default; brush: xml; gutter: false" type="syntaxhighlighter"><![CDATA[ Address: http://localhost:8080/services/social/authorize/decision Http-Method: POST Content-Type: application/x-www-form-urlencoded @@ -320,34 +328,34 @@ User-Agent=[Mozilla/5.0 (X11; Linux x86_ -------------------------------------- 09-Nov-2011 16:41:58 org.apache.cxf.jaxrs.utils.FormUtils logRequestParametersIfNeeded INFO: session_authenticity_token=e52b5033-9bf5-4b34-9d3a-39a7d5b7e686&oauthDecision=allow&oauth_token=6dfd5e52-236c-4939-8df8-a53212f7d2a2 -</pre> +]]></script> </div></div> <p>AuthorizationRequestService will use a session_authenticity_token to validate that the session is valid and will process the user decision next.<br clear="none"> If it is set to "allow" then it will ask OAuthDataProvider to generate an authorization key (verifier) and return this verifier alongside with the request token key and the state if any by redirecting the current user back to the callback URI provided during the request token request:</p> <div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent"> -<pre class="code-xml"> +<script class="theme: Default; brush: xml; gutter: false" type="syntaxhighlighter"><![CDATA[ Response-Code: 303 Headers: { Location=[http://localhost:8080/services/reservations/reserve/complete?oauth_token=6dfd5e52-236c-4939-8df8-a53212f7d2a2&oauth_verifier=00bd8fa7-4233-42a2-8957-0a0a22c684ba] } -</pre> +]]></script> </div></div> <p>which leads to a browser redirecting the user:</p> <div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent"> -<pre class="code-java"> -Address: http:<span class="code-comment">//localhost:8080/services/reservations/reserve/complete?oauth_token=6dfd5e52-236c-4939-8df8-a53212f7d2a2&oauth_verifier=00bd8fa7-4233-42a2-8957-0a0a22c684ba -</span>Http-Method: GET +<script class="theme: Default; brush: java; gutter: false" type="syntaxhighlighter"><![CDATA[ +Address: http://localhost:8080/services/reservations/reserve/complete?oauth_token=6dfd5e52-236c-4939-8df8-a53212f7d2a2&oauth_verifier=00bd8fa7-4233-42a2-8957-0a0a22c684ba +Http-Method: GET Content-Type: Headers: { Authorization=[Basic YmFycnlAc29jaWFsLmNvbToxMjM0], Cookie=[JSESSIONID=eovucah9rwqp], -Referer=[http:<span class="code-comment">//localhost:8080/services/social/authorize?oauth_token=6dfd5e52-236c-4939-8df8-a53212f7d2a2], -</span>User-Agent=[Mozilla/5.0 (X11; Linux x86_64; rv:2.0) Gecko/20100101 Firefox/4.0]} -</pre> +Referer=[http://localhost:8080/services/social/authorize?oauth_token=6dfd5e52-236c-4939-8df8-a53212f7d2a2], +User-Agent=[Mozilla/5.0 (X11; Linux x86_64; rv:2.0) Gecko/20100101 Firefox/4.0]} +]]></script> </div></div> <p>If a user decision was set to "deny" then no verifier will be sent back to the consumer.</p> @@ -360,7 +368,7 @@ Referer=[http:<span class="code-comment" requested: </p> <div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent"> -<pre class="code-xml"> +<script class="theme: Default; brush: xml; gutter: false" type="syntaxhighlighter"><![CDATA[ Address: http://localhost:8080/services/oauth/initiate Encoding: ISO-8859-1 Http-Method: POST @@ -370,15 +378,15 @@ Accept=[application/x-www-form-urlencode Content-Length=[0], -Authorization=[OAuth oauth_callback=<span class="code-quote">"oob"</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>] +Authorization=[OAuth oauth_callback="oob", + oauth_nonce="e365fa02-772e-4e33-900d-00a766ccadf8", + oauth_consumer_key="123456789", + oauth_signature_method="HMAC-SHA1", + oauth_timestamp="1320748683", + oauth_version="1.0", + oauth_signature="ztTQuqaJS7L6dNQwn%2Fqi1MdaqQQ%3D"] } -</pre> +]]></script> </div></div> <p>RequestTokenService will only accept the "oob" value if a client callbackURI property has been set to "oob" during the client application registration process. Specifically, RequestTokenService will expect that 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> bean will have its callbackURI property being set to "oob".</p> @@ -392,21 +400,21 @@ Authorization=[OAuth oauth_callback=<spa Here is an example request log:</p> <div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent"> -<pre class="code-xml"> +<script class="theme: Default; brush: xml; gutter: false" type="syntaxhighlighter"><![CDATA[ Address: http://localhost:8080/services/oauth/token Http-Method: POST Headers: { Accept=[application/x-www-form-urlencoded], -Authorization=[OAuth oauth_signature_method=<span class="code-quote">"HMAC-SHA1"</span>, - oauth_consumer_key=<span class="code-quote">"123456789"</span>, - oauth_token=<span class="code-quote">"6dfd5e52-236c-4939-8df8-a53212f7d2a2"</span>, - oauth_verifier=<span class="code-quote">"00bd8fa7-4233-42a2-8957-0a0a22c684ba"</span>, - oauth_timestamp=<span class="code-quote">"1320760259"</span>, - oauth_nonce=<span class="code-quote">"16237669362301"</span>, - oauth_version=<span class="code-quote">"1.0"</span>, - oauth_signature=<span class="code-quote">"dU%2BhXPNFfFpX2sC74IOxzTjdVrY%3D"</span>] +Authorization=[OAuth oauth_signature_method="HMAC-SHA1", + oauth_consumer_key="123456789", + oauth_token="6dfd5e52-236c-4939-8df8-a53212f7d2a2", + oauth_verifier="00bd8fa7-4233-42a2-8957-0a0a22c684ba", + oauth_timestamp="1320760259", + oauth_nonce="16237669362301", + oauth_version="1.0", + oauth_signature="dU%2BhXPNFfFpX2sC74IOxzTjdVrY%3D"] } -</pre> +]]></script> </div></div> <p>This request is very similar to a temporarily token request. Note that the request token key is also included and this token key and its secret pair, as well as the consumer key and secret pair are used to calculate the signature.</p> @@ -417,28 +425,28 @@ Authorization=[OAuth oauth_signature_met <p>Next it asks the data provider to create a new <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/AccessToken.java";>AccessToken</a> based on this RequestToken. The resulting access token key and secret pair is returned back to a consumer:</p> <div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent"> -<pre class="code-xml"> +<script class="theme: Default; brush: xml; gutter: false" type="syntaxhighlighter"><![CDATA[ Response-Code: 200 Content-Type: application/x-www-form-urlencoded Headers: {Date=[Tue, 08 Nov 2011 13:50:59 GMT]} Payload: oauth_token=abc15aca-2073-4bde-b1be-1a02dc7ccafe&oauth_token_secret=859dfe9e-ca4c-4b36-9e60-044434ab636c -</pre> +]]></script> </div></div> <p>The consumer will use this access token to access the current user's resources in order to complete the original user's request, for example, the request to access a user's calendar may look like this:</p> <div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent"> -<pre class="code-xml"> +<script class="theme: Default; brush: xml; gutter: false" type="syntaxhighlighter"><![CDATA[ Address: http://localhost:8080/services/user/calendar Http-Method: GET Headers: { Accept=[application/XML], -Authorization=[OAuth oauth_signature_method=<span class="code-quote">"HMAC-SHA1"</span>, - oauth_consumer_key=<span class="code-quote">"123456789"</span>, - oauth_token=<span class="code-quote">"abc15aca-2073-4bde-b1be-1a02dc7ccafe"</span>, - oauth_version=<span class="code-quote">"1.0"</span>, - oauth_signature=<span class="code-quote">"dU%2BhXPNFfFpX2sC74IOxzTjdVrY%3D"</span>] +Authorization=[OAuth oauth_signature_method="HMAC-SHA1", + oauth_consumer_key="123456789", + oauth_token="abc15aca-2073-4bde-b1be-1a02dc7ccafe", + oauth_version="1.0", + oauth_signature="dU%2BhXPNFfFpX2sC74IOxzTjdVrY%3D"] } -</pre> +]]></script> </div></div> <p>Note that the access token is set and the access token key and secret pair, as well as the consumer key and secret pair are used to create a signature.</p> @@ -452,14 +460,14 @@ Authorization=[OAuth oauth_signature_met <p>Note that OAuthDataProvider supports retrieving <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> instances but it has no methods for creating or removing Clients. The reason for it is that the process of registering third-party consumers is very specific to a particular OAuth application, so CXF does not offer a registration support service and hence OAuthDataProvider has no Client create/update methods. You will likely need to do something like this:</p> <div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent"> -<pre class="code-java"> -<span class="code-keyword">public</span> class CustomOAuthProvider <span class="code-keyword">implements</span> OAuthDataProvider { - <span class="code-keyword">public</span> Client registerClient(<span class="code-object">String</span> applicationName, <span class="code-object">String</span> applicationURI, ...) {} - <span class="code-keyword">public</span> void removeClient(<span class="code-object">String</span> cliendId) {} - <span class="code-comment">// etc -</span> <span class="code-comment">// OAuthDataProvider methods -</span>} -</pre> +<script class="theme: Default; brush: java; gutter: false" type="syntaxhighlighter"><![CDATA[ +public class CustomOAuthProvider implements OAuthDataProvider { + public Client registerClient(String applicationName, String applicationURI, ...) {} + public void removeClient(String cliendId) {} + // etc + // OAuthDataProvider methods +} +]]></script> </div></div> <p>CustomOAuthProvider will also remove all tokens associated with a given Client in removeClient(String cliendId).</p> @@ -467,21 +475,21 @@ Authorization=[OAuth oauth_signature_met <p>When creating RequestToken or AccessToken tokens as well as authorization keys, OAuthDataProvider will need to create unique identifiers.<br clear="none"> The way it's done is application specific and custom implementations may also use a utility <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/provider/MD5SequenceGenerator.java";>MD5SequenceGenerator</a> shipped with CXF, for example:</p> <div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent"> -<pre class="code-java"> -<span class="code-keyword">public</span> <span class="code-object">String</span> setRequestTokenVerifier(RequestToken requestToken) <span class="code-keyword">throws</span> OAuthServiceException { +<script class="theme: Default; brush: java; gutter: false" type="syntaxhighlighter"><![CDATA[ +public String setRequestTokenVerifier(RequestToken requestToken) throws OAuthServiceException { requestToken.setVerifier(generateSequence()); - <span class="code-keyword">return</span> requestToken.getVerifier(); + return requestToken.getVerifier(); } -<span class="code-keyword">private</span> <span class="code-object">String</span> generateSequence() <span class="code-keyword">throws</span> OAuthServiceException { - <span class="code-keyword">try</span> { - <span class="code-keyword">return</span> tokenGenerator.generate(UUID.randomUUID().toString().getBytes(<span class="code-quote">"UTF-8"</span>)); - } <span class="code-keyword">catch</span> (Exception e) { - <span class="code-keyword">throw</span> <span class="code-keyword">new</span> OAuthServiceException(<span class="code-quote">"Unable to generate the key"</span>, e.getCause()); +private String generateSequence() throws OAuthServiceException { + try { + return tokenGenerator.generate(UUID.randomUUID().toString().getBytes("UTF-8")); + } catch (Exception e) { + throw new OAuthServiceException("Unable to generate the key", e.getCause()); } } -</pre> +]]></script> </div></div> <p>Generating tokens/keys and persisting them effectively is what OAuthDataProvider all about.<br clear="none"> @@ -495,25 +503,25 @@ Note that CXF will check that Request an Most likely, you'd want to deploy RequestTokenService and AccessTokenService as two root resources inside a single JAX-RS endpoint (or have one RequestTokenService and one AccessTokenService endpoint), for example:</p> <div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent"> -<pre class="code-xml"> -<span class="code-tag"><span class="code-comment"><!-- implements OAuthDataProvider --></span></span> -<span class="code-tag"><bean id=<span class="code-quote">"oauthProvider"</span> class=<span class="code-quote">"oauth.manager.OAuthManager"</span>/></span> - -<span class="code-tag"><bean id=<span class="code-quote">"requestTokenService"</span> class=<span class="code-quote">"org.apache.cxf.rs.security.oauth.services.RequestTokenService"</span>></span> - <span class="code-tag"><property name=<span class="code-quote">"dataProvider"</span> ref=<span class="code-quote">"oauthProvider"</span>/></span> -<span class="code-tag"></bean></span> +<script class="theme: Default; brush: xml; gutter: false" type="syntaxhighlighter"><![CDATA[ +<!-- implements OAuthDataProvider --> +<bean id="oauthProvider" class="oauth.manager.OAuthManager"/> + +<bean id="requestTokenService" class="org.apache.cxf.rs.security.oauth.services.RequestTokenService"> + <property name="dataProvider" ref="oauthProvider"/> +</bean> -<span class="code-tag"><bean id=<span class="code-quote">"accessTokenService"</span> class=<span class="code-quote">"org.apache.cxf.rs.security.oauth.services.AccessTokenService"</span>></span> - <span class="code-tag"><property name=<span class="code-quote">"dataProvider"</span> ref=<span class="code-quote">"oauthProvider"</span>/></span> -<span class="code-tag"></bean></span> - -<span class="code-tag"><jaxrs:server id=<span class="code-quote">"oauthServer"</span> address=<span class="code-quote">"/oauth"</span>></span> - <span class="code-tag"><jaxrs:serviceBeans></span> - <span class="code-tag"><ref bean=<span class="code-quote">"requestTokenService"</span>/></span> - <span class="code-tag"><ref bean=<span class="code-quote">"accessTokenService"</span>/></span> - <span class="code-tag"></jaxrs:serviceBeans></span> -<span class="code-tag"></jaxrs:server></span> -</pre> +<bean id="accessTokenService" class="org.apache.cxf.rs.security.oauth.services.AccessTokenService"> + <property name="dataProvider" ref="oauthProvider"/> +</bean> + +<jaxrs:server id="oauthServer" address="/oauth"> + <jaxrs:serviceBeans> + <ref bean="requestTokenService"/> + <ref bean="accessTokenService"/> + </jaxrs:serviceBeans> +</jaxrs:server> +]]></script> </div></div> <p>RequestTokenService listens on a relative "/initiate" path, AccessTokenService - on "/token". Giving the that jaxrs:server/@adress is "/oauth" and assuming a context name is "/services", the absolute address of RequestTokenService would be something like "http://localhost:8080/services/oauth/initiate"; and that of AccessTokenService - "http://localhost:8080/services/oauth/token";. </p> @@ -521,22 +529,22 @@ Most likely, you'd want to deploy Reques <p>AuthorizationRequestService is better to put where the main application endpoint is. It can be put alongside RequestTokenService and AccessTokenService - but the problem is that the end user is expected to authenticate itself with the resource server after it has been redirected by a third-party consumer to AuthorizationRequestService. That would make it more complex for the OAuth server endpoint to manage both OAuth (third-party consumer) and the regular user authentication - that can be done, see more on it below in the Design considerations section, but the simpler option is to simply get AuthorizationRequestService under the control of the security filter enforcing the end user authentication:</p> <div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent"> -<pre class="code-java"> -<bean id=<span class="code-quote">"authorizationService"</span> class=<span class="code-quote">"org.apache.cxf.rs.security.oauth.services.AuthorizationRequestService"</span>> - <property name=<span class="code-quote">"dataProvider"</span> ref=<span class="code-quote">"oauthProvider"</span>/> +<script class="theme: Default; brush: java; gutter: false" type="syntaxhighlighter"><![CDATA[ +<bean id="authorizationService" class="org.apache.cxf.rs.security.oauth.services.AuthorizationRequestService"> + <property name="dataProvider" ref="oauthProvider"/> </bean> -<bean id=<span class="code-quote">"myApp"</span> class=<span class="code-quote">"org.myapp.MyApp"</span>> - <property name=<span class="code-quote">"dataProvider"</span> ref=<span class="code-quote">"oauthProvider"</span>/> +<bean id="myApp" class="org.myapp.MyApp"> + <property name="dataProvider" ref="oauthProvider"/> </bean> -<jaxrs:server id=<span class="code-quote">"oauthServer"</span> address=<span class="code-quote">"/myapp"</span>> +<jaxrs:server id="oauthServer" address="/myapp"> <jaxrs:serviceBeans> - <ref bean=<span class="code-quote">"myApp"</span>/> - <ref bean=<span class="code-quote">"authorizationService"</span>/> + <ref bean="myApp"/> + <ref bean="authorizationService"/> </jaxrs:serviceBeans> </jaxrs:server> -</pre> +]]></script> </div></div> <p>AuthorizationRequestService listens on a relative "/authorize" path so in this case its absolute address will be something like "http://localhost:8080/services/myapp/authorize";. This address and those of RequestTokenService and AccessTokenService will be used by third-party consumers.</p> @@ -548,18 +556,18 @@ Most likely, you'd want to deploy Reques <p>When checking a request like this:</p> <div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent"> -<pre class="code-xml"> +<script class="theme: Default; brush: xml; gutter: false" type="syntaxhighlighter"><![CDATA[ Address: http://localhost:8080/services/user/calendar Http-Method: GET Headers: { Accept=[application/XML], -Authorization=[OAuth oauth_signature_method=<span class="code-quote">"HMAC-SHA1"</span>, - oauth_consumer_key=<span class="code-quote">"123456789"</span>, - oauth_token=<span class="code-quote">"abc15aca-2073-4bde-b1be-1a02dc7ccafe"</span>, - oauth_version=<span class="code-quote">"1.0"</span>, - oauth_signature=<span class="code-quote">"dU%2BhXPNFfFpX2sC74IOxzTjdVrY%3D"</span>] +Authorization=[OAuth oauth_signature_method="HMAC-SHA1", + oauth_consumer_key="123456789", + oauth_token="abc15aca-2073-4bde-b1be-1a02dc7ccafe", + oauth_version="1.0", + oauth_signature="dU%2BhXPNFfFpX2sC74IOxzTjdVrY%3D"] } -</pre> +]]></script> </div></div> <p>the filter will do the following:</p> @@ -589,29 +597,29 @@ how one can access a user login name tha The following code shows one way of how this can be done starting from CXF 2.5.1:</p> <div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent"> -<pre class="code-java"> -@Path(<span class="code-quote">"/userResource"</span>) -<span class="code-keyword">public</span> class ThirdPartyAccessService { +<script class="theme: Default; brush: java; gutter: false" type="syntaxhighlighter"><![CDATA[ +@Path("/userResource") +public class ThirdPartyAccessService { @Context - <span class="code-keyword">private</span> MessageContext mc; + private MessageContext mc; @GET - <span class="code-keyword">public</span> UserResource getUserResource() { + public UserResource getUserResource() { OAuthContext oauth = mc.getContent(OAuthContext.class); - <span class="code-keyword">if</span> (oauth == <span class="code-keyword">null</span> || oauth.getSubject() == <span class="code-keyword">null</span> || oauth.getSubject().getLogin() == <span class="code-keyword">null</span>) { - <span class="code-keyword">throw</span> <span class="code-keyword">new</span> WebApplicationException(403); + if (oauth == null || oauth.getSubject() == null || oauth.getSubject().getLogin() == null) { + throw new WebApplicationException(403); } - <span class="code-object">String</span> userName = oauth.getSubject().getLogin(); - <span class="code-keyword">return</span> findUserResource(userName) + String userName = oauth.getSubject().getLogin(); + return findUserResource(userName) } - <span class="code-keyword">private</span> UserResource findUserResource(<span class="code-object">String</span> userName) { - <span class="code-comment">// find and <span class="code-keyword">return</span> UserResource -</span> } + private UserResource findUserResource(String userName) { + // find and return UserResource + } } -</pre> +]]></script> </div></div> <p>The above shows a fragment of the JAX-RS service managing the access to user resources from authorized 3rd-party clients (see the Design Considerations section for more information).</p> @@ -629,40 +637,40 @@ for this to happen.</p> <p>For example, the following custom code can be used by the third-party application:</p> <div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent"> -<pre class="code-java"> -<span class="code-keyword">public</span> class OAuthClientManager { +<script class="theme: Default; brush: java; gutter: false" type="syntaxhighlighter"><![CDATA[ +public class OAuthClientManager { - <span class="code-keyword">private</span> WebClient accessTokenService; - <span class="code-keyword">private</span> WebClient requestTokenService; - <span class="code-keyword">private</span> <span class="code-object">String</span> authorizationServiceURI; + private WebClient accessTokenService; + private WebClient requestTokenService; + private String authorizationServiceURI; - <span class="code-comment">// inject properties... -</span> - <span class="code-keyword">public</span> URI getAuthorizationServiceURI(<span class="code-object">String</span> token) { - <span class="code-keyword">return</span> OAuthClientUtils.getAuthorizationURI(authorizationServiceURI, token); + // inject properties... + + public URI getAuthorizationServiceURI(String token) { + return OAuthClientUtils.getAuthorizationURI(authorizationServiceURI, token); } - <span class="code-keyword">public</span> Token getRequestToken(URI callback) { - <span class="code-keyword">try</span> { - <span class="code-keyword">return</span> OAuthClientUtils.getRequestToken(requestTokenService, consumer, callback, <span class="code-keyword">null</span>); - } <span class="code-keyword">catch</span> (OAuthServiceException ex) { - <span class="code-keyword">return</span> <span class="code-keyword">null</span>; + public Token getRequestToken(URI callback) { + try { + return OAuthClientUtils.getRequestToken(requestTokenService, consumer, callback, null); + } catch (OAuthServiceException ex) { + return null; } } - <span class="code-keyword">public</span> Token getAccessToken(Token requestToken, <span class="code-object">String</span> verifier) { - <span class="code-keyword">try</span> { - <span class="code-keyword">return</span> OAuthClientUtils.getAccessToken(accessTokenService, consumer, requestToken, verifier); - } <span class="code-keyword">catch</span> (OAuthServiceException ex) { - <span class="code-keyword">return</span> <span class="code-keyword">null</span>; + public Token getAccessToken(Token requestToken, String verifier) { + try { + return OAuthClientUtils.getAccessToken(accessTokenService, consumer, requestToken, verifier); + } catch (OAuthServiceException ex) { + return null; } } - <span class="code-keyword">public</span> <span class="code-object">String</span> createAuthorizationHeader(Token token, <span class="code-object">String</span> method, <span class="code-object">String</span> requestURI) { - <span class="code-keyword">return</span> OAuthClientUtils.createAuthorizationHeader(consumer, token, method, requestURI); + public String createAuthorizationHeader(Token token, String method, String requestURI) { + return OAuthClientUtils.createAuthorizationHeader(consumer, token, method, requestURI); } } -</pre> +]]></script> </div></div> <p>The reason such a simple wrapper can be introduced is to minimize the exposure to OAuth of the main application code to the bare minimum, this is why<br clear="none"> @@ -690,27 +698,27 @@ For this to work RequestToken needs to b <h2><a shape="rect" name="JAX-RSOAuth-OnlyConsumerKeyandSecretinAuthorizationheader"></a>Only Consumer Key and Secret in Authorization header</h2> <div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent"> -<pre class="code-xml"> +<script class="theme: Default; brush: xml; gutter: false" type="syntaxhighlighter"><![CDATA[ Address: http://localhost:8080/services/user/calendar Http-Method: GET Headers: { Accept=[application/XML], -Authorization=[OAuth oauth_consumer_key=<span class="code-quote">"123456789"</span>,oauth_consumer_secret=<span class="code-quote">"987654321"</span>] +Authorization=[OAuth oauth_consumer_key="123456789",oauth_consumer_secret="987654321"] } -</pre> +]]></script> </div></div> <p>Alternatively, the consumer key and secret can be joined by a ":" character and encoded with the Base64 encoding:</p> <div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent"> -<pre class="code-xml"> +<script class="theme: Default; brush: xml; gutter: false" type="syntaxhighlighter"><![CDATA[ Address: http://localhost:8080/services/user/calendar Http-Method: GET Headers: { Accept=[application/XML], Authorization=[Basic base64EncodedValue] } -</pre> +]]></script> </div></div> <p>In this mode the Client is expected to reference a pre-authorized AccessToken. OAuth filters validate this token as usual. </p> @@ -727,18 +735,18 @@ However, supporting other types of end u <p>CXF OAuth 1.0 services will report only HTTP status code in case of various OAuth-related errors to minimize the information about the actual cause of the failure and will log the details locally. If providing the extra error information can help with debugging 3rd-party applications or if such application can indeed recover from the failures based on such details, then setting a contextual "report.failure.details" property to "true" will get the error messages available in the response body. Some OAuth1.0 implementers have chosen to return a custom "oauth_problem" HTTP header instead - this option can be supported by additionally setting a contextual "report.failure.details.as.header" property to "true", for example:</p> <div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent"> -<pre class="code-xml"> -<span class="code-tag"><jaxrs:server id=<span class="code-quote">"oauthServer"</span> address=<span class="code-quote">"/initiate"</span>></span> - <span class="code-tag"><jaxrs:serviceBeans></span> - <span class="code-tag"><bean class=<span class="code-quote">"org.apache.cxf.rs.security.oauth.services.RequestTokenService"</span>/></span> - <span class="code-tag"></jaxrs:serviceBeans></span> - <span class="code-tag"><jaxrs:properties></span> - <span class="code-tag"><entry key=<span class="code-quote">"report.failure.details"</span> value=<span class="code-quote">"true"</span>/></span> - <span class="code-tag"><entry key=<span class="code-quote">"report.failure.details.as.header"</span> value=<span class="code-quote">"true"</span>/></span> - <span class="code-tag"></jaxrs:properties></span> -<span class="code-tag"></jaxrs:server></span> +<script class="theme: Default; brush: xml; gutter: false" type="syntaxhighlighter"><![CDATA[ +<jaxrs:server id="oauthServer" address="/initiate"> + <jaxrs:serviceBeans> + <bean class="org.apache.cxf.rs.security.oauth.services.RequestTokenService"/> + </jaxrs:serviceBeans> + <jaxrs:properties> + <entry key="report.failure.details" value="true"/> + <entry key="report.failure.details.as.header" value="true"/> + </jaxrs:properties> +</jaxrs:server> -</pre> +]]></script> </div></div> @@ -768,51 +776,51 @@ However, supporting other types of end u Perhaps the simplest option is to extend a CXF OAuth filter (JAX-RS or servlet one), check Authorization header, if it is OAuth then delegate to the superclass, alternatively - proceed with authenticating the end users:</p> <div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent"> -<pre class="code-java"> -<span class="code-keyword">public</span> class SecurityFilter <span class="code-keyword">extends</span> org.apache.cxf.rs.security.oauth.filters.OAuthRequestFilter { +<script class="theme: Default; brush: java; gutter: false" type="syntaxhighlighter"><![CDATA[ +public class SecurityFilter extends org.apache.cxf.rs.security.oauth.filters.OAuthRequestFilter { @Context - <span class="code-keyword">private</span> HttpHeaders headers; + private HttpHeaders headers; - <span class="code-keyword">public</span> Response handleRequest(ClassResourceInfo cri, Message message) { - <span class="code-object">String</span> header = headers.getRequestHeaders().getFirst(<span class="code-quote">"Authorization"</span>); - <span class="code-keyword">if</span> (header.startsWith(<span class="code-quote">"OAuth "</span>)) { - <span class="code-keyword">return</span> <span class="code-keyword">super</span>.handleRequest(cri, message); - } <span class="code-keyword">else</span> { - <span class="code-comment">// authenticate the end user -</span> } + public Response handleRequest(ClassResourceInfo cri, Message message) { + String header = headers.getRequestHeaders().getFirst("Authorization"); + if (header.startsWith("OAuth ")) { + return super.handleRequest(cri, message); + } else { + // authenticate the end user + } } } -</pre> +]]></script> </div></div> <p>The next issue is how to enforce that the end users can only access the resources they've been authorized to access.<br clear="none"> For example, consider the following JAX-RS resource class:</p> <div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent"> -<pre class="code-java"> -@Path(<span class="code-quote">"calendar"</span>) -<span class="code-keyword">public</span> class CalendarResource { +<script class="theme: Default; brush: java; gutter: false" type="syntaxhighlighter"><![CDATA[ +@Path("calendar") +public class CalendarResource { @GET - @Path(<span class="code-quote">"{id}"</span>) - <span class="code-keyword">public</span> Calendar getPublicCalendar(@PathParam(<span class="code-quote">"id"</span>) <span class="code-object">long</span> id) { - <span class="code-comment">// <span class="code-keyword">return</span> the calendar <span class="code-keyword">for</span> a user identified by 'id' -</span> } + @Path("{id}") + public Calendar getPublicCalendar(@PathParam("id") long id) { + // return the calendar for a user identified by 'id' + } @GET - @Path(<span class="code-quote">"{id}/<span class="code-keyword">private</span>"</span>) - <span class="code-keyword">public</span> Calendar getPrivateCalendar(@PathParam(<span class="code-quote">"id"</span>) <span class="code-object">long</span> id) { - <span class="code-comment">// <span class="code-keyword">return</span> the calendar <span class="code-keyword">for</span> a user identified by 'id' -</span> } + @Path("{id}/private") + public Calendar getPrivateCalendar(@PathParam("id") long id) { + // return the calendar for a user identified by 'id' + } @PUT - @Path(<span class="code-quote">"{id}"</span>) - <span class="code-keyword">public</span> void updateCalendar(@PathParam(<span class="code-quote">"id"</span>) <span class="code-object">long</span> id, Calendar c) { - <span class="code-comment">// update the calendar <span class="code-keyword">for</span> a user identified by 'id' -</span> } + @Path("{id}") + public void updateCalendar(@PathParam("id") long id, Calendar c) { + // update the calendar for a user identified by 'id' + } } -</pre> +]]></script> </div></div> <p>Lets assume that the 3rd party consumer has been allowed to read the public user Calendars at "/calendar/{id}" only, how to make sure that the consumer won't try to:<br clear="none">
![http://cxf.apache.org/images/asf-logo.png"](http://cxf.apache.org/images/asf-logo.png"){kind=link}
