You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@cxf.apache.org by bu...@apache.org on 2015/04/24 18:46:53 UTC
svn commit: r949052 - in /websites/production/cxf/content:
cache/docs.pageCache docs/jax-rs-oauth2.html
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"><![CDATA[<bean id="oauthProvider" class="oauth2.manager.OAuthManager"/>
<bean id="accessTokenService" class="org.apache.cxf.rs.security.oauth2.services.AccessTokenService">