cxf-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From build...@apache.org
Subject svn commit: r994731 - in /websites/production/cxf/content: cache/docs.pageCache docs/jax-rs-oauth2.html
Date Mon, 08 Aug 2016 12:47:38 GMT
Author: buildbot
Date: Mon Aug  8 12:47:38 2016
New Revision: 994731

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 Mon Aug  8 12:47:38 2016
@@ -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.rbtoc1466682418597 {padding: 0px;}
-div.rbtoc1466682418597 ul {list-style: disc;margin-left: 0px;}
-div.rbtoc1466682418597 li {margin-left: 0px;padding-left: 0px;}
+div.rbtoc1470660420927 {padding: 0px;}
+div.rbtoc1470660420927 ul {list-style: disc;margin-left: 0px;}
+div.rbtoc1470660420927 li {margin-left: 0px;padding-left: 0px;}
 
-/*]]>*/</style></p><div class="toc-macro rbtoc1466682418597">
+/*]]>*/</style></p><div class="toc-macro rbtoc1470660420927">
 <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>
@@ -364,7 +364,7 @@ return token;
 // decrypt a token given a token key
 
 ModelEncryptionSupport.decryptAccessToken(this, encryptedToken, key);</pre>
-</div></div><pre>&#160;</pre><h4 id="JAX-RSOAuth2-JWTTokens">JWT
Tokens</h4><p>JWT Token can be JWE-encrypted and the encrypted string passed to
ServerAccessToken as access token id parameter.</p><p>See <a shape="rect" href="http://cxf.apache.org/docs/jax-rs-jose.html">JAX-RS
JOSE</a> wiki page for more information on how to sign and encrypt JSON Web Tokens.</p><p><a
shape="rect" class="external-link" href="https://github.com/apache/cxf/blob/master/rt/rs/security/oauth-parent/oauth2/src/main/java/org/apache/cxf/rs/security/oauth2/tokens/jwt/JwtAccessTokenUtils.java"
rel="nofollow">JwtAccessTokenUtils </a>provides utility method for encrypting and
decrypting an access token represented as JWT.</p><p>Note more support for JWT
access tokens is on the way.</p><h4 id="JAX-RSOAuth2-Customtokens">Custom tokens</h4><p>If
needed, users can use their own custom token types, with the only restriction that the custom
token type implementations have to extend org.apache.cxf.rs.security.oauth2.co
 mmon.ServerAccessToken.</p><h4 id="JAX-RSOAuth2-SimpleTokensandAudience">Simple
Tokens and Audience</h4><p>Starting from CXF 2.7.7 an <a shape="rect" class="external-link"
href="http://tools.ietf.org/html/draft-tschofenig-oauth-audience-00" rel="nofollow">audience</a>
parameter is supported during the client token requests.</p><h3 id="JAX-RSOAuth2-OAuthJSONProvider">OAuthJSONProvider</h3><p>org.apache.cxf.rs.security.oauth2.provider.OAuthJSONProvider
is a JAX-RS MessageBodyWriter which supports returning ClientAccessToken and OAuthError representations
to the client in a JSON format required by OAuth2 spec. It is also a JAX-RS MessageBodyReader
that is used by client OAuthClientUtils (see below) to read the responses from AccessTokenService.</p><p>Register
it as a provider with a JAXRS AccessTokenService endpoint.</p><p>Alternatively,
if you prefer, a custom MessageBodyWriter implementation can be registered instead.</p><h2
id="JAX-RSOAuth2-AccessTokenValidationService">Access Token
  Validation Service</h2><h3 id="JAX-RSOAuth2-AccessTokenValidatorService">AccessTokenValidatorService</h3><p>The
<a shape="rect" class="external-link" href="https://github.com/apache/cxf/blob/master/rt/rs/security/oauth-parent/oauth2/src/main/java/org/apache/cxf/rs/security/oauth2/services/AccessTokenValidatorService.java"
rel="nofollow">AccessTokenValidatorService</a> is a CXF specific OAuth2 service for
accepting the remote access token validation requests. OAuthRequestFilter needs to be injected
with <a shape="rect" class="external-link" href="https://github.com/apache/cxf/blob/master/rt/rs/security/oauth-parent/oauth2/src/main/java/org/apache/cxf/rs/security/oauth2/filters/AccessTokenValidatorClient.java"
rel="nofollow">AccessTokenValidatorClient</a> which will ask AccessTokenValidatorService
to return the information relevant to the current access token, before setting up a security
context.</p><h3 id="JAX-RSOAuth2-TokenIntrospectionService">TokenIntrospectionService</h3><p>The
  <a shape="rect" class="external-link" href="https://github.com/apache/cxf/blob/master/rt/rs/security/oauth-parent/oauth2/src/main/java/org/apache/cxf/rs/security/oauth2/services/TokenIntrospectionService.java"
rel="nofollow">TokenIntrospectionService</a> is a standard OAuth2 service for accepting
the remote access token introspection requests. See <a shape="rect" class="external-link"
href="https://tools.ietf.org/html/rfc7662" rel="nofollow">RFC 7662</a>. OAuthRequestFilter
needs to be injected with <a shape="rect" class="external-link" href="https://github.com/apache/cxf/blob/master/rt/rs/security/oauth-parent/oauth2/src/main/java/org/apache/cxf/rs/security/oauth2/filters/AccessTokenIntrospectionClient.java"
rel="nofollow">AccessTokenIntrospectionClient.</a></p><h2 id="JAX-RSOAuth2-TokenRevocationService">TokenRevocationService</h2><p><a
shape="rect" class="external-link" href="https://github.com/apache/cxf/blob/master/rt/rs/security/oauth-parent/oauth2/src/main/java/org/apache/cx
 f/rs/security/oauth2/services/TokenRevocationService.java" rel="nofollow">TokenRevocationService</a>
