Author: buildbot
Date: Thu Nov 26 12:47:04 2015
New Revision: 973633
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 26 12:47:04
2015
@@ -118,11 +118,11 @@ 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.rbtoc1448383591892 {padding: 0px;}
-div.rbtoc1448383591892 ul {list-style: disc;margin-left: 0px;}
-div.rbtoc1448383591892 li {margin-left: 0px;padding-left: 0px;}
+div.rbtoc1448541991917 {padding: 0px;}
+div.rbtoc1448541991917 ul {list-style: disc;margin-left: 0px;}
+div.rbtoc1448541991917 li {margin-left: 0px;padding-left: 0px;}
-/*]]>*/</style></p><div class="toc-macro rbtoc1448383591892">
+/*]]>*/</style></p><div class="toc-macro rbtoc1448541991917">
<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-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>
@@ -235,7 +235,7 @@ Payload:
grant_type=authorization_code&code=5c993144b910bccd5977131f7d2629ab
&redirect_uri=http%3A%2F%2Flocalhost%3A8080%2Fservices%2Freservations%2Freserve%2Fcomplete
</pre>
-</div></div><p>This request contains a client_id and client_secret
(Authorization header), the grant_type, the grant value (code)<br clear="none">
plus the redirect URI the authorization grant was returned to which is needed
for the additional validation.<br clear="none"> Note that the alternative
client authentication methods are also possible, in this case the token service
will expect a mapping between the client credentials and the client_id
representing the client registration available.</p><p>After validating the
request, the service will find a matching <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/AccessTokenGrantHandler.java";>AccessTokenGrantHandler</a>
and request to create 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/c
ommon/ServerAccessToken.java">ServerAccessToken</a> which is a server-side
representation of the access token.<br clear="none"> The grant handlers, such
as <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/AuthorizationCodeGrantHandler.java";>AuthorizationCodeGrantHandler</a>
may delegate the creation of the actual access token to data providers, which
may create Bearer or MAC tokens with the help of utility classes shipped with
CXF or depend on other 3rd party token libraries.</p><p>The data providers do
not strictly required to persist the data such as access tokens, instead the
token key may act as an encrypted bag capturing all the relevant
information.</p><p>Now that the token has been created, it is mapped by the
service to 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/ClientAccessToken.java">client
representation</a> and is returned back as a JSON payload:</p><div class="code
panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl">
+</div></div><p>This request contains a client_id and client_secret
(Authorization header), the grant_type, the grant value (code) plus the
redirect URI the authorization grant was returned to which is needed for the
additional validation. Note that the alternative client authentication methods
are also possible, in this case the token service will expect a mapping between
the client credentials and the client_id representing the client registration
available.</p><p>After validating the request, the service will find a matching
<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/AccessTokenGrantHandler.java";>AccessTokenGrantHandler</a>
and request to create 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/ServerAccessToken.java";>Serv
erAccessToken</a> which is a server-side representation of the access
token.<br clear="none"> The grant handlers, such as <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/AuthorizationCodeGrantHandler.java";>AuthorizationCodeGrantHandler</a>
may delegate the creation of the actual access token to data providers, which
may create Bearer or MAC tokens with the help of utility classes shipped with
CXF or depend on other 3rd party token libraries.</p><p>The data providers do
not strictly required to persist the data such as access tokens, instead the
token key may act as an encrypted bag capturing all the relevant
information.</p><p>Now that the token has been created, it is mapped by the
service to 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/securi
ty/oauth2/common/ClientAccessToken.java">client representation</a> and is
returned back as a JSON payload:</p><div class="code panel pdl"
style="border-width: 1px;"><div class="codeContent panelContent pdl">
<pre class="brush: xml; gutter: false; theme: Default"
style="font-size:12px;">Response-Code: 200
Content-Type: application/json
Headers: {
@@ -370,7 +370,7 @@ ModelEncryptionSupport.decryptAccessToke
// OAuthDataProvider methods
}
</pre>
-</div></div><p>CustomOAuthProvider will also remove all tokens associated with
a given Client in removeClient(String cliendId).</p><p>Finally
OAuthDataProvider may need to convert opaque scope values such as
"readCalendar" into 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/security/oauth2/common/OAuthPermission.java";>OAuthPermission</a>s.
AuthorizationCodeGrantService and OAuth2 security filters will depend on it
(assuming scopes are used in the first place). In the former case
AuthorizationCodeGrantService will use this list to populate <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>
- the reason this bean only sees <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
is that some of the properties OAuthPermission keeps are of no interest to
OAuthAuthorizationData handlers.</p><h3
id="JAX-RSOAuth2-DefaultProviders">Default
Providers</h3><p> </p><p>Starting from CXF 3.0.2 default Ehcache-based and
encrypting  OAuthDataProvider and AuthorizationCodeDataProvider
implementations are
shipped.</p><p>org.apache.cxf.rs.security.oauth2.grants.code.DefaultEHCacheCodeDataProvider
and org.apache.cxf.rs.security.oauth2.provider.DefaultEHCacheOAuthDataProvider
use Ehcache to store grant, client, access and refresh token
data.</p><p>org.apache.cxf.rs.security.oauth2.grants.code.DefaultEncryptingCodeDataProvider
and org.apache.cxf.rs.security.oauth2.provider.DefaultEncryptingOAuthDataProvider
use an auto-generated or provided Java symmetric SecretKey to
store</p><p>grant, access and refresh token data.</p><
p>Users are encouraged to experiment with these default providers, customize
them if needed and provide the feedback.</p><p>Users implementing their own
persistence strategy may consider extending
org.apache.cxf.rs.security.oauth2.grants.code.AbstractAuthorizationCodeDataProvider
or org.apache.cxf.rs.security.oauth2.provider.AbstractOAuthDataProvider -
these classes might help with taking care of some basic data initialization and
check routines.</p><h2 id="JAX-RSOAuth2-OAuthServerJAX-RSendpoints">OAuth
Server JAX-RS endpoints</h2><p>With CXF offering OAuth service implementations
and a custom OAuthDataProvider provider in place, it is time to deploy the
OAuth2 server. <br clear="none"> Most likely, you'd want to deploy
AccessTokenService as an independent JAX-RS endpoint, for example:</p><div
class="code panel pdl" style="border-width: 1px;"><div class="codeContent
panelContent pdl">
+</div></div><p>CustomOAuthProvider will also remove all tokens associated with
a given Client in removeClient(String cliendId).</p><p>Finally
OAuthDataProvider may need to convert opaque scope values such as
"readCalendar" into 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/security/oauth2/common/OAuthPermission.java";>OAuthPermission</a>s.
AuthorizationCodeGrantService and OAuth2 security filters will depend on it
(assuming scopes are used in the first place). In the former case
AuthorizationCodeGrantService will use this list to populate <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>
- the reason this bean only sees <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
is that some of the properties OAuthPermission keeps are of no interest to
OAuthAuthorizationData handlers.</p><h3
id="JAX-RSOAuth2-DefaultProviders">Default Providers</h3><p>Starting from CXF
3.0.2 default Ehcache-based and encrypting  OAuthDataProvider and
AuthorizationCodeDataProvider implementations are
shipped.</p><p>org.apache.cxf.rs.security.oauth2.grants.code.DefaultEHCacheCodeDataProvider
and org.apache.cxf.rs.security.oauth2.provider.DefaultEHCacheOAuthDataProvider
use Ehcache to store grant, client, access and refresh token
data.</p><p>org.apache.cxf.rs.security.oauth2.grants.code.DefaultEncryptingCodeDataProvider
and org.apache.cxf.rs.security.oauth2.provider.DefaultEncryptingOAuthDataProvider
use an auto-generated or provided Java symmetric SecretKey to store grant,
access and refresh token data.</p><p>Users are encoura
ged to experiment with these default providers, customize them if needed and
provide the feedback.</p><p>Users implementing their own persistence strategy
may consider extending
org.apache.cxf.rs.security.oauth2.grants.code.AbstractAuthorizationCodeDataProvider
or org.apache.cxf.rs.security.oauth2.provider.AbstractOAuthDataProvider -
these classes might help with taking care of some basic data initialization and
check routines.</p><h2 id="JAX-RSOAuth2-OAuthServerJAX-RSendpoints">OAuth
Server JAX-RS endpoints</h2><p>With CXF offering OAuth service implementations
and a custom OAuthDataProvider provider in place, it is time to deploy the
OAuth2 server. <br clear="none"> Most likely, you'd want to deploy
AccessTokenService as an independent JAX-RS endpoint, for example:</p><div
class="code panel pdl" style="border-width: 1px;"><div class="codeContent
panelContent pdl">
<pre class="brush: xml; gutter: false; theme: Default"
style="font-size:12px;"><!-- implements OAuthDataProvider -->
<bean id="oauthProvider" class="oauth.manager.OAuthManager"/>
@@ -395,7 +395,6 @@ ModelEncryptionSupport.decryptAccessToke
<property name="dataProvider" ref="oauthProvider"/>
</bean>
-
<jaxrs:server id="oauthServer" address="/oauth">
<jaxrs:serviceBeans>
<ref bean="accessTokenService"/>
@@ -417,7 +416,7 @@ ModelEncryptionSupport.decryptAccessToke
</jaxrs:serviceBeans>
</jaxrs:server>
</pre>
-</div></div><p>AuthorizationCodeGrantService 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 that of
AccessTokenService will be used by third-party clients.</p><h1
id="JAX-RSOAuth2-ThirdPartyClientAuthentication">Third Party Client
Authentication</h1><p>When a client requests a token from Access Token Service,
it needs to get authenticated. Providing its client_id and client secret as
part of Basic Authorization scheme or posting them directly as form parameters
are typical options, however other authentication schemes can easily be
supported if required.</p><p>For example, using client certificates or
assertions like SAML2 Bearer or JWT is all acceptable - the only additional
requirement in this case is that a given security filter processing a specific
authentication scheme maps the client credentials to an actual client_id - CXF
Access Token Service will check a
"client_id" property on the current message context as the last resort. Note
that org.apache.cxf.rs.security.oauth2.provider.ClientIdProvider can be
registered with AccessTokenService to facilitate the mapping between an
authenticated client and its id expected by the data provider if the container
or filter based authentication can not set a "client_id" contextual
property.</p><p>If a Basic authentication scheme is used and neither the
container or filter has authenticated the client AccessTokenService will
request a Client from the data provider and compare the Client's secret against
the password found in the Basic scheme data.
org.apache.cxf.rs.security.oauth2.provider.ClientSecretVerifier is available
starting from CXF 3.0.3 to support Clients saving only password hashes. Its
org.apache.cxf.rs.security.oauth2.provider.ClientSecretHashVerifier (calculates
a SHA-256 password hash and compares it with the Client's secret) or custom
implementations can be registered with AccessToke
nService.</p><p>If a 2-way TLS is sued to authenticate a client and Client has
a Base64 encoded representations of its X509Certificates available in its
"applicationCertificates" property then AccessTokenService will do the
additional comparison of these certificates against the ones available in the
current TLS session.</p><p> </p><p>Please see <a shape="rect"
href="jaxrs-oauth2-assertions.html">JAXRS OAuth2 Assertions</a> section for
more information on how it may work.</p><p> </p><h1
id="JAX-RSOAuth2-UserSessionAuthenticity">User Session
Authenticity</h1><p>Redirection-based Authorization Code and Implicit flows
depend on end users signing in if needed during the initial redirection,
challenged with the client authorization form and returning their decision. By
default, CXF will enforce the user session authenticity by keeping the session
state in a servlet container's HTTPSession. If the alternative storage is
preferred then you can register a new <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/SessionAuthenticityTokenProvider.java";>SessionAuthenticityTokenProvider</a>
(available from CXF 2.6.4) with either AuthorizationCodeGrantService or
ImplicitGrantService beans.</p><h3
id="JAX-RSOAuth2-Keepingthestateinthesession">Keeping the state in the
session</h3><p>Note that <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/SessionAuthenticityTokenProvider.java";>SessionAuthenticityTokenProvider</a>
has been further updated in CXF 3.1.0 to support signing and/or encrypting
some of the redirection properties that would otherwise have to be kept as HTML
form hidden fields (see "Authorization Service" section).</p><p>CXF  ships
org.apache.cxf.rs.security.oauth2.provider.JoseSessionTokenProvider that
can be used as 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/provider/SessionAuthenticityTokenProvider.java";>SessionAuthenticityTokenProvider</a>
which JWS-signs and/or JWE-encrypts the properties and saves the result in the
session. The HTML authorization forms will only have to have an
"authenticityToken" property which the provider will use to match the session
signed/encryped data and decrypt and/or validate the session data.</p><h3
id="JAX-RSOAuth2-MultipleFactorVerification">Multiple Factor
Verification</h3><p>Note that <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/SessionAuthenticityTokenProvider.java";>SessionAuthenticityTokenProvider</a>
has been updated in CXF 3.0.2 to accept request parameters and a reference to
the aut
henticated user. This allows for introducing a multiple factor session
verification: when the provider created a session property it can for example
sent a message to a user's mobile phone expect the authorization consent form
return the sent value.</p><p>The other minor enhancement is that
RedirectionBasedGrantService will check the authorization content form for the
name of the form property that contains a session authentication property,
using a "session_authenticity_token_param_name" property name. This allows for
the 'rotation' of hidden form properties containing the actual session
authenticity values.</p><h1
id="JAX-RSOAuth2-CustomizingEndUserSubjectinitialization">Customizing End User
Subject initialization</h1><p>By default, redirection based authorization
services will the the current CXF SecurityContext to initialize a subject
representing the authenticated resource owner/end user. If the customization if
needed: custom CXF filter can be used to create UserSubject and se
t it on the message or
org.apache.cxf.rs.security.oauth2.provider.SubjectCreator interface
implementation can be registered with either AuthorizationCodeGrantService or
ImplicitGrantService.</p><h1
id="JAX-RSOAuth2-ProtectingresourceswithOAuthfilters">Protecting resources with
OAuth filters</h1><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/filters/OAuthRequestFilter.java";>OAuthRequestFilter</a>
request handler can be used to protect the resource server when processing the
requests from the third-party clients. Add it as a jaxrs:provider to the
endpoint which deals with the clients requesting the resources.</p><p>When
checking a request like this:</p><div class="code panel pdl"
style="border-width: 1px;"><div class="codeContent panelContent pdl">
+</div></div><p>AuthorizationCodeGrantService 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 that of
AccessTokenService will be used by third-party clients.</p><h1
id="JAX-RSOAuth2-ThirdPartyClientAuthentication">Third Party Client
Authentication</h1><p>When a client requests a token from Access Token Service,
it needs to get authenticated. Providing its client_id and client secret as
part of Basic Authorization scheme or posting them directly as form parameters
are typical options, however other authentication schemes can easily be
supported if required.</p><p>For example, using client certificates or
assertions like SAML2 Bearer or JWT is all acceptable - the only additional
requirement in this case is that a given security filter processing a specific
authentication scheme maps the client credentials to an actual client_id - CXF
Access Token Service will check a
"client_id" property on the current message context as the last resort. Note
that org.apache.cxf.rs.security.oauth2.provider.ClientIdProvider can be
registered with AccessTokenService to facilitate the mapping between an
authenticated client and its id expected by the data provider if the container
or filter based authentication can not set a "client_id" contextual
property.</p><p>If a Basic authentication scheme is used and neither the
container or filter has authenticated the client AccessTokenService will
request a Client from the data provider and compare the Client's secret against
the password found in the Basic scheme data.
org.apache.cxf.rs.security.oauth2.provider.ClientSecretVerifier is available
starting from CXF 3.0.3 to support Clients saving only password hashes. Its
org.apache.cxf.rs.security.oauth2.provider.ClientSecretHashVerifier (calculates
a SHA-256 password hash and compares it with the Client's secret) or custom
implementations can be registered with AccessToke
nService.</p><p>If a 2-way TLS is sued to authenticate a client and Client has
a Base64 encoded representations of its X509Certificates available in its
"applicationCertificates" property then AccessTokenService will do the
additional comparison of these certificates against the ones available in the
current TLS session.</p><p>Please see <a shape="rect"
href="jaxrs-oauth2-assertions.html">JAXRS OAuth2 Assertions</a> section for
more information on how it may work.</p><h1
id="JAX-RSOAuth2-UserSessionAuthenticity">User Session
Authenticity</h1><p>Redirection-based Authorization Code and Implicit flows
depend on end users signing in if needed during the initial redirection,
challenged with the client authorization form and returning their decision. By
default, CXF will enforce the user session authenticity by keeping the session
state in a servlet container's HTTPSession. If the alternative storage is
preferred then you can register a new <a shape="rect" class="external-link"
href="htt
p://svn.apache.org/repos/asf/cxf/trunk/rt/rs/security/oauth-parent/oauth2/src/main/java/org/apache/cxf/rs/security/oauth2/provider/SessionAuthenticityTokenProvider.java">SessionAuthenticityTokenProvider</a>
(available from CXF 2.6.4) with either AuthorizationCodeGrantService or
ImplicitGrantService beans.</p><h3
id="JAX-RSOAuth2-Keepingthestateinthesession">Keeping the state in the
session</h3><p>Note that <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/SessionAuthenticityTokenProvider.java";>SessionAuthenticityTokenProvider</a>
has been further updated in CXF 3.1.0 to support signing and/or encrypting
some of the redirection properties that would otherwise have to be kept as HTML
form hidden fields (see "Authorization Service" section).</p><p>CXF  ships
org.apache.cxf.rs.security.oauth2.provider.JoseSessionTokenProvider that can be
used as 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/provider/SessionAuthenticityTokenProvider.java";>SessionAuthenticityTokenProvider</a>
which JWS-signs and/or JWE-encrypts the properties and saves the result in the
session. The HTML authorization forms will only have to have an
"authenticityToken" property which the provider will use to match the session
signed/encryped data and decrypt and/or validate the session data.</p><h3
id="JAX-RSOAuth2-MultipleFactorVerification">Multiple Factor
Verification</h3><p>Note that <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/SessionAuthenticityTokenProvider.java";>SessionAuthenticityTokenProvider</a>
has been updated in CXF 3.0.2 to accept request parameters and a reference to
the authenticated user. This allo
ws for introducing a multiple factor session verification: when the provider
created a session property it can for example sent a message to a user's mobile
phone expect the authorization consent form return the sent value.</p><p>The
other minor enhancement is that RedirectionBasedGrantService will check the
authorization content form for the name of the form property that contains a
session authentication property, using a
"session_authenticity_token_param_name" property name. This allows for the
'rotation' of hidden form properties containing the actual session authenticity
values.</p><h1
id="JAX-RSOAuth2-CustomizingEndUserSubjectinitialization">Customizing End User
Subject initialization</h1><p>By default, redirection based authorization
services will the the current CXF SecurityContext to initialize a subject
representing the authenticated resource owner/end user. If the customization if
needed: custom CXF filter can be used to create UserSubject and set it on the
message or org
.apache.cxf.rs.security.oauth2.provider.SubjectCreator interface
implementation can be registered with either AuthorizationCodeGrantService or
ImplicitGrantService.</p><h1
id="JAX-RSOAuth2-ProtectingresourceswithOAuthfilters">Protecting resources with
OAuth filters</h1><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/filters/OAuthRequestFilter.java";>OAuthRequestFilter</a>
request handler can be used to protect the resource server when processing the
requests from the third-party clients. Add it as a jaxrs:provider to the
endpoint which deals with the clients requesting the resources.</p><p>When
checking a request like this:</p><div class="code panel pdl"
style="border-width: 1px;"><div class="codeContent panelContent pdl">
<pre class="brush: xml; gutter: false; theme: Default"
style="font-size:12px;">Address:
http://localhost:8080/services/thirdPartyAccess/calendar
Http-Method: GET
Headers:
@@ -476,7 +475,7 @@ Headers:
</jaxrs:providers>
</jaxrs:server>
</pre>
-</div></div><h2 id="JAX-RSOAuth2-OAuth2tokensandSOAPendpoints">OAuth2 tokens
and SOAP endpoints</h2><p> </p><p>If you use HTTP Authorization header or
WS-Security Binary token to pass OAuth2 tokens to SOAP endpoints then <a
shape="rect" class="external-link"
href="https://git-wip-us.apache.org/repos/asf?p=cxf.git;a=blob;f=rt/rs/security/oauth-parent/oauth2/src/main/java/org/apache/cxf/rs/security/oauth2/filters/OAuthRequestInterceptor.java;h=173fed36fc78db69c0d4afaee5d5f482dd4e05fd;hb=HEAD";>OAuthRequestInterceptor</a>
can be used to validate such tokens. It is OAuthRequestFilter running as CXF
interceptor which will work OOB for tokens passed with Authorization header and
it can be easily extended to support WS-Security binary tokens</p><h1
id="JAX-RSOAuth2-Howtogettheuserloginname">How to get the user login
name</h1><p>When one writes a custom server application which needs to
participate in OAuth2 flows, the major question which needs to be addressed
is<br clear="none"> how o
ne can access a user login name that was used during the end-user authorizing
the third-party client. This username will help to uniquely identify the
resources that the 3rd party client is now attempting to access. The following
code shows one way of how this can be done:</p><div class="code panel pdl"
style="border-width: 1px;"><div class="codeContent panelContent pdl">
+</div></div><h2 id="JAX-RSOAuth2-OAuth2tokensandSOAPendpoints">OAuth2 tokens
and SOAP endpoints</h2><p>If you use HTTP Authorization header or WS-Security
Binary token to pass OAuth2 tokens to SOAP endpoints then <a shape="rect"
class="external-link"
href="https://git-wip-us.apache.org/repos/asf?p=cxf.git;a=blob;f=rt/rs/security/oauth-parent/oauth2/src/main/java/org/apache/cxf/rs/security/oauth2/filters/OAuthRequestInterceptor.java;h=173fed36fc78db69c0d4afaee5d5f482dd4e05fd;hb=HEAD";>OAuthRequestInterceptor</a>
can be used to validate such tokens. It is OAuthRequestFilter running as CXF
interceptor which will work OOB for tokens passed with Authorization header and
it can be easily extended to support WS-Security binary tokens</p><h1
id="JAX-RSOAuth2-Howtogettheuserloginname">How to get the user login
name</h1><p>When one writes a custom server application which needs to
participate in OAuth2 flows, the major question which needs to be addressed is
how one can access a user login nam
e that was used during the end-user authorizing the third-party client. This
username will help to uniquely identify the resources that the 3rd party client
is now attempting to access. The following code shows one way of how this can
be done:</p><div class="code panel pdl" style="border-width: 1px;"><div
class="codeContent panelContent pdl">
<pre class="brush: java; gutter: false; theme: Default"
style="font-size:12px;">
import org.apache.cxf.rs.security.oauth2.utils.OAuthContextUtils;
@@ -520,10 +519,10 @@ public class ThirdPartyAccessService {
<pre class="brush: java; gutter: false; theme: Default"
style="font-size:12px;">public class OAuthClientManager {
private WebClient accessTokenService;
- private String authorizationServiceURI;
- private Consumer consumer;
+ private String authorizationServiceURI;
+ private Consumer consumer;
- // inject properties, register the client application...
+ // inject properties, register the client application...
public URI getAuthorizationServiceURI(ReservationRequest request,
URI redirectUri,
@@ -558,8 +557,6 @@ import org.apache.cxf.rs.security.oauth2
import org.apache.cxf.rs.security.oauth2.grants.refresh.RefreshTokenGrant;
import org.apache.cxf.rs.security.oauth2.common.ClientAccessToken;
-
-
// the pseudo-code for getting the access token
Consumer consumer = ...
AuthorizationCodeGrant codeGrant = ...
@@ -592,9 +589,6 @@ try {
}
}
-
-
-
</pre>
</div></div><p>The client code directly dealing with OAuth2 specifics can be
the most flelxible option: the client which has both access and refresh tokens
can check the current access token expiry time and if it is known to have
expiried then it can proactively</p><p>refresh the tokens, avoiding doing a
futile HTTP request that is bound to return 401. Or/and indeed it can take care
of JAX-RS NotAuthorizedException (401) and refresh the tokens. Sophisticated
clients might want to check which scopes have been approved for a given access
token and dynamically decide if a given HTTP service call can be made or not.
Clients can also proactively revoke the tokens using a token revocation
mechanism.</p><h2
id="JAX-RSOAuth2-OAuth2clientapplicationswithcode-grantfilters">OAuth2 client
applications with code-grant filters</h2><p>The code in the previous section
shows the client application code directly supporting OAuth2 dynamics
(redirection, the access token acquisition). Starting from CXF
3.0.6 a simpler option is possible with the help of ClientCodeRequestFilter.
This filter manages the initial redirection, exchanging code grants for tokens,
persisting the request state, and then making the token and the state available
to the application code, for example, the following code does not deal itself
with teh redirection or interacting with OAuth2 servers:</p><div class="code
panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl">
<pre class="brush: java; gutter: false; theme: Default"
style="font-size:12px;">import org.apache.cxf.jaxrs.client.WebClient;
@@ -652,45 +646,44 @@ public Response reserve(@Context ClientT
}
</pre>
-</div></div><p> </p><p>The filter is configured as
follows:</p><p> </p><p> </p><div class="code panel pdl"
style="border-width: 1px;"><div class="codeContent panelContent pdl">
+</div></div><p> </p><p>The filter is configured as
follows:</p><p> </p><div class="code panel pdl" style="border-width:
1px;"><div class="codeContent panelContent pdl">
<pre class="brush: xml; gutter: false; theme: Default"
style="font-size:12px;"><beans>
<jaxrs:server id="reservationsServer" address="/reservations">
- <jaxrs:serviceBeans>
- <ref bean="restaurantReserveService"/>
- </jaxrs:serviceBeans>
- <jaxrs:providers>
- <!-- other providers -->
-
- <bean
class="oauth2.thirdparty.CustomClientTokenContextProvider"/>
- <bean
class="org.apache.cxf.rs.security.oauth2.client.ClientCodeRequestFilter">
- <property name="authorizationServiceUri"
value="http://localhost:8080/services/authorize"/>
- <property name="accessTokenServiceClient"
ref="atServiceClient"/>
- <property name="startUri" value="reserve/table"/>
- <property name="clientCodeStateManager"
ref="codeManager"/>
- <property name="consumer" ref="consumer"/>
- </bean>
- </jaxrs:providers>
- </jaxrs:server>
- <bean id="codeManager"
class="oauth2.thirdparty.ClientCodeStateManagerImpl"/>
-
- <!-- the consumer pre-registered with OAuth2 servers -->
- <bean id="consumer"
class="org.apache.cxf.rs.security.oauth2.client.Consumer">
- <property name="key" value="123456789"/>
- <property name="secret" value="987654321"/>
- </bean>
-
- <!-- WebClient for communicating with OAuth2 AccessTokenService -->
- <jaxrs-client:client id="atServiceClient"
serviceClass="org.apache.cxf.jaxrs.client.WebClient"
- address="http://localhost:8080/services/oauth2Token/token">
- <jaxrs-client:headers>
- <entry key="Accept" value="application/json"/>
- </jaxrs-client:headers>
- </jaxrs-client:client>
+ <jaxrs:serviceBeans>
+ <ref bean="restaurantReserveService"/>
+ </jaxrs:serviceBeans>
+ <jaxrs:providers>
+ <!-- other providers -->
+
+ <bean class="oauth2.thirdparty.CustomClientTokenContextProvider"/>
+ <bean
class="org.apache.cxf.rs.security.oauth2.client.ClientCodeRequestFilter">
+ <property name="authorizationServiceUri"
value="http://localhost:8080/services/authorize"/>
+ <property name="accessTokenServiceClient"
ref="atServiceClient"/>
+ <property name="startUri" value="reserve/table"/>
+ <property name="clientCodeStateManager" ref="codeManager"/>
+ <property name="consumer" ref="consumer"/>
+ </bean>
+ </jaxrs:providers>
+</jaxrs:server>
+
+<bean id="codeManager"
class="oauth2.thirdparty.ClientCodeStateManagerImpl"/>
-</beans>
+<!-- the consumer pre-registered with OAuth2 servers -->
+<bean id="consumer"
class="org.apache.cxf.rs.security.oauth2.client.Consumer">
+ <property name="key" value="123456789"/>
+ <property name="secret" value="987654321"/>
+</bean>
+<!-- WebClient for communicating with OAuth2 AccessTokenService -->
+<jaxrs-client:client id="atServiceClient"
serviceClass="org.apache.cxf.jaxrs.client.WebClient"
+ address="http://localhost:8080/services/oauth2Token/token">
+ <jaxrs-client:headers>
+ <entry key="Accept" value="application/json"/>
+ </jaxrs-client:headers>
+</jaxrs-client:client>
+</beans>
</pre>
</div></div><p> ClientCodeRequestFilter redirects to
'authorizationServiceUri' when a 'startUri' is matched.</p><p>In the above
example the filter uses a custom 'clientCodeStateManager'
(org.apache.cxf.rs.security.oauth2.client.ClientCodeStateManager
implementation) for keeping the original request state before redirecting for
it to be available later on to the application code - this is optional and is
only needed if the redirection request depends on the request parameters
(example, Oauth2 scope values are dynamic such as updateCalendar-7 where '7' is
the hour) . By default, CXF ships some state managers out of the box, at the
moment these are MemoryClientCodeStateManager and JoseClientCodeStateManager
implementations, the latter signs and/or encrypts the request state and saves
it in the HTTP session.</p><p>After the user is redirected back the filter
exchanges the code for a new access token and sets this token and the original
redirection state in ClientTokenContext. Note
CllientTokenContext makes the original request state available to the
application as MultivaluedMap.</p><p>CXF also ships a default
ClientTokenContext implementation, a simple
org.apache.cxf.rs.security.oauth2.client.ClientTokenContextImpl bean. Finally
CXF ships org.apache.cxf.rs.security.oauth2.client.ClientTokenContextProvider
to ensure ClientTokenContext can be available as JAX-RS context. Note though
that the above configuration registers a custom ClientTokenContext provider
('oauth2.thirdparty.CustomClientTokenContextProvider') instead - this is
optional and is only needed if it is preferred for the application code to
access the state in a type safe way (example, via ReservationRequest type as
shown above), such a provider can be implemented like
this:</p><p> </p><div class="code panel pdl" style="border-width:
1px;"><div class="codeContent panelContent pdl">
<pre class="brush: java; gutter: false; theme: Default"
style="font-size:12px;">import javax.ws.rs.core.MultivaluedMap;
@@ -743,7 +736,8 @@ public class CustomClientTokenContextPro
<property name="refreshToken" value="87654321"/>
<!--
Set this property for the authenticator to check the access token
expiry date and refresh the token proactively.
- Note that this property can also become effective after the first token
refresh as it is not known in advance when the injected access token will expire
+ Note that this property can also become effective after the first token
refresh as it is not known in advance when
+ the injected access token will expire
-->
<property name="refreshEarly" value="true"/>
<!-- client OAuth2 id and secret - needed to use a refresh token grant
-->
@@ -757,7 +751,7 @@ public class CustomClientTokenContextPro
</authSupplier>
</conduit>
</beans></pre>
-</div></div><p> </p><p>At the moment only BearerAuthSupplier supporting
bearer access tokens is available; authenticators supporting other well known
token types will be provided in the
future.</p><p>org.apache.cxf.rs.security.oauth2.client.CodeAuthSupplier is also
shipped. It is similar to BearerAuthSupplier except that it is initailized with
an authorization code grant obtained out of band, uses this grant</p><p>to get
the tokens and then delegates to BearerAuthSupplier.
Example:</p><p> </p><div class="code panel pdl" style="border-width:
1px;"><div class="codeContent panelContent pdl">
+</div></div><p> </p><p>At the moment only BearerAuthSupplier supporting
bearer access tokens is available; authenticators supporting other well known
token types will be provided in the
future.</p><p>org.apache.cxf.rs.security.oauth2.client.CodeAuthSupplier is also
shipped. It is similar to BearerAuthSupplier except that it is initailized with
an authorization code grant obtained out of band, uses this grant to get the
tokens and then delegates to BearerAuthSupplier. Example:</p><p> </p><div
class="code panel pdl" style="border-width: 1px;"><div class="codeContent
panelContent pdl">
<pre class="brush: xml; gutter: false; theme: Default"
style="font-size:12px;"><beans>
<bean id="consumer"
class="org.apache.cxf.rs.security.oauth2.client.Consumer">
<property name="clientId" value="1"/>
