cxf-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From build...@apache.org
Subject svn commit: r929080 - in /websites/production/cxf/content: cache/docs.pageCache docs/jax-rs-oauth2.html
Date Thu, 13 Nov 2014 16:47:07 GMT
Author: buildbot
Date: Thu Nov 13 16:47:07 2014
New Revision: 929080

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 Nov 13 16:47:07 2014
@@ -118,14 +118,14 @@ Apache CXF -- JAX-RS OAuth2
            <!-- Content -->
            <div class="wiki-content">
 <div id="ConfluenceContent"><h1 id="JAX-RSOAuth2-JAX-RS:OAuth2">JAX-RS: OAuth2</h1><p><style
type="text/css">/*<![CDATA[*/
-div.rbtoc1415382419537 {padding: 0px;}
-div.rbtoc1415382419537 ul {list-style: disc;margin-left: 0px;}
-div.rbtoc1415382419537 li {margin-left: 0px;padding-left: 0px;}
+div.rbtoc1415897192618 {padding: 0px;}
+div.rbtoc1415897192618 ul {list-style: disc;margin-left: 0px;}
+div.rbtoc1415897192618 li {margin-left: 0px;padding-left: 0px;}
 
-/*]]>*/</style></p><div class="toc-macro rbtoc1415382419537">
+/*]]>*/</style></p><div class="toc-macro rbtoc1415897192618">
 <ul class="toc-indentation"><li><a shape="rect" href="#JAX-RSOAuth2-JAX-RS:OAuth2">JAX-RS:
OAuth2</a></li><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>
 <ul class="toc-indentation"><li><a shape="rect" href="#JAX-RSOAuth2-AuthorizationService">Authorization
Service</a>
-<ul class="toc-indentation"><li><a shape="rect" href="#JAX-RSOAuth2-EndUserNameinAuthorizationForm">EndUser
Name in Authorization Form</a></li><li><a shape="rect" href="#JAX-RSOAuth2-PublicClients(Devices)">Public
Clients (Devices)</a>
+<ul class="toc-indentation"><li><a shape="rect" href="#JAX-RSOAuth2-HowtocreateAuthorizationView">How
to create Authorization View</a></li><li><a shape="rect" href="#JAX-RSOAuth2-EndUserNameinAuthorizationForm">EndUser
Name in Authorization Form</a></li><li><a shape="rect" href="#JAX-RSOAuth2-PublicClients(Devices)">Public
Clients (Devices)</a>
 <ul class="toc-indentation"><li><a shape="rect" href="#JAX-RSOAuth2-OOBResponse">OOB
Response</a></li><li><a shape="rect" href="#JAX-RSOAuth2-SecurecodeacquisitionwithredirectURI">Secure
code acquisition with redirect URI</a></li></ul>
 </li></ul>
 </li><li><a shape="rect" href="#JAX-RSOAuth2-AccessTokenService">AccessTokenService</a>