is a simple OAuth2 service supporting the clients wishing to revoke the access or refresh
tokens they own themselves, please see <a shape="rect" class="external-link" href="http://tools.ietf.org/html/draft-ietf-oauth-revocation-09"
rel="nofollow">OAuth2 Token Revocation Draft</a> for more information.</p><p>TokenRevocationService
and AccessTokenService share the same code which enforces that the clients have been correctly
authenticated.</p><p>Note, OAuthDataProvider implementations processing a revocation
request should simply ignore the invalid tokens as recommended by the specification which
will let TokenRevocationService return HTTP 200 which is done to minimize a possible attack
surface (specifically for bad clients not to see if their requests failed or succeeded) and
throw the exceptions only if the token revocation feature is not currently supported.</p><h2
id="JAX-RSOAuth2-
 SupportedGrants">Supported Grants</h2><p>The following subsections briefly
describe how the well-known grant types can be supported on the server side. Please also check
the "Client Side Support" section on how to use the related <a shape="rect" class="external-link"
href="https://github.com/apache/cxf/blob/master/rt/rs/security/oauth-parent/oauth2/src/main/java/org/apache/cxf/rs/security/oauth2/common/AccessTokenGrant.java"
rel="nofollow">AccessTokenGrant</a> implementations to request the access tokens.</p><h3
id="JAX-RSOAuth2-AuthorizationCode">Authorization Code</h3><p>As described
above, <a shape="rect" class="external-link" href="https://github.com/apache/cxf/blob/master/rt/rs/security/oauth-parent/oauth2/src/main/java/org/apache/cxf/rs/security/oauth2/services/AuthorizationCodeGrantService.java"
rel="nofollow">AuthorizationCodeGrantService</a> service and <a shape="rect" class="external-link"
href="https://github.com/apache/cxf/blob/master/rt/rs/security/oauth-parent/oauth2/s
 rc/main/java/org/apache/cxf/rs/security/oauth2/grants/code/AuthorizationCodeDataProvider.java"
rel="nofollow">AuthorizationCodeDataProvider</a> data provider can support a redirection-based
Authorization Code flow.</p><p>The code that the client receives in the end of
the redirection process will need to be exchanged for a new access token with AccessTokenService.
CXF-based clients can use a helper <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/AuthorizationCodeGrant.java">AuthorizationCodeGrant</a>
bean to request a new access token with OAuthClientUtils.</p><h3 id="JAX-RSOAuth2-Implicit">Implicit</h3><p>Implicit
grant is supported the same way Authorization Code grant is except that no code is created,
a token is issued immediately and returned to the client running within a web browser.</p><p><a
shape="rect" class="external-link" href="https://gith
 ub.com/apache/cxf/blob/master/rt/rs/security/oauth-parent/oauth2/src/main/java/org/apache/cxf/rs/security/oauth2/services/ImplicitGrantService.java"
rel="nofollow">ImplicitGrantService</a> service asks <a shape="rect" class="external-link"
href="https://github.com/apache/cxf/blob/master/rt/rs/security/oauth-parent/oauth2/src/main/java/org/apache/cxf/rs/security/oauth2/provider/OAuthDataProvider.java"
rel="nofollow">OAuthDataProvider</a> data provider to issue a new token after a user
has approved it.</p><p>Note the only difference is the use of ImplicitGrantService
instead of AuthorizationCodeGrantService.</p><p>Also note that when an Implicit
grant client (running within a browser) replaces the code grant for a new access token and
tries to access the end user's resource, Cross Origin Resource Sharing (CORS) support will
most likely need to be enabled on the end user's resource server.<br clear="none"> The
simplest approach is to register a CXF <a shape="rect" href="http://cxf.apac
 he.org/docs/jax-rs-cors.html">CORS filter</a>, right before OAuth2 filter (see on
it below).</p><p>Starting from CXF 2.7.5 it is possible to request ImplicitGrantService
to return a registered Client id to the browser-hosted client. This is recommended so that
the client can verify that the token is meant to be delivered to this client.</p><h3
id="JAX-RSOAuth2-ClientCredentials">Client Credentials</h3><p>Register <a
shape="rect" class="external-link" href="https://github.com/apache/cxf/blob/master/rt/rs/security/oauth-parent/oauth2/src/main/java/org/apache/cxf/rs/security/oauth2/grants/clientcred/ClientCredentialsGrant.java"
rel="nofollow">ClientCredentialsGrantHandler</a> handler with AccessTokenService
for this grant be supported.</p><p>CXF-based clients can use a helper <a shape="rect"
class="external-link" href="https://github.com/apache/cxf/blob/master/rt/rs/security/oauth-parent/oauth2/src/main/java/org/apache/cxf/rs/security/oauth2/grants/clientcred/ClientCredentialsGrant.jav
 a" rel="nofollow">ClientCredentialsGrant</a> bean to request a new access token
with OAuthClientUtils.</p><h3 id="JAX-RSOAuth2-ResourceOwnerPasswordCredentials">Resource
Owner Password Credentials</h3><p>Register <a shape="rect" class="external-link"
href="https://github.com/apache/cxf/blob/master/rt/rs/security/oauth-parent/oauth2/src/main/java/org/apache/cxf/rs/security/oauth2/grants/owner/ResourceOwnerGrantHandler.java"
rel="nofollow">ResourceOwnerGrantHandler</a> handler with AccessTokenService for
this grant be supported.</p><p>CXF-based clients can use a helper <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/owner/ResourceOwnerGrant.java">ResourceOwnerGrant</a>
bean to request a new access token with OAuthClientUtils.</p><h3 id="JAX-RSOAuth2-RefreshToken">Refresh
Token</h3><p>The client can issue a refresh token grant if the current access
token it ow
 ns has expired or been revoked and the refresh token was issued alongside with the access
