Author: buildbot
Date: Fri Apr 24 16:46:53 2015
New Revision: 949052
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 Fri Apr 24 16:46:53
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.rbtoc1421621185099 {padding: 0px;}
-div.rbtoc1421621185099 ul {list-style: disc;margin-left: 0px;}
-div.rbtoc1421621185099 li {margin-left: 0px;padding-left: 0px;}
+div.rbtoc1429893990608 {padding: 0px;}
+div.rbtoc1429893990608 ul {list-style: disc;margin-left: 0px;}
+div.rbtoc1429893990608 li {margin-left: 0px;padding-left: 0px;}
-/*]]>*/</style></p><div class="toc-macro rbtoc1421621185099">
+/*]]>*/</style></p><div class="toc-macro rbtoc1429893990608">
<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>
@@ -143,7 +143,9 @@ div.rbtoc1421621185099 li {margin-left:
<ul class="toc-indentation"><li><a shape="rect"
href="#JAX-RSOAuth2-MultipleFactorVerification">Multiple Factor
Verification</a></li></ul>
</li><li><a shape="rect"
href="#JAX-RSOAuth2-CustomizingEndUserSubjectinitialization">Customizing End
User Subject initialization</a></li><li><a shape="rect"
href="#JAX-RSOAuth2-ProtectingresourceswithOAuthfilters">Protecting resources
with OAuth filters</a>
<ul class="toc-indentation"><li><a shape="rect"
href="#JAX-RSOAuth2-OAuth2tokensandSOAPendpoints">OAuth2 tokens and SOAP
endpoints</a></li></ul>
-</li><li><a shape="rect" href="#JAX-RSOAuth2-Howtogettheuserloginname">How to
get the user login name</a></li><li><a shape="rect"
href="#JAX-RSOAuth2-Client-sidesupport">Client-side support</a></li><li><a
shape="rect" href="#JAX-RSOAuth2-OAuth2withouttheExplicitAuthorization">OAuth2
without the Explicit Authorization</a></li><li><a shape="rect"
href="#JAX-RSOAuth2-OAuthWithoutaBrowser">OAuth Without a
Browser</a></li><li><a shape="rect"
href="#JAX-RSOAuth2-Reportingerrordetails">Reporting error
details</a></li><li><a shape="rect" href="#JAX-RSOAuth2-OAuth2andJOSE">OAuth2
and JOSE</a></li><li><a shape="rect" href="#JAX-RSOAuth2-OAuth2andOIDC">OAuth2
and OIDC</a></li><li><a shape="rect"
href="#JAX-RSOAuth2-Designconsiderations">Design considerations</a>
+</li><li><a shape="rect" href="#JAX-RSOAuth2-Howtogettheuserloginname">How to
get the user login name</a></li><li><a shape="rect"
href="#JAX-RSOAuth2-Client-sidesupport">Client-side support</a>
+<ul class="toc-indentation"><li><a shape="rect"
href="#JAX-RSOAuth2-OAuth2clientfilters">OAuth2 client filters</a></li></ul>
+</li><li><a shape="rect"
href="#JAX-RSOAuth2-OAuth2withouttheExplicitAuthorization">OAuth2 without the
Explicit Authorization</a></li><li><a shape="rect"
href="#JAX-RSOAuth2-OAuthWithoutaBrowser">OAuth Without a
Browser</a></li><li><a shape="rect"
href="#JAX-RSOAuth2-Reportingerrordetails">Reporting error
details</a></li><li><a shape="rect" href="#JAX-RSOAuth2-OAuth2andJOSE">OAuth2
and JOSE</a></li><li><a shape="rect" href="#JAX-RSOAuth2-OAuth2andOIDC">OAuth2
and OIDC</a></li><li><a shape="rect"
href="#JAX-RSOAuth2-Designconsiderations">Design considerations</a>
<ul class="toc-indentation"><li><a shape="rect"
href="#JAX-RSOAuth2-ControllingtheAccesstoResourceServer">Controlling the
Access to Resource Server</a>
<ul class="toc-indentation"><li><a shape="rect"
href="#JAX-RSOAuth2-Sharingthesameaccesspathbetweenendusersandclients">Sharing
the same access path between end users and clients</a></li><li><a shape="rect"
href="#JAX-RSOAuth2-Providingdifferentaccesspointstoendusersandclients">Providing
different access points to end users and clients</a></li></ul>
</li><li><a shape="rect" href="#JAX-RSOAuth2-SingleSignOn">Single Sign
On</a></li></ul>
@@ -593,7 +595,57 @@ try {
]]></script>
-</div></div><h1 id="JAX-RSOAuth2-OAuth2withouttheExplicitAuthorization">OAuth2
without the Explicit Authorization</h1><p>Client Credentials is one of OAuth2
grants that does not require the explicit authorization and is currently
supported by CXF.</p><h1 id="JAX-RSOAuth2-OAuthWithoutaBrowser">OAuth Without a
Browser</h1><p>When an end user is accessing the 3rd party application and is
authorizing it later on, it's usually expected that the user is relying on a
browser. <br clear="none"> However, supporting other types of end users is easy
enough. Writing the client code that processes the redirection requests from
the 3rd party application and AuthorizationCodeGrantService is simple with
JAX-RS and additionally CXF can be configured to do auto-redirects on the
client side.</p><p>Also note that AuthorizationCodeGrantService can return XML
or JSON <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/a
pache/cxf/rs/security/oauth/data/OAuthAuthorizationData.java">OAuthAuthorizationData</a>
representations. That makes it easy for a client code to get
OAuthAuthorizationData and offer a pop-up window or get the input from the
command-line. Authorizing the third-party application might even be automated
in this case - which can lead to a complete 3-leg OAuth flow implemented
without a human user being involved.</p><h1
id="JAX-RSOAuth2-Reportingerrordetails">Reporting error details</h1><p>This <a
shape="rect" class="external-link"
href="http://tools.ietf.org/html/draft-ietf-oauth-v2-30#section-5.2";
rel="nofollow">section</a> lists all the error properties that can be returned
to the client application. CXF OAuth2 services will always report a required
'error' property but will omit the optional error properties by default (for
example, in case of access token grant handlers throwing <a shape="rect"
class="external-link"
href="http://svn.apache.org/repos/asf/cxf/trunk/rt/rs/security/oau
th-parent/oauth2/src/main/java/org/apache/cxf/rs/security/oauth2/provider/OAuthServiceException.java">OAuthServiceException</a>
initialized with <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/OAuthError.java";>OAuthError</a>
which may have the optional properties set).<br clear="none"> When reporting
the optional error properties is actually needed then setting a
'writeCustomErrors' property to 'true' will help:</p><div class="code panel
pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl">
+</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-OAuth2clientfilters">OAuth2 client
filters</h2><p>Not all clients that may need to access an OAuth2-protected
application server can be modified. Futhermore, not all OAuth2 clients can
participate in advanced flows such as an authorization code flow and need to be
initi
alized with access and refresh tokens.</p><p>CXF HTTPConduit HttpAuthSupplier
supporting access and refresh tokens is shipped starting from CXF 3.0.5
.</p><p>org.apache.cxf.rs.security.oauth2.client.BearerAuthSupplier supports
creating HTTP Authorization header from bearer access tokens, refreshing them
proactively or in response to 401 failures and recreating HTTP Authorization
from the refreshed token.</p><p>It is not possible to refresh a token from a
JAX-RS ClientRequestFilter because such a filter does not handle HTTP responses
so it can not detect 401 (returned by a server if the access token has
expired), while HTTPConduit HttpAuthSupplier gets a chance to react to 401 and
retry.</p><p>Here is a configuration example:</p><p> </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[<beans>
+<bean id="consumer"
class="org.apache.cxf.rs.security.oauth2.client.Consumer">
+ <property name="clientId" value="1"/>
+ <property name="clientSecret" value="2"/>
+</bean>
+<bean id="bearerAuthSupplier"
class="org.apache.cxf.rs.security.oauth2.client.BearerAuthSupplier">
+ <!-- access token -->
+ <property name="accessToken" value="12345678"/>
+ <!-- refresh token and the info needed to use it to refersh the expired
access token proactively or in response to 401 -->
+ <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
+ -->
+ <property name="refreshEarly" value="true"/>
+ <!-- client OAuth2 id and secret - needed to use a refresh token grant
-->
+ <property name="consumer" ref="consumer"/>
+ <!-- address of OAuth2 token service that supports a refresh token grant
+ <property name="accessTokenServiceUri"
value="https://server/oauth2/accessToken"/>
+</bean>
+<conduit name="*.http-conduit"
xmlns="http://cxf.apache.org/transports/http/configuration">
+ <authSupplier>
+ <ref bean="bearerAuthSupplier"/>
+ </authSupplier>
+</conduit>
+</beans>]]></script>
+</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">
+<script class="theme: Default; brush: xml; gutter: false"
type="syntaxhighlighter"><![CDATA[<beans>
+<bean id="consumer"
class="org.apache.cxf.rs.security.oauth2.client.Consumer">
+ <property name="clientId" value="1"/>
+ <property name="clientSecret" value="2"/>
+</bean>
+<bean id="codeAuthSupplier"
class="org.apache.cxf.rs.security.oauth2.client.CodeAuthSupplier">
+ <!-- authorization code -->
+ <property name="code" value="12345678"/>
+
+ <!-- Set this property for the authenticator to check the access token
expiry date and refresh the token proactively -->
+ <property name="refreshEarly" value="true"/>
+ <!-- client OAuth2 id and secret - needed to use a refresh token grant
-->
+ <property name="consumer" ref="consumer"/>
+ <!-- address of OAuth2 token service that supports a refresh token grant
+ <property name="accessTokenServiceUri"
value="https://server/oauth2/accessToken"/>
+</bean>
+<conduit name="*.http-conduit"
xmlns="http://cxf.apache.org/transports/http/configuration">
+ <authSupplier>
+ <ref bean="codeAuthSupplier"/>
+ </authSupplier>
+</conduit>
+</beans>]]></script>
+</div></div><p> </p><p>Additionally, a basic JAX-RS 2.0
ClientRequestFilter,
org.apache.cxf.rs.security.oauth2.client.BearerClientFilter, is shipped and is
initialized with an "accessToken" property only. It might be used in cases
where only a non-expiring access token is available.</p><p>Using a token that
expires within ClientRequestFilter does not work as explained above. However
BearerClientFilter might be enhanced to support the pro-active refreshment of
access token in the future.</p><h1
id="JAX-RSOAuth2-OAuth2withouttheExplicitAuthorization">OAuth2 without the
Explicit Authorization</h1><p>Client Credentials is one of OAuth2 grants that
does not require the explicit authorization and is currently supported by
CXF.</p><h1 id="JAX-RSOAuth2-OAuthWithoutaBrowser">OAuth Without a
Browser</h1><p>When an end user is accessing the 3rd party application and is
authorizing it later on, it's usually expected that the user is relying on a
browser. <br clear="none"> However, supporti
ng other types of end users is easy enough. Writing the client code that
processes the redirection requests from the 3rd party application and
AuthorizationCodeGrantService is simple with JAX-RS and additionally CXF can be
configured to do auto-redirects on the client side.</p><p>Also note that
AuthorizationCodeGrantService can return XML or JSON <a shape="rect"
class="external-link"
href="http://svn.apache.org/repos/asf/cxf/trunk/rt/rs/security/oauth-parent/oauth/src/main/java/org/apache/cxf/rs/security/oauth/data/OAuthAuthorizationData.java";>OAuthAuthorizationData</a>
representations. That makes it easy for a client code to get
OAuthAuthorizationData and offer a pop-up window or get the input from the
command-line. Authorizing the third-party application might even be automated
in this case - which can lead to a complete 3-leg OAuth flow implemented
without a human user being involved.</p><h1
id="JAX-RSOAuth2-Reportingerrordetails">Reporting error details</h1><p>This <a
shape="rec
t" class="external-link"
href="http://tools.ietf.org/html/draft-ietf-oauth-v2-30#section-5.2";
rel="nofollow">section</a> lists all the error properties that can be returned
to the client application. CXF OAuth2 services will always report a required
'error' property but will omit the optional error properties by default (for
example, in case of access token grant handlers throwing <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/OAuthServiceException.java";>OAuthServiceException</a>
initialized with <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/OAuthError.java";>OAuthError</a>
which may have the optional properties set).<br clear="none"> When reporting
the optional error properties is actually needed then setting a 'writeCustomErr
ors' property to 'true' will help:</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"><