@@ -177,7 +177,7 @@ Referer=[http://localhost:8080/services/
 <script class="theme: Default; brush: xml; gutter: false" type="syntaxhighlighter"><![CDATA[12-Apr-2012
13:26:21 org.apache.cxf.rs.security.oauth2.services.AbstractOAuthService checkTransportSecurity
 WARNING: Unsecure HTTP, Transport Layer Security is recommended
 ]]></script>
-</div></div><p>It can also be configured to reject the requests over un-secure
HTTP transport.</p><p>AuthorizationCodeGrantService will retrieve the information
about the <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
application</a> 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/oauth2/src/main/java/org/apache/cxf/rs/security/oauth2/common/OAuthAuthorizationData.java">OAuthAuthorizationData</a>
bean and return 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/oauth2/src/main/java/org/apache/cxf/rs/security/oauth2/common/Permission.java">Permission</a>s
and other properties which can be either
  presented to the user or kept in the hidden form fields in order to uniquely identify the
actual authorization request when the end user returns the decision.</p><p>One
important OAuthAuthorizationData property is "authenticityToken". It is used for validating
that the current session has not been hijacked - AuthorizationCodeGrantService generates a
random key, stores it in a Servlet HTTPSession instance and expects the returned authenticityToken
value to match it - this is a recommended approach and it also implies that the authenticityToken
value is hidden from a user, for example, it's kept in a 'hidden' form field. The other properties
which are meant to be hidden are clientId, state, redirectUri, proposedScope.</p><p>The
helper "replyTo" property is an absolute URI identifying the AuthorizationCodeGrantService
handler processing the user decision and can be used by view handlers when building the forms
or by other OAuthAuthorizationData handlers.</p><p>So the populated OAuthAu
 thorizationData is finally returned. Note that it's a JAXB XMLRootElement-annotated bean
and can be processed by registered JAXB or JSON providers given that AuthorizationCodeGrantService
supports producing "application/xml" and "application/json" (See the OAuth Without Browser
section below for more). But in this case we have the end user working with a browser so an
HTML form is what is really expected back.</p><p>AuthorizationCodeGrantService
supports producing "text/html" and simply relies on a registered <a shape="rect" href="http://cxf.apache.org/docs/jax-rs-redirection.html#JAX-RSRedirection-WithRequestDispatcherProvider">RequestDispatcherProvider</a>
to set the OAuthAuthorizationData bean as an HttpServletRequest attribute and redirect the
response to a view handler (can be JSP or some other servlet) to actually build the form and
return it to the user. Alternatively, registering <a shape="rect" href="http://cxf.apache.org/docs/jax-rs-advanced-xml.html#JAX-RSAdvancedXML-XSLT
 support">XSLTJaxbProvider</a> would also be a good option for creating HTML views.</p><p>Assuming
RequestDispatcherProvider is used, the following example log shows the initial response from
AuthorizationCodeGrantService:</p><div class="code panel pdl" style="border-width:
1px;"><div class="codeContent panelContent pdl">
+</div></div><p>It can also be configured to reject the requests over un-secure
HTTP transport.</p><p>AuthorizationCodeGrantService will retrieve the information
about the <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
application</a> 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/oauth2/src/main/java/org/apache/cxf/rs/security/oauth2/common/OAuthAuthorizationData.java">OAuthAuthorizationData</a>
bean and return 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/oauth2/src/main/java/org/apache/cxf/rs/security/oauth2/common/Permission.java">Permission</a>s
and other properties which can be either
  presented to the user or kept in the hidden form fields in order to uniquely identify the
actual authorization request when the end user returns the decision.</p><p>One
important OAuthAuthorizationData property is "authenticityToken". It is used for validating
that the current session has not been hijacked - AuthorizationCodeGrantService generates a
random key, stores it in a Servlet HTTPSession instance and expects the returned authenticityToken
value to match it - this is a recommended approach and it also implies that the authenticityToken
value is hidden from a user, for example, it's kept in a 'hidden' form field. The other properties
which are meant to be hidden are clientId, state, redirectUri, proposedScope.</p><p>The
helper "replyTo" property is an absolute URI identifying the AuthorizationCodeGrantService
handler processing the user decision and can be used by view handlers when building the forms
or by other OAuthAuthorizationData handlers.</p><p>So the populated OAuthAu
 thorizationData is finally returned. Note that it's a JAXB XMLRootElement-annotated bean
and can be processed by registered JAXB or JSON providers given that AuthorizationCodeGrantService
supports producing "application/xml" and "application/json" (See the OAuth Without Browser
section below for more). But in this case we have the end user working with a browser so an
HTML form is what is really expected back.</p><p>AuthorizationCodeGrantService
supports producing "text/html" and simply relies on a registered <a shape="rect" href="http://cxf.apache.org/docs/jax-rs-redirection.html#JAX-RSRedirection-WithRequestDispatcherProvider">RequestDispatcherProvider</a>
to set the OAuthAuthorizationData bean as an HttpServletRequest attribute and redirect the
response to a view handler (can be JSP or some other servlet) to actually build the form and
return it to the user. See the section below on other alternatives on how a view can be created.</p><p>Assuming
RequestDispatcherProvider is used,
  the following example log shows the initial response from AuthorizationCodeGrantService:</p><div
class="code panel pdl" style="border-width: 1px;"><div class="codeContent panelContent
pdl">
 <script class="theme: Default; brush: xml; gutter: false" type="syntaxhighlighter"><![CDATA[12-Apr-2012
13:26:21 org.apache.cxf.jaxrs.provider.RequestDispatcherProvider logRedirection
 INFO: Setting an instance of &quot;org.apache.cxf.rs.security.oauth2.common.OAuthAuthorizationData&quot;
as HttpServletRequest 
 attribute &quot;data&quot; and redirecting the response to &quot;/forms/oauthAuthorize.jsp&quot;.
@@ -215,7 +215,7 @@ Authorization=[Basic YmFycnlAcmVzdGF1cmF
 Cookie=[JSESSIONID=1c289vha0cxfe],
 }
 ]]></script>
-</div></div><p>If a user decision was set to "deny" then the error will
be returned to the client.</p><p>Assuming the decision was "allow", the client
has now received back the authorization code grant and is ready to exchange it for a new access
token.</p><h3 id="JAX-RSOAuth2-EndUserNameinAuthorizationForm">EndUser Name in
Authorization Form</h3><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 id="JAX-RSOAuth2-PublicClients(Devices)">Public
Clients (Devices)</h3><p>CXF 2.7.7 provides an initial support for public clients
(such as various
  mobile devices).</p><p>Client can be 'public' if it has been registered as a
public client with no client secret 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><h4 id="JAX-RSOAuth2-OOBResponse">OOB Response</h4><p>If
a public client has not registered a redirect URI with the Authorization service then 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/oa
 uth-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>Having OOB responses supported is useful when a public
client (typically a device which can not keep the client secrets and where no redirect URI
is supported) 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">
+</div></div><p>If a user decision was set to "deny" then the error will
be returned to the client.</p><p>Assuming the decision was "allow", the client
has now received back the authorization code grant and is ready to exchange it for a new access
token.</p><h3 id="JAX-RSOAuth2-HowtocreateAuthorizationView">How to create Authorization
View</h3><p>Typically one can use RequestDispatcherProvider to redirect to a view
handler like JSP. Overriding RedirectionBasedService.startAuthorization by delegating to the
superclass and then converting the Response to HTML or writing a custom MessageBodyWriter
that will do the conversion are other two options.</p><p>Yet another option is
to register <a shape="rect" href="http://cxf.apache.org/docs/jax-rs-advanced-xml.html#JAX-RSAdvancedXML-XSLTsupport">XSLTJaxbProvider</a>
which would convert OAuthAuthorizationData to HTML or JAXBProvider set with a reference to
an XSLT stylesheet.</p><h3 id="JAX-RSOAuth2-EndUserNameinAuthorizationForm">EndUser
Name
  in Authorization Form</h3><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 id="JAX-RSOAuth2-PublicClients(Devices)">Public
Clients (Devices)</h3><p>CXF 2.7.7 provides an initial support for public clients
(such as various mobile devices).</p><p>Client can be 'public' if it has been
registered as a public client with no client secret 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 b
 e able to exchange a code grant for an access token.</p><h4 id="JAX-RSOAuth2-OOBResponse">OOB
Response</h4><p>If a public client has not registered a redirect URI with the
Authorization service then 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>Having OOB responses supported is useful when a public
client (typically a 
 device which can not keep the client secrets and where no redirect URI is supported) 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>
@@ -424,7 +424,7 @@ Headers: 
   Accept=[application/xml]
 }
 ]]></script>