token which is now invalid and get the new, 'refreshed' access token. This can allow the client
to avoid seeking a new authorization approval from the end user.</p><p>Register
<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/refresh/RefreshTokenGrantHandler.java">RefreshTokenGrantHandler</a>
handler with AccessTokenService for this grant be supported. Note this grant handler is only
useful for refreshing the existing access token, so one or more of the other grant handlers
(Authorization Code, Implicit, etc) will also have to be registered with AccessTokenService.</p><p>CXF-based
clients can use a helper <a shape="rect" class="external-link" href="https://github.com/apache/cxf/blob/master/rt/rs/security/oauth-parent/oauth2/src/main/java/org/apache/cxf/rs/security/oauth2
 /grants/owner/ResourceOwnerGrant.java" rel="nofollow">RefreshTokenGrant</a> bean
to request a new access token with OAuthClientUtils.</p><h3 id="JAX-RSOAuth2-SAMLandJWTAssertions">SAML
and JWT Assertions</h3><p><a shape="rect" class="external-link" href="https://tools.ietf.org/html/rfc7522"
rel="nofollow">SAML2 assertions</a> and <a shape="rect" class="external-link"
href="https://tools.ietf.org/html/rfc7523" rel="nofollow">JWT assertions</a> can
be used as token grants.</p><p>JWT assertion grants are supported in <a shape="rect"
class="external-link" href="https://github.com/apache/cxf/tree/master/rt/rs/security/oauth-parent/oauth2/src/main/java/org/apache/cxf/rs/security/oauth2/grants/jwt"
rel="nofollow">this package</a>. <a shape="rect" class="external-link" href="https://github.com/apache/cxf/blob/master/rt/rs/security/oauth-parent/oauth2/src/main/java/org/apache/cxf/rs/security/oauth2/grants/jwt/JwtBearerClientCredentialsGrant.java"
rel="nofollow">JwtBearerClientCredentialsGran
 t</a> is AccessTokenGrantHandler one can register with AccessTokenService. <a shape="rect"
class="external-link" href="https://github.com/apache/cxf/blob/master/rt/rs/security/oauth-parent/oauth2/src/main/java/org/apache/cxf/rs/security/oauth2/grants/jwt/JwtBearerGrantHandler.java"
rel="nofollow">JwtBearerGrantHandler</a> is a client side helper once can use with
OAuthClientUtils. <a shape="rect" class="external-link" href="https://github.com/apache/cxf/blob/master/rt/rs/security/oauth-parent/oauth2/src/main/java/org/apache/cxf/rs/security/oauth2/grants/jwt/JwtBearerAuthHandler.java"
rel="nofollow">JwtBearerAuthHandler</a> can be used as a generic client authentication
filter (where the client authenticated with JWT token as opposed to with a username:password
pair, etc).</p><p>Please also see <a shape="rect" href="jaxrs-oauth2-assertions.html">JAXRS
OAuth2 Assertions</a> section for more information.</p><p>&#160;</p><h3
id="JAX-RSOAuth2-CustomGrants">Custom Grants</h3><p>If you nee
 d to customize the way the well-known grant requests are handled then consider extending
one of the grant handlers listed in the previous sub-sections.</p><p>Alternatively
create a custom <a shape="rect" class="external-link" href="https://github.com/apache/cxf/blob/master/rt/rs/security/oauth-parent/oauth2/src/main/java/org/apache/cxf/rs/security/oauth2/provider/AccessTokenGrantHandler.java"
rel="nofollow">AccessTokenGrantHandler</a> and register it with AccessTokenService.
Additionally, consider providing a related&#160;<a shape="rect" class="external-link"
href="https://github.com/apache/cxf/blob/master/rt/rs/security/oauth-parent/oauth2/src/main/java/org/apache/cxf/rs/security/oauth2/common/AccessTokenGrant.java"
rel="nofollow">AccessTokenGrant</a> implementation for making it easy for the client
code to request a new access token with this custom grant.</p><h2 id="JAX-RSOAuth2-RedirectionFlowFilters">Redirection
Flow Filters</h2><p><a shape="rect" class="external-link" href="ht
 tps://github.com/apache/cxf/blob/master/rt/rs/security/oauth-parent/oauth2/src/main/java/org/apache/cxf/rs/security/oauth2/provider/AuthorizationRequestFilter.java"
rel="nofollow">AuthorizationRequestFilter</a> implementations can be registered with
AuthorizationCodeGrantService or ImplicitGrantService in order to pre-process code requests.
For example, <a shape="rect" class="external-link" href="https://github.com/apache/cxf/blob/master/rt/rs/security/oauth-parent/oauth2/src/main/java/org/apache/cxf/rs/security/oauth2/grants/code/JwtRequestCodeFilter.java"
rel="nofollow">JwtRequestCodeFilter</a> can be used to process JWS-signed or JWE-encrypted
code requests.</p><p><a shape="rect" class="external-link" href="https://github.com/apache/cxf/blob/master/rt/rs/security/oauth-parent/oauth2/src/main/java/org/apache/cxf/rs/security/oauth2/provider/AuthorizationCodeResponseFilter.java"
rel="nofollow">AuthorizationCodeResponseFilter</a> implementations can be registered
with AuthorizationCo
 deService in order to post-process code responses.</p><h2 id="JAX-RSOAuth2-AccessTokenResponseFilters">AccessTokenResponse
Filters</h2><p><a shape="rect" class="external-link" href="https://github.com/apache/cxf/blob/master/rt/rs/security/oauth-parent/oauth2/src/main/java/org/apache/cxf/rs/security/oauth2/provider/AccessTokenResponseFilter.java"
rel="nofollow">AccessTokenResponseFilter</a> implementations can be registered with
AccessTokenService in order to post-process access token responses. For example,&#160;
OIDC IdToken can be added to a response with a <a shape="rect" class="external-link" href="https://github.com/apache/cxf/blob/master/rt/rs/security/sso/oidc/src/main/java/org/apache/cxf/rs/security/oidc/idp/IdTokenResponseFilter.java"
rel="nofollow">IdTokenResponseFilter</a>.</p><h2 id="JAX-RSOAuth2-PreAuthorizedaccesstokens">PreAuthorized
access tokens</h2><p>When working with the flows which require the end users/resource
owners explicitly authorizing clients (for example
 , as in the case of redirection-based flows), using pre-authorized access tokens is one option
to minimize the need for the end-user intervention. <br clear="none"> OAuthDataProvider
is always checked first if the pre-authorized access token for a given Client exists and if
yes then it will be returned immediately, without starting the authorization process involving
the end user (as required by some flows).</p><p>Consider providing a user interface
which will let the end users/resource owners to pre-authorize specific clients early. Note,
a CXF service for supporting the users pre-authorizing the clients or revoking the tokens
for some of the clients may be introduced in the future.</p><p>Also note that
using a refresh token grant may further help with minimizing the end user involvement, in
cases when the current access token has expired.</p><h2 id="JAX-RSOAuth2-Pre-registeredscopes">Pre-registered
scopes</h2><p>Clients can register custom scopes they will be expected to use
and t
 hen avoid specifying the scopes when requesting the code grants or access tokens.<br clear="none">
Alternatively it makes it easier to support so called wild-card scopes. For example, a client
pre-registers a scope "update" and actually uses an "update-7" scope: Redirection-based services
and access token grants can be configured to do a partial scope match, in this case, validate
that "update-7" starts from "update"</p><h2 id="JAX-RSOAuth2-WritingOAuthDataProvider">Writing
OAuthDataProvider</h2><p>Using CXF OAuth service implementations will help a lot
with setting up an OAuth server. As you can see from the above sections, these services rely
on a custom <a shape="rect" class="external-link" href="https://github.com/apache/cxf/blob/master/rt/rs/security/oauth-parent/oauth2/src/main/java/org/apache/cxf/rs/security/oauth2/provider/OAuthDataProvider.java"
rel="nofollow">OAuthDataProvider</a> implementation.</p><p>The main task
of <a shape="rect" class="external-link" href="https://gi
 thub.com/apache/cxf/blob/master/rt/rs/security/oauth-parent/oauth2/src/main/java/org/apache/cxf/rs/security/oauth2/provider/OAuthDataProvider.java"
rel="nofollow">OAuthDataProvider</a> is to persist and generate access tokens. Additionally,
as noted above, <a shape="rect" class="external-link" href="https://github.com/apache/cxf/blob/master/rt/rs/security/oauth-parent/oauth2/src/main/java/org/apache/cxf/rs/security/oauth2/grants/code/AuthorizationCodeDataProvider.java"
rel="nofollow">AuthorizationCodeDataProvider</a> needs to persist and remove the
code grant registrations. The way it's done is really application-specific. Consider starting
with a basic memory based implementation and then move on to keeping the data in some DB.</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="https://github.com/apache/cxf/blob/master/rt/rs/security/oauth-parent/oauth2/src/main/java/org/apache/cx
 f/rs/security/oauth2/common/OAuthPermission.java" rel="nofollow">OAuthPermission</a>s.
AuthorizationCodeGrantService and OAuth2 security filters will depend on it (assuming scopes
are used in the first place).&#160;</p><h3 id="JAX-RSOAuth2-DefaultProviders">Default
Providers</h3><p>CXF 3.1.7 ships JPA2 (<a shape="rect" class="external-link"
href="https://github.com/apache/cxf/blob/master/rt/rs/security/oauth-parent/oauth2/src/main/java/org/apache/cxf/rs/security/oauth2/provider/JPAOAuthDataProvider.java"
rel="nofollow">JPAOAuthDataProvider</a> and <a shape="rect" class="external-link"
href="https://github.com/apache/cxf/blob/master/rt/rs/security/oauth-parent/oauth2/src/main/java/org/apache/cxf/rs/security/oauth2/grants/code/JPACodeDataProvider.java"
rel="nofollow">JPACodeDataProvider</a>), Ehcache (<a shape="rect" class="external-link"
href="https://github.com/apache/cxf/blob/master/rt/rs/security/oauth-parent/oauth2/src/main/java/org/apache/cxf/rs/security/oauth2/provider/DefaultE
 HCacheOAuthDataProvider.java" rel="nofollow">DefaultEHCacheOAuthDataProvider</a>
and <a shape="rect" class="external-link" href="https://github.com/apache/cxf/blob/master/rt/rs/security/oauth-parent/oauth2/src/main/java/org/apache/cxf/rs/security/oauth2/grants/code/DefaultEHCacheCodeDataProvider.java"
rel="nofollow">DefaultEHCacheCodeDataProvider</a>) and JCache (<a shape="rect"
class="external-link" href="https://github.com/apache/cxf/blob/master/rt/rs/security/oauth-parent/oauth2/src/main/java/org/apache/cxf/rs/security/oauth2/provider/JCacheOAuthDataProvider.java"
rel="nofollow">JCacheOAuthDataProvider</a> and <a shape="rect" class="external-link"
href="https://github.com/apache/cxf/blob/master/rt/rs/security/oauth-parent/oauth2/src/main/java/org/apache/cxf/rs/security/oauth2/grants/code/JCacheCodeDataProvider.java"
rel="nofollow">JCacheCodeDataProvider</a>) provider implementations which take care
of all the persistence tasks: saving or removing registered clients, tokens and co
 de grants. These providers can be easily customized.</p><p>Custom implementations