-</div></div><p>the filter will do the following:</p><p>1. Retrieve
a ServerAccessToken by delegating to a matching registered <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/AccessTokenValidator.java">AccessTokenValidator</a>.
AccessTokenValidator is expected to check the validity of the incoming token parameters and
possibly delegate to OAuthDataProvider to find the token representation - this is what the
filter will default to if no matching AccessTokenValidator is found and the Authorization
scheme is 'Bearer'.</p><p>2. Check the token has not expired</p><p>3.
AccessToken may have a list of <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/security2/oauth/data/OAuthPermission.java">OAuthPermissions</a>.
For every permission it will:</p><ul class="alte
 rnate"><li>If it has a uri property set then the current request URI will be checked
against it</li><li>If it has an httpVerb property set then the current HTTP verb
will be checked against it</li></ul><p>4. Finally, it will create a CXF
<a shape="rect" class="external-link" href="http://svn.apache.org/repos/asf/cxf/trunk/api/src/main/java/org/apache/cxf/security/SecurityContext.java">SecurityContext</a>
using this list of <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/data/OAuthPermission.java">OAuthPermissions</a>,
the <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/UserSubject.java">UserSubject</a>
representing the client or the end user who authorized the grant used to obtain this token.</p><p>This
SecurityContext will not necessaril
 y be important for some of OAuth2 applications. Most of the security checks will be done