can also extend&#160; <a shape="rect" class="external-link" href="https://github.com/apache/cxf/blob/master/rt/rs/security/oauth-parent/oauth2/src/main/java/org/apache/cxf/rs/security/oauth2/provider/AbstractOAuthDataProvider.java"
rel="nofollow">AbstractOAuthDataProvider</a> or <a shape="rect" class="external-link"
href="https://github.com/apache/cxf/blob/master/rt/rs/security/oauth-parent/oauth2/src/main/java/org/apache/cxf/rs/security/oauth2/grants/code/AbstractCodeDataProvider.java"
rel="nofollow">AbstractCodeDataProvider</a>&#160; and only implement their abstract
persistence related methods or further customize some of their code.</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 t
 o 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><pre>&#160;</pre><h4 id="JAX-RSOAuth2-JWTTokens">JWT
Tokens</h4><p>JWT Token can be JWE-encrypted and the encrypted string passed to
ServerAccessToken as access token id parameter.</p><p>See <a shape="rect" href="http://cxf.apache.org/docs/jax-rs-jose.html">JAX-RS
JOSE</a> wiki page for more information on how to sign and encrypt JSON Web Tokens.</p><p><a
shape="rect" class="external-link" href="https://github.com/apache/cxf/blob/master/rt/rs/security/oauth-parent/oauth2/src/main/java/org/apache/cxf/rs/security/oauth2/tokens/jwt/JwtAccessTokenUtils.java"
rel="nofollow">JwtAccessTokenUtils </a>provides utility method for encrypting and
decrypting an access token represented as JWT.</p><p>Note more support for JWT
access tokens is on the way.</p><h4 id="JAX-RSOAuth2-Customtokens">Custom tokens</h4><p>If
needed, users can use their own custom token types, with the only restriction that the custom
token type implementations have to extend org.apache.cxf.rs.security.oauth2.co
 mmon.ServerAccessToken.</p><h4 id="JAX-RSOAuth2-SimpleTokensandAudience">Simple
Tokens and Audience</h4><p>Starting from CXF 2.7.7 an <a shape="rect" class="external-link"
href="http://tools.ietf.org/html/draft-tschofenig-oauth-audience-00" rel="nofollow">audience</a>
parameter is supported during the client token requests.</p><h3 id="JAX-RSOAuth2-OAuthJSONProvider">OAuthJSONProvider</h3><p>org.apache.cxf.rs.security.oauth2.provider.OAuthJSONProvider
is a JAX-RS MessageBodyWriter which supports returning ClientAccessToken and OAuthError representations
to the client in a JSON format required by OAuth2 spec. It is also a JAX-RS MessageBodyReader
that is used by client OAuthClientUtils (see below) to read the responses from AccessTokenService.</p><p>Register
it as a provider with a JAXRS AccessTokenService endpoint.</p><p>Alternatively,
if you prefer, a custom MessageBodyWriter implementation can be registered instead.</p><h2
id="JAX-RSOAuth2-AccessTokenValidationService">Access Token
  Validation Service</h2><h3 id="JAX-RSOAuth2-AccessTokenValidatorService">AccessTokenValidatorService</h3><p>The
<a shape="rect" class="external-link" href="https://github.com/apache/cxf/blob/master/rt/rs/security/oauth-parent/oauth2/src/main/java/org/apache/cxf/rs/security/oauth2/services/AccessTokenValidatorService.java"
rel="nofollow">AccessTokenValidatorService</a> is a CXF specific OAuth2 service for
accepting the remote access token validation requests. OAuthRequestFilter needs to be injected
with <a shape="rect" class="external-link" href="https://github.com/apache/cxf/blob/master/rt/rs/security/oauth-parent/oauth2/src/main/java/org/apache/cxf/rs/security/oauth2/filters/AccessTokenValidatorClient.java"
rel="nofollow">AccessTokenValidatorClient</a> which will ask AccessTokenValidatorService
to return the information relevant to the current access token, before setting up a security
context.</p><h3 id="JAX-RSOAuth2-TokenIntrospectionService">TokenIntrospectionService</h3><p>The
  <a shape="rect" class="external-link" href="https://github.com/apache/cxf/blob/master/rt/rs/security/oauth-parent/oauth2/src/main/java/org/apache/cxf/rs/security/oauth2/services/TokenIntrospectionService.java"
rel="nofollow">TokenIntrospectionService</a> is a standard OAuth2 service for accepting
the remote access token introspection requests. See <a shape="rect" class="external-link"
href="https://tools.ietf.org/html/rfc7662" rel="nofollow">RFC 7662</a>. OAuthRequestFilter
needs to be injected with <a shape="rect" class="external-link" href="https://github.com/apache/cxf/blob/master/rt/rs/security/oauth-parent/oauth2/src/main/java/org/apache/cxf/rs/security/oauth2/filters/AccessTokenIntrospectionClient.java"
rel="nofollow">AccessTokenIntrospectionClient.</a></p><h2 id="JAX-RSOAuth2-TokenRevocationService">TokenRevocationService</h2><p><a
shape="rect" class="external-link" href="https://github.com/apache/cxf/blob/master/rt/rs/security/oauth-parent/oauth2/src/main/java/org/apache/cx
 f/rs/security/oauth2/services/TokenRevocationService.java" rel="nofollow">TokenRevocationService</a>
is a simple OAuth2 service supporting the clients wishing to revoke the access or refresh
tokens they own themselves, please see <a shape="rect" class="external-link" href="http://tools.ietf.org/html/draft-ietf-oauth-revocation-09"
rel="nofollow">OAuth2 Token Revocation Draft</a> for more information.</p><p>TokenRevocationService
and AccessTokenService share the same code which enforces that the clients have been correctly
authenticated.</p><p>Note, OAuthDataProvider implementations processing a revocation
request should simply ignore the invalid tokens as recommended by the specification which
will let TokenRevocationService return HTTP 200 which is done to minimize a possible attack
surface (specifically for bad clients not to see if their requests failed or succeeded) and
throw the exceptions only if the token revocation feature is not currently supported.</p><h2
id="JAX-RSOAuth2-
 SupportedGrants">Supported Grants</h2><p>The following subsections briefly
describe how the well-known grant types can be supported on the server side. Please also check
the "Client Side Support" section on how to use the related <a shape="rect" class="external-link"
href="https://github.com/apache/cxf/blob/master/rt/rs/security/oauth-parent/oauth2/src/main/java/org/apache/cxf/rs/security/oauth2/common/AccessTokenGrant.java"
rel="nofollow">AccessTokenGrant</a> implementations to request the access tokens.</p><h3
id="JAX-RSOAuth2-AuthorizationCode">Authorization Code</h3><p>As described
above, <a shape="rect" class="external-link" href="https://github.com/apache/cxf/blob/master/rt/rs/security/oauth-parent/oauth2/src/main/java/org/apache/cxf/rs/security/oauth2/services/AuthorizationCodeGrantService.java"
rel="nofollow">AuthorizationCodeGrantService</a> service and <a shape="rect" class="external-link"
href="https://github.com/apache/cxf/blob/master/rt/rs/security/oauth-parent/oauth2/s
 rc/main/java/org/apache/cxf/rs/security/oauth2/grants/code/AuthorizationCodeDataProvider.java"
rel="nofollow">AuthorizationCodeDataProvider</a> data provider can support a redirection-based
Authorization Code flow.</p><p>The code that the client receives in the end of
the redirection process will need to be exchanged for a new access token with AccessTokenService.
CXF-based clients can use a helper <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/AuthorizationCodeGrant.java">AuthorizationCodeGrant</a>
bean to request a new access token with OAuthClientUtils.</p><h3 id="JAX-RSOAuth2-Implicit">Implicit</h3><p>Implicit
grant is supported the same way Authorization Code grant is except that no code is created,
a token is issued immediately and returned to the client running within a web browser.</p><p><a
shape="rect" class="external-link" href="https://gith
 ub.com/apache/cxf/blob/master/rt/rs/security/oauth-parent/oauth2/src/main/java/org/apache/cxf/rs/security/oauth2/services/ImplicitGrantService.java"
rel="nofollow">ImplicitGrantService</a> service asks <a shape="rect" class="external-link"
href="https://github.com/apache/cxf/blob/master/rt/rs/security/oauth-parent/oauth2/src/main/java/org/apache/cxf/rs/security/oauth2/provider/OAuthDataProvider.java"
rel="nofollow">OAuthDataProvider</a> data provider to issue a new token after a user
has approved it.</p><p>Note the only difference is the use of ImplicitGrantService
instead of AuthorizationCodeGrantService.</p><p>Also note that when an Implicit
grant client (running within a browser) replaces the code grant for a new access token and
tries to access the end user's resource, Cross Origin Resource Sharing (CORS) support will
most likely need to be enabled on the end user's resource server.<br clear="none"> The
simplest approach is to register a CXF <a shape="rect" href="http://cxf.apac
 he.org/docs/jax-rs-cors.html">CORS filter</a>, right before OAuth2 filter (see on
it below).</p><p>Starting from CXF 2.7.5 it is possible to request ImplicitGrantService
to return a registered Client id to the browser-hosted client. This is recommended so that
the client can verify that the token is meant to be delivered to this client.</p><h3
id="JAX-RSOAuth2-ClientCredentials">Client Credentials</h3><p>Register <a
shape="rect" class="external-link" href="https://github.com/apache/cxf/blob/master/rt/rs/security/oauth-parent/oauth2/src/main/java/org/apache/cxf/rs/security/oauth2/grants/clientcred/ClientCredentialsGrantHandler.java"
rel="nofollow">ClientCredentialsGrantHandler</a> handler with AccessTokenService
for this grant be supported.</p><p>CXF-based clients can use a helper <a shape="rect"
class="external-link" href="https://github.com/apache/cxf/blob/master/rt/rs/security/oauth-parent/oauth2/src/main/java/org/apache/cxf/rs/security/oauth2/grants/clientcred/ClientCredentialsGr
 ant.java" rel="nofollow">ClientCredentialsGrant</a> bean to request a new access
token with OAuthClientUtils.</p><h3 id="JAX-RSOAuth2-ResourceOwnerPasswordCredentials">Resource
Owner Password Credentials</h3><p>Register <a shape="rect" class="external-link"
href="https://github.com/apache/cxf/blob/master/rt/rs/security/oauth-parent/oauth2/src/main/java/org/apache/cxf/rs/security/oauth2/grants/owner/ResourceOwnerGrantHandler.java"
rel="nofollow">ResourceOwnerGrantHandler</a> handler with AccessTokenService for
this grant be supported.</p><p>CXF-based clients can use a helper <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/owner/ResourceOwnerGrant.java">ResourceOwnerGrant</a>
bean to request a new access token with OAuthClientUtils.</p><h3 id="JAX-RSOAuth2-RefreshToken">Refresh
Token</h3><p>The client can issue a refresh token grant if the current access
toke
 n it owns has expired or been revoked and the refresh token was issued alongside with the