by OAuth2 filters and security filters protecting the main application path the end users
themselves use. Only if you would like to share the same JAX-RS resource code and access URIs
between end users and clients then it can become handy. More on it below.</p><p>Here
is one example of how OAuthRequestFilter can be configured:</p><div class="code panel
pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl">
+</div></div><p>the filter will do the following:</p><p>1. Retrieve
a ServerAccessToken by delegating to a matching registered <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/AccessTokenValidator.java">AccessTokenValidator</a>.
AccessTokenValidator is expected to check the validity of the incoming token parameters and
possibly delegate to OAuthDataProvider to find the token representation - this is what the
filter will default to if no matching AccessTokenValidator is found and the Authorization
scheme is 'Bearer'.</p><p>2. Check the token has not expired</p><p>3.
AccessToken may have a list of <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/security2/oauth/data/OAuthPermission.java">OAuthPermissions</a>.
For every permission it will:</p><ul class="alte
 rnate"><li>If it has a uri property set then the current request URI will be checked
against it</li><li>If it has an httpVerb property set then the current HTTP verb
will be checked against it</li></ul><p>If an allPermissionsMatch property
is set then the filter will check that all the token permissions have been met.</p><p>If
a requestScopes property is set then the filter will check that all of the scopes are 'covered'
by one or more token permissions.</p><p>4. Finally, it will create a CXF <a
shape="rect" class="external-link" href="http://svn.apache.org/repos/asf/cxf/trunk/api/src/main/java/org/apache/cxf/security/SecurityContext.java">SecurityContext</a>
using this list of <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/data/OAuthPermission.java">OAuthPermissions</a>,
the <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/UserSubject.java">UserSubject</a>
representing the client or the end user who authorized the grant used to obtain this token.</p><p>This
SecurityContext will not necessarily be important for some of OAuth2 applications. Most of
the security checks will be done by OAuth2 filters and security filters protecting the main
application path the end users themselves use. Only if you would like to share the same JAX-RS
resource code and access URIs between end users and clients then it can become handy. More
on it below.</p><p>Here is one example of how OAuthRequestFilter can be configured:</p><div
class="code panel pdl" style="border-width: 1px;"><div class="codeContent panelContent
pdl">
 <script class="theme: Default; brush: xml; gutter: false" type="syntaxhighlighter"><![CDATA[&lt;bean
id=&quot;oauthProvider&quot; class=&quot;oauth.manager.OAuthManager&quot;/&gt;
 &lt;bean id=&quot;oauthFiler&quot; class=&quot;org.apache.cxf.rs.security.oauth2.filters.OAuthRequestFilter&quot;&gt;
   &lt;property name=&quot;dataProvider&quot; ref=&quot;oauthProvider&quot;/&gt;



Mime
View raw message