access token which is now invalid and get the new, 'refreshed' access token. This can allow
the client to avoid seeking a new authorization approval from the end user.</p><p>Register
<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/refresh/RefreshTokenGrantHandler.java">RefreshTokenGrantHandler</a>
handler with AccessTokenService for this grant be supported. Note this grant handler is only
useful for refreshing the existing access token, so one or more of the other grant handlers
(Authorization Code, Implicit, etc) will also have to be registered with AccessTokenService.</p><p>CXF-based
clients can use a helper <a shape="rect" class="external-link" href="https://github.com/apache/cxf/blob/master/rt/rs/security/oauth-parent/oauth2/src/main/java/org/apache/cxf/rs/security
 /oauth2/grants/owner/ResourceOwnerGrant.java" rel="nofollow">RefreshTokenGrant</a>
bean to request a new access token with OAuthClientUtils.</p><h3 id="JAX-RSOAuth2-SAMLandJWTAssertions">SAML
and JWT Assertions</h3><p><a shape="rect" class="external-link" href="https://tools.ietf.org/html/rfc7522"
rel="nofollow">SAML2 assertions</a> and <a shape="rect" class="external-link"
href="https://tools.ietf.org/html/rfc7523" rel="nofollow">JWT assertions</a> can
be used as token grants.</p><p>JWT assertion grants are supported in <a shape="rect"
class="external-link" href="https://github.com/apache/cxf/tree/master/rt/rs/security/oauth-parent/oauth2/src/main/java/org/apache/cxf/rs/security/oauth2/grants/jwt"
rel="nofollow">this package</a>. <a shape="rect" class="external-link" href="https://github.com/apache/cxf/blob/master/rt/rs/security/oauth-parent/oauth2/src/main/java/org/apache/cxf/rs/security/oauth2/grants/jwt/JwtBearerAuthHandler.java"
rel="nofollow">JwtBearerAuthHandler</a> can be us
 ed as a generic client authentication filter (where the client authenticated with JWT token
as opposed to with a username:password pair, etc).</p><p>Please also see <a
shape="rect" href="jaxrs-oauth2-assertions.html">JAXRS OAuth2 Assertions</a> section
for more information.</p><p>&#160;</p><h3 id="JAX-RSOAuth2-CustomGrants">Custom
Grants</h3><p>If you need to customize the way the well-known grant requests are
handled then consider extending one of the grant handlers listed in the previous sub-sections.</p><p>Alternatively
create a custom <a shape="rect" class="external-link" href="https://github.com/apache/cxf/blob/master/rt/rs/security/oauth-parent/oauth2/src/main/java/org/apache/cxf/rs/security/oauth2/provider/AccessTokenGrantHandler.java"
rel="nofollow">AccessTokenGrantHandler</a> and register it with AccessTokenService.
Additionally, consider providing a related&#160;<a shape="rect" class="external-link"
href="https://github.com/apache/cxf/blob/master/rt/rs/security/oauth-paren
 t/oauth2/src/main/java/org/apache/cxf/rs/security/oauth2/common/AccessTokenGrant.java" rel="nofollow">AccessTokenGrant</a>
implementation for making it easy for the client code to request a new access token with this
custom grant.</p><h2 id="JAX-RSOAuth2-RedirectionFlowFilters">Redirection Flow
Filters</h2><p><a shape="rect" class="external-link" href="https://github.com/apache/cxf/blob/master/rt/rs/security/oauth-parent/oauth2/src/main/java/org/apache/cxf/rs/security/oauth2/provider/AuthorizationRequestFilter.java"
rel="nofollow">AuthorizationRequestFilter</a> implementations can be registered with
AuthorizationCodeGrantService or ImplicitGrantService in order to pre-process code requests.
For example, <a shape="rect" class="external-link" href="https://github.com/apache/cxf/blob/master/rt/rs/security/oauth-parent/oauth2/src/main/java/org/apache/cxf/rs/security/oauth2/grants/code/JwtRequestCodeFilter.java"
rel="nofollow">JwtRequestCodeFilter</a> can be used to process JWS-signed or
  JWE-encrypted code requests.</p><p><a shape="rect" class="external-link"
href="https://github.com/apache/cxf/blob/master/rt/rs/security/oauth-parent/oauth2/src/main/java/org/apache/cxf/rs/security/oauth2/provider/AuthorizationCodeResponseFilter.java"
rel="nofollow">AuthorizationCodeResponseFilter</a> implementations can be registered
with AuthorizationCodeService in order to post-process code responses.</p><h2 id="JAX-RSOAuth2-AccessTokenResponseFilters">AccessTokenResponse
Filters</h2><p><a shape="rect" class="external-link" href="https://github.com/apache/cxf/blob/master/rt/rs/security/oauth-parent/oauth2/src/main/java/org/apache/cxf/rs/security/oauth2/provider/AccessTokenResponseFilter.java"
rel="nofollow">AccessTokenResponseFilter</a> implementations can be registered with
AccessTokenService in order to post-process access token responses. For example,&#160;
OIDC IdToken can be added to a response with a <a shape="rect" class="external-link" href="https://github.com/apache/cxf/
 blob/master/rt/rs/security/sso/oidc/src/main/java/org/apache/cxf/rs/security/oidc/idp/IdTokenResponseFilter.java"
rel="nofollow">IdTokenResponseFilter</a>.</p><h2 id="JAX-RSOAuth2-PreAuthorizedaccesstokens">PreAuthorized
access tokens</h2><p>When working with the flows which require the end users/resource
owners explicitly authorizing clients (for example, as in the case of redirection-based flows),
using pre-authorized access tokens is one option to minimize the need for the end-user intervention.
<br clear="none"> OAuthDataProvider is always checked first if the pre-authorized access
token for a given Client exists and if yes then it will be returned immediately, without starting
the authorization process involving the end user (as required by some flows).</p><p>Consider
providing a user interface which will let the end users/resource owners to pre-authorize specific
clients early. Note, a CXF service for supporting the users pre-authorizing the clients or
revoking the tokens for 
 some of the clients may be introduced in the future.</p><p>Also note that using
a refresh token grant may further help with minimizing the end user involvement, in cases
when the current access token has expired.</p><h2 id="JAX-RSOAuth2-Pre-registeredscopes">Pre-registered
scopes</h2><p>Clients can register custom scopes they will be expected to use
and then avoid specifying the scopes when requesting the code grants or access tokens.<br
clear="none"> Alternatively it makes it easier to support so called wild-card scopes. For
example, a client pre-registers a scope "update" and actually uses an "update-7" scope: Redirection-based
services and access token grants can be configured to do a partial scope match, in this case,
validate that "update-7" starts from "update"</p><h2 id="JAX-RSOAuth2-WritingOAuthDataProvider">Writing
OAuthDataProvider</h2><p>Using CXF OAuth service implementations will help a lot
with setting up an OAuth server. As you can see from the above sections, these s
 ervices rely on a custom <a shape="rect" class="external-link" href="https://github.com/apache/cxf/blob/master/rt/rs/security/oauth-parent/oauth2/src/main/java/org/apache/cxf/rs/security/oauth2/provider/OAuthDataProvider.java"
rel="nofollow">OAuthDataProvider</a> implementation.</p><p>The main task
of <a shape="rect" class="external-link" href="https://github.com/apache/cxf/blob/master/rt/rs/security/oauth-parent/oauth2/src/main/java/org/apache/cxf/rs/security/oauth2/provider/OAuthDataProvider.java"
rel="nofollow">OAuthDataProvider</a> is to persist and generate access tokens. Additionally,
as noted above, <a shape="rect" class="external-link" href="https://github.com/apache/cxf/blob/master/rt/rs/security/oauth-parent/oauth2/src/main/java/org/apache/cxf/rs/security/oauth2/grants/code/AuthorizationCodeDataProvider.java"
rel="nofollow">AuthorizationCodeDataProvider</a> needs to persist and remove the
code grant registrations. The way it's done is really application-specific. Consider 
 starting with a basic memory based implementation and then move on to keeping the data in
some DB.</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="https://github.com/apache/cxf/blob/master/rt/rs/security/oauth-parent/oauth2/src/main/java/org/apache/cxf/rs/security/oauth2/common/OAuthPermission.java"
rel="nofollow">OAuthPermission</a>s. AuthorizationCodeGrantService and OAuth2 security
filters will depend on it (assuming scopes are used in the first place).&#160;</p><h3
id="JAX-RSOAuth2-DefaultProviders">Default Providers</h3><p>CXF 3.1.7 ships
JPA2 (<a shape="rect" class="external-link" href="https://github.com/apache/cxf/blob/master/rt/rs/security/oauth-parent/oauth2/src/main/java/org/apache/cxf/rs/security/oauth2/provider/JPAOAuthDataProvider.java"
rel="nofollow">JPAOAuthDataProvider</a> and <a shape="rect" class="external-link"
href="https://github.com/apache/cxf/blob/master/
 rt/rs/security/oauth-parent/oauth2/src/main/java/org/apache/cxf/rs/security/oauth2/grants/code/JPACodeDataProvider.java"
rel="nofollow">JPACodeDataProvider</a>), Ehcache (<a shape="rect" class="external-link"
href="https://github.com/apache/cxf/blob/master/rt/rs/security/oauth-parent/oauth2/src/main/java/org/apache/cxf/rs/security/oauth2/provider/DefaultEHCacheOAuthDataProvider.java"
rel="nofollow">DefaultEHCacheOAuthDataProvider</a> and <a shape="rect" class="external-link"
href="https://github.com/apache/cxf/blob/master/rt/rs/security/oauth-parent/oauth2/src/main/java/org/apache/cxf/rs/security/oauth2/grants/code/DefaultEHCacheCodeDataProvider.java"
rel="nofollow">DefaultEHCacheCodeDataProvider</a>) and JCache (<a shape="rect"
class="external-link" href="https://github.com/apache/cxf/blob/master/rt/rs/security/oauth-parent/oauth2/src/main/java/org/apache/cxf/rs/security/oauth2/provider/JCacheOAuthDataProvider.java"
rel="nofollow">JCacheOAuthDataProvider</a> and <a shape="rect" cla
 ss="external-link" href="https://github.com/apache/cxf/blob/master/rt/rs/security/oauth-parent/oauth2/src/main/java/org/apache/cxf/rs/security/oauth2/grants/code/JCacheCodeDataProvider.java"
rel="nofollow">JCacheCodeDataProvider</a>) provider implementations which take care
of all the persistence tasks: saving or removing registered clients, tokens and code grants.
These providers can be easily customized.</p><p>Custom implementations can also
extend&#160; <a shape="rect" class="external-link" href="https://github.com/apache/cxf/blob/master/rt/rs/security/oauth-parent/oauth2/src/main/java/org/apache/cxf/rs/security/oauth2/provider/AbstractOAuthDataProvider.java"
rel="nofollow">AbstractOAuthDataProvider</a> or <a shape="rect" class="external-link"
href="https://github.com/apache/cxf/blob/master/rt/rs/security/oauth-parent/oauth2/src/main/java/org/apache/cxf/rs/security/oauth2/grants/code/AbstractCodeDataProvider.java"
rel="nofollow">AbstractCodeDataProvider</a>&#160; and only impleme
 nt their abstract persistence related methods or further customize some of their code.</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;">&lt;!--
implements OAuthDataProvider --&gt;
 &lt;bean id="oauthProvider" class="oauth.manager.OAuthManager"/&gt;
      




Mime
View raw message