Author: buildbot
Date: Mon May 25 15:56:42 2020
New Revision: 1060906
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 May 25 15:56:42
2020
@@ -119,11 +119,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.rbtoc1588067795049 {padding: 0px;}
-div.rbtoc1588067795049 ul {list-style: disc;margin-left: 0px;}
-div.rbtoc1588067795049 li {margin-left: 0px;padding-left: 0px;}
+div.rbtoc1590422163223 {padding: 0px;}
+div.rbtoc1590422163223 ul {list-style: disc;margin-left: 0px;}
+div.rbtoc1590422163223 li {margin-left: 0px;padding-left: 0px;}
-/*]]>*/</style></p><div class="toc-macro rbtoc1588067795049">
+/*]]>*/</style></p><div class="toc-macro rbtoc1590422163223">
<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>
@@ -155,14 +155,14 @@ div.rbtoc1588067795049 li {margin-left:
<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>
</li></ul>
-</div><h1 id="JAX-RSOAuth2-Introduction">Introduction</h1><p>New:</p><ul
style="list-style-type: square;"><li>JCache and JPA2 OAuthDataProviders (as
well as Ehcache 2.x prior to CXF 3.3.0) can represent access tokens in
JWT</li><li>Client Certificate Authentication and Token Binding is
supported</li><li>DynamicRegistrationService is enhanced<br clear="none"><br
clear="none"></li></ul><p>CXF provides the implementation of <a shape="rect"
class="external-link" href="http://tools.ietf.org/html/rfc6749";
rel="nofollow">OAuth 2.0</a>. See also the <a shape="rect"
href="jax-rs-oauth.html">JAX-RS OAuth</a> page for information about OAuth
1.0.</p><p>Authorization Code, Implicit, Client Credentials, Resource Owner
Password Credentials, Refresh Token, SAML2 Assertions and JWT assertion grants
are currently supported.</p><p>Custom grant handlers can be
registered.</p><p>OAuth2 is a new protocol which offers a complex yet elegant
solution toward helping end users (resource owners) authorize thi
rd-party providers to access their resources.</p><p>The OAuth2 flow which is
closely related to the original OAuth 1.0 3-leg flow is called Authorization
Code and involves 3 parties: the end user, the third party service (client) and
the resource server which is protected by OAuth2 filters. Typically a client
offers a service feature that an end user requests and which requires the
former to access one or more protected resources on behalf of this user which
are located at the resource server. For example, the client may need to access
the end user's photos in order to print them and post to the user or read and
possibly update a user's calendar in order to make a booking.</p><p>In order to
make it happen, the third-party service application/client needs to register
itself with the OAuth2 server. This happens out-of-band and after the
registration the client gets back a client key and secret pair. Typically the
client is expected to provide the name and description of the applicatio
n, the application logo URI, one or more redirect URIs, and other information
that may help the OAuth2 authorization server to identify this client to the
end user at the authorization time.</p><p>From then on, the authorization code
flow works like this:<br clear="none">1. End User requests the third-party
service using a browser.</p><p>2. The client redirects the end user to OAuth2
Authorization Service, adding its client id, the state, redirect URI and the
optional scope to the target URI. The state parameter represents the current
end user's request, redirect URI - where the authorization code is expected to
be returned to, and the scope is the list of opaque permissions that the client
needs in order to access the protected resources.</p><p>3. Authorization
Service will retrieve the information about the client using its client id,
build an HTML form and return it to the end user. The form will ask the user if
a given third-party application can be allowed to access some resour
ces on behalf of this user.</p><p>4. If the user approves it then
Authorization Service will generate an authorization code and redirect the user
back to the redirect uri provided by the client, also adding a state parameter
to the redirect URI.</p><p>5. The client requests an access token from OAuth2
Access Token Service by providing an authorization code grant.</p><p>6. After
getting an access token token, the service finally proceeds with accessing the
current user's resources and completes the user's request.</p><p>As you can see
the flow can be complex yet it is very effective. A number of issues may need
to be taken care along the way such as managing expired tokens, making sure
that the OAuth2 security layer is functioning properly and is not interfering
with the end user itself trying to access its own resources, etc.</p><p>Please
check the <a shape="rect" class="external-link"
href="https://tools.ietf.org/html/rfc6749"; rel="nofollow">specification</a> as
well as other resou
rces available on the WEB for more information you may need to know about
OAuth2.</p><p>CXF JAX-RS gives the best effort to making this process as simple
as possible and requiring only a minimum effort on behalf of OAuth2 server
developers. It also offers the utility code for greatly simplifying the way the
third-party application can interact with the OAuth2 service endpoints.</p><h1
id="JAX-RSOAuth2-Mavendependencies">Maven dependencies</h1><div class="code
panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl">
+</div><h1 id="JAX-RSOAuth2-Introduction">Introduction</h1><p>New:</p><ul
style="list-style-type: square;"><li>JCache and JPA2 OAuthDataProviders (as
well as Ehcache 2.x prior to CXF 3.3.0) can represent access tokens in
JWT</li><li>Client Certificate Authentication and Token Binding is
supported</li><li>DynamicRegistrationService is enhanced<br clear="none"><br
clear="none"></li></ul><p>CXF provides an implementation of <a shape="rect"
class="external-link" href="http://tools.ietf.org/html/rfc6749";
rel="nofollow">OAuth 2.0</a>. See also the <a shape="rect"
href="jax-rs-oauth.html">JAX-RS OAuth</a> page for information about OAuth
1.0.</p><p>Authorization Code, Implicit, Client Credentials, Resource Owner
Password Credentials, Refresh Token, SAML2 Assertions and JWT assertion grants
are currently supported.</p><p>Custom grant handlers can be
registered.</p><p>OAuth2 is a protocol which offers a complex yet elegant
solution toward helping end users (resource owners) authorize third-pa
rty providers to access their resources.</p><p>The OAuth2 flow which is
closely related to the original OAuth 1.0 3-leg flow is called Authorization
Code and involves 3 parties: the end user, the third party service (client) and
the resource server which is protected by OAuth2 filters. Typically a client
offers a service that an end user requests and which requires the former to
access one or more protected resources on behalf of this user which are located
at the resource server. For example, the client may need to access the end
user's photos in order to print them and post to the user or read and possibly
update a user's calendar in order to make a booking.</p><p>In order to make
this happen, the third-party service application/client needs to register
itself with the OAuth2 server. This happens out-of-band and after the
registration the client gets back a client key and secret pair. Typically the
client is expected to provide the name and description of the application, the
appl
ication logo URI, one or more redirect URIs, and other information that may
help the OAuth2 authorization server to identify this client to the end user at
authorization time.</p><p>From then on, the authorization code flow works like
this:<br clear="none">1. End User requests the third-party service using a
browser.</p><p>2. The client redirects the end user to OAuth2 Authorization
Service, adding its client id, the state, redirect URI and the optional scope
to the target URI. The state parameter represents the current end user's
request, redirect URI - where the authorization code is expected to be returned
to, and the scope is the list of opaque permissions that the client needs in
order to access the protected resources.</p><p>3. The Authorization Service
will retrieve the information about the client using its client id, build an
HTML form and return it to the end user. The form will ask the user if the
given third-party application can be allowed to access specified resources
on behalf of this user.</p><p>4. If the user approves, then the Authorization
Service will generate an authorization code and redirect the user back to the
redirect uri provided by the client, also adding a state parameter to the
redirect URI.</p><p>5. The client requests an access token from OAuth2 Access
Token Service by providing an authorization code grant.</p><p>6. After getting
an access token, the service finally proceeds with accessing the current user's
resources and completes the user's request.</p><p>As you can see the flow can
be complex yet it is very effective. A number of issues may need to be taken
care along the way such as managing expired tokens, making sure that the OAuth2
security layer is functioning properly and not interfering when the end user
itself is trying to access its own resources, etc.</p><p>Please check the <a
shape="rect" class="external-link" href="https://tools.ietf.org/html/rfc6749";
rel="nofollow">specification</a> as well as other resources ava
ilable on the web for more information you may need to know about
OAuth2.</p><p>CXF JAX-RS gives the best effort to making this process as simple
as possible and requiring only a minimum effort on behalf of OAuth2 server
developers. It also offers utility code for greatly simplifying the way
third-party applications can interact with the OAuth2 service endpoints.</p><h1
id="JAX-RSOAuth2-Mavendependencies">Maven dependencies</h1><div class="code
panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl">
<pre class="brush: java; gutter: false; theme: Default"><dependency>
<groupId>org.apache.cxf</groupId>
<artifactId>cxf-rt-rs-security-oauth2</artifactId>
<version>3.1.7</version>
</dependency>
</pre>
-</div></div><h1 id="JAX-RSOAuth2-ClientRegistration">Client
Registration</h1><p>Client Registration is typically done out of band, with the
the dynamic client registration being also possible.<br clear="none">The client
registration service will offer an HTML form where the clients will enter their
details, see 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/common/Client.java";
rel="nofollow">Client</a> bean for the currently supported
properties.</p><p>See <a shape="rect" class="external-link"
href="https://github.com/apache/cxf-fediz/blob/master/services/oidc/src/main/java/org/apache/cxf/fediz/service/oidc/clients/ClientRegistrationService.java";
rel="nofollow">this JAX-RS service implementation</a> for one possible
approach.</p><h1 id="JAX-RSOAuth2-DevelopingOAuth2Servers">Developing OAuth2
Servers</h1><p>OAuth2 server is the core piece of the complete OAuth2-
based solution. Typically it contains 3 services for:<br clear="none">1.
Authorizing request tokens by asking the end users to let clients access some
of their resources and returning the<br clear="none">grants back to the client
(Authorization Service)<br clear="none">2. Exchanging the token grants for
access tokens (Access Token Service)</p><p>3. Validating access
tokens</p><p><br clear="none"></p><p>CXF offers several JAX-RS service
implementations that can be used to create the OAuth2 servers fast: <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> 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/services/ImplicitGrantService.java";
rel="nofollow">Im
plicitGrantService</a> for managing the redirection-based flows, as well as <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/AccessTokenService.java";
rel="nofollow">AccessTokenService</a> for exchanging the grants for new
tokens.</p><p>All of these services rely on the 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> which persists the access tokens and
converts the opaque scope values to the information that can be presented to
the users. Additionally, <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.ja
va" rel="nofollow">AuthorizationCodeDataProvider</a> is an <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> which can keep temporary information
about the authorization code grants which needs to be removed after the tokens
are requested in exchange.</p><p>Note that some grants that do not require the
redirection-based support, such as Client Credentials or SAML2 or JWT assertion
grants, and may only require an Access Token Service be operational.</p><p>If
your OAuth2 server does support either Authorization Code or Implicit flow then
either <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">AuthorizationCodeGra
ntService</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/services/ImplicitGrantService.java";
rel="nofollow">ImplicitGrantService</a> need to be registered. If both
services need to be supported then simply register two of them, but note each
service will have its own @Path segment, "/authorize"
and "/authorize-implicit". If you'd like both services listening on the
same path then use <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/AuthorizationService.java";
rel="nofollow">AuthorizationService</a> and inject <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.j
ava" rel="nofollow">AuthorizationCodeGrantService</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/services/ImplicitGrantService.java";
rel="nofollow">ImplicitGrantService</a> beans into it.</p><p>If no
AuthorizationCode redirection flow is supported then implementing <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 sufficent.</p><p>Writing your own <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> or <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/provider/OAuthDataProvider.java"
rel="nofollow">OAuthDataProvider</a> implementation is what is needed to get
the OAuth2 server up and running. In many cases all you need to do is to
persist or remove the Authorization Code Grant data, use one of the available
utility classes to create a new access token and also persist it or remove the
expired one, and finally convert the optional opaque scope values (if any are
supported) to a more view-able information.</p><p>CXF ships several default
provider implementations, see the section on wirting the providers
below.</p><p><br clear="none"></p><h2
id="JAX-RSOAuth2-AuthorizationService">Authorization Service</h2><p>The main
responsibility of OAuth2 Authorization Service is to present an end user with a
form asking the user to allow or deny the client accessing some of the user
resources. CXF offers  <a shape="rect" class="e
xternal-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> 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/services/ImplicitGrantService.java";
rel="nofollow">ImplicitGrantService</a> for accepting the redirection
requests, challenging the end users with the authorization forms, handling the
end user decisions and returning the results back to the clients.</p><p>One of
the differences between Authorization Code and Implicit flows is that in the
latter case the grant is the actual access token which is returned as the URI
fragment value to the client script running in the browser. The way the end
user is asked to authorize the client request is similar between the two flows.
In this se
ction we will assume that the Authorization Code flow is being used.</p><p>A
third-party client redirects the current user to AuthorizationCodeGrantService,
for example, here is how a redirection may happen:</p><div class="code panel
pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl">
+</div></div><h1 id="JAX-RSOAuth2-ClientRegistration">Client
Registration</h1><p>Client Registration is typically done out of band, with
dynamic client registration also being possible.<br clear="none">The client
registration service will offer an HTML form where the clients will enter their
details, see 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/common/Client.java";
rel="nofollow">Client</a> bean for currently supported properties.</p><p>See
<a shape="rect" class="external-link"
href="https://github.com/apache/cxf-fediz/blob/master/services/oidc/src/main/java/org/apache/cxf/fediz/service/oidc/clients/ClientRegistrationService.java";
rel="nofollow">this JAX-RS service implementation</a> for one possible
approach.</p><h1 id="JAX-RSOAuth2-DevelopingOAuth2Servers">Developing OAuth2
Servers</h1><p>OAuth2 server is the core piece of the complete OAuth2-based
solution. Typically it contains 3 services for:<br clear="none">1.
Authorizing request tokens by asking the end users to let clients access some
of their resources and returning the<br clear="none">grants back to the client
(Authorization Service)<br clear="none">2. Exchanging the token grants for
access tokens (Access Token Service)</p><p>3. Validating access
tokens</p><p><br clear="none"></p><p>CXF offers several JAX-RS service
implementations that can be used to create OAuth2 servers quickly: <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> 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/services/ImplicitGrantService.java";
rel="nofollow">Implicit
GrantService</a> for managing the redirection-based flows, as well as <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/AccessTokenService.java";
rel="nofollow">AccessTokenService</a> for exchanging the grants for new
tokens.</p><p>All of these services rely on the 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> which persists the access tokens and
converts the opaque scope values to the information that can be presented to
the users. Additionally, <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";
re
l="nofollow">AuthorizationCodeDataProvider</a> is an <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> which can keep temporary information
about the authorization code grants which needs to be removed after the tokens
are requested in exchange.</p><p>Note that some grants that do not require
redirection-based support, such as Client Credentials or SAML2 or JWT assertion
grants, and instead may require only an Access Token Service be
operational.</p><p>If your OAuth2 server does support either Authorization Code
or Implicit flow then either <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">AuthorizationCodeGrant
Service</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/services/ImplicitGrantService.java";
rel="nofollow">ImplicitGrantService</a> need to be registered. If both
services need to be supported then simply register two of them, but note each
service will have its own @Path segment, "/authorize"
and "/authorize-implicit". If you'd like both services listening on the
same path then use <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/AuthorizationService.java";
rel="nofollow">AuthorizationService</a> and inject 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/AuthorizationCodeGrantService
.java" rel="nofollow">AuthorizationCodeGrantService</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/services/ImplicitGrantService.java";
rel="nofollow">ImplicitGrantService</a> beans into it.</p><p>If no
AuthorizationCode redirection flow is supported then implementing <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 sufficient.</p><p>Writing your own <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> or <a shape="rect"
class="external-link" href="https://g
ithub.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 is what is needed to get
the OAuth2 server up and running. In many cases all you need to do is to
persist or remove the Authorization Code Grant data, use one of the available
utility classes to create a new access token and also persist it or remove the
expired one, and finally convert the optional opaque scope values (if any are
supported) to a more view-able information.</p><p>CXF ships several default
provider implementations, see the section on writing the providers
below.</p><p><br clear="none"></p><h2
id="JAX-RSOAuth2-AuthorizationService">Authorization Service</h2><p>The main
responsibility of OAuth2 Authorization Service is to present an end user with a
form asking the user to allow or deny the client to access specified resources
owned by the user. CXF offers  <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> 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/services/ImplicitGrantService.java";
rel="nofollow">ImplicitGrantService</a> for accepting redirection requests,
challenging end users with the authorization forms, handling the end user
decisions and returning the results back to the clients.</p><p>One of the
differences between Authorization Code and Implicit flows is that in the latter
case the grant is the actual access token which is returned as the URI fragment
value to the client script running in the browser. The way the end user is
asked to authorize the client request is similar between the two flows. In t
his section we will assume that the Authorization Code flow is being
used.</p><p>A third-party client redirects the current user to
AuthorizationCodeGrantService, for example, here is how a redirection may
happen:</p><div class="code panel pdl" style="border-width: 1px;"><div
class="codeContent panelContent pdl">
<pre class="brush: java; gutter: false; theme: Default">Response-Code: 303
Headers:
{Location=[http://localhost:8080/services/social/authorize?client_id=123456789&scope=updateCalendar-7&response_type=code
&redirect_uri=http%3A//localhost%3A8080/services/reservations/reserve/complete&state=1],
@@ -180,11 +180,11 @@ Referer=[http://localhost:8080/services/
...
}
</pre>
-</div></div><p>Note that the end user needs to authenticate. The Request URI
includes the client_id, custom scope value, response_type set to 'code', the
current request state and the redirect uri. Note the scope is optional - the
Authorization Service will usually allocate a default scope; however even if
the client does include an additional custom scope the end user may still not
approve it. The redirect uri is also optional, assuming one or more ones
redirect URIs have been provided at the client registration
time.</p><p>AuthorizationCodeGrantService will report a warning is no secure
HTTPS transport is used:</p><div class="code panel pdl" style="border-width:
1px;"><div class="codeContent panelContent pdl">
+</div></div><p>Note that the end user needs to authenticate. The Request URI
includes the client_id, custom scope value, response_type set to 'code', the
current request state and the redirect uri. Note the scope is optional - the
Authorization Service will usually allocate a default scope; however even if
the client does include an additional custom scope the end user may still not
approve it. The redirect uri is also optional, assuming one or more redirect
URIs were provided when the client was registered with the Authorization
Service.</p><p>The AuthorizationCodeGrantService will report a warning if no
secure HTTPS transport is used:</p><div class="code panel pdl"
style="border-width: 1px;"><div class="codeContent panelContent pdl">
<pre class="brush: java; gutter: false; theme: Default">12-Apr-2012 13:26:21
org.apache.cxf.rs.security.oauth2.services.AbstractOAuthService
checkTransportSecurity
WARNING: Unsecure HTTP, Transport Layer Security is recommended
</pre>
-</div></div><p>It can also be configured to reject the requests over insecure
HTTP transport.</p><p>AuthorizationCodeGrantService will retrieve the
information about 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/common/Client.java";
rel="nofollow">client application</a> to populate an instance 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/OAuthAuthorizationData.java";
rel="nofollow">OAuthAuthorizationData</a> bean and return it.
OAuthAuthorizationData contains application name and URI properties, optional
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">Permiss
ion</a>s and other properties which can be either presented to the user or
kept in the hidden form fields in order to uniquely identify the actual
authorization request when the end user returns the decision.</p><p>One
important OAuthAuthorizationData property is "authenticityToken". It is used
for validating that the current session has not been hijacked -
AuthorizationCodeGrantService generates a random key, stores it in a Servlet
HTTPSession instance and expects the returned authenticityToken value to match
it - this is a recommended approach and it also implies that the
authenticityToken value is hidden from a user, for example, it's kept in a
'hidden' form field. See also "User Session Authenticity" on how <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/SessionAuthenticityTokenProvider.java";
rel="nofollow">SessionAuthenticityTokenProvider</a> can hel
p.</p><p>A number of properties which have been submitted to the authorization
endpoint with the original user redirect need to be made available after the
user has been challenged with the autorization consent form, when the user
makes an authorization decision. These are properties such as 'clientId',
'state', 'redirectUri', and other properties, see <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/OAuthRedirectionState.java";
rel="nofollow">this class</a> which is extended by OAuthAuthorizationData. One
simple approach is to have a view handler preparing an authorization form 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/common/OAuthAuthorizationData.java";
rel="nofollow">OAuthAuthorizationData</a> to have these properties hidden i
n the form. Another option is to secure them in a session thus making the view
creation process much simpler, see "User Session Authenticity" for one
example.</p><p>The helper "replyTo" property is an absolute URI identifying the
AuthorizationCodeGrantService handler processing the user decision and can be
used by view handlers when building the forms or by other
OAuthAuthorizationData handlers.</p><p>So the populated OAuthAuthorizationData
is finally returned. Note that it's a JAXB XMLRootElement-annotated bean and
can be processed by registered JAXB or JSON providers given that
AuthorizationCodeGrantService supports producing "application/xml" and
"application/json" (See the OAuth Without Browser section below for more). But
in this case we have the end user working with a browser so an HTML form is
what is really expected back.</p><p>AuthorizationCodeGrantService supports
producing "text/html" and simply relies on a registered <a shape="rect"
href="http://cxf.apache.org/docs/jax-
rs-redirection.html#JAX-RSRedirection-WithRequestDispatcherProvider">RequestDispatcherProvider</a>
to set the OAuthAuthorizationData bean as an HttpServletRequest attribute and
redirect the response to a view handler (can be JSP or some other servlet) to
actually build the form and return it to the user. See the section below on
other alternatives on how a view can be created.</p><p>Assuming
RequestDispatcherProvider is used, the following example log shows the initial
response from AuthorizationCodeGrantService:</p><div class="code panel pdl"
style="border-width: 1px;"><div class="codeContent panelContent pdl">
+</div></div><p>It can also be configured to reject requests made over insecure
HTTP transport.</p><p>The AuthorizationCodeGrantService will retrieve the
information about 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/common/Client.java";
rel="nofollow">client application</a> to populate an instance 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/OAuthAuthorizationData.java";
rel="nofollow">OAuthAuthorizationData</a> bean and return it.
OAuthAuthorizationData contains application name and URI properties, optional
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">Pe
rmission</a>s and other properties which can be either presented to the user
or kept in the hidden form fields in order to uniquely identify the actual
authorization request when the end user returns the decision.</p><p>One
important OAuthAuthorizationData property is "authenticityToken". It is used
for validating that the current session has not been hijacked -
AuthorizationCodeGrantService generates a random key, stores it in a Servlet
HTTPSession instance and expects the returned authenticityToken value to match
it - this is a recommended approach and it also implies that the
authenticityToken value is hidden from a user, for example, it's kept in a
'hidden' form field. See also "User Session Authenticity" on how 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/provider/SessionAuthenticityTokenProvider.java";
rel="nofollow">SessionAuthenticityTokenProvider
</a> can help.</p><p>A number of properties which have been submitted to the
authorization endpoint with the original user redirect need to be made
available after the user has been challenged with the authorization consent
form, when the user makes an authorization decision. These are properties such
as 'clientId', 'state', 'redirectUri', and other properties, see <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/OAuthRedirectionState.java";
rel="nofollow">this class</a> which is extended by OAuthAuthorizationData. One
simple approach is to have a view handler prepare an authorization form 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/common/OAuthAuthorizationData.java";
rel="nofollow">OAuthAuthorizationData</a> to have these properti
es hidden in the form. Another option is to secure them in a session thus
making the view creation process much simpler, see "User Session Authenticity"
for one example.</p><p>The helper "replyTo" property is an absolute URI
identifying the AuthorizationCodeGrantService handler which processes the
user's decision and can be used by view handlers when building the forms or by
other OAuthAuthorizationData handlers.</p><p>So the populated
OAuthAuthorizationData is finally returned. Note that it's a JAXB
XMLRootElement-annotated bean and can be processed by registered JAXB or JSON
providers given that AuthorizationCodeGrantService supports producing
"application/xml" and "application/json" (See the OAuth Without Browser section
below for more). But in this case we have the end user working with a browser
so an HTML form is what is expected back.</p><p>The
AuthorizationCodeGrantService supports producing "text/html" and simply relies
on a registered <a shape="rect" href="http://cxf.apach
e.org/docs/jax-rs-redirection.html#JAX-RSRedirection-WithRequestDispatcherProvider">RequestDispatcherProvider</a>
to set the OAuthAuthorizationData bean as an HttpServletRequest attribute and
redirect the response to a view handler (can be JSP or some other servlet) to
actually build the form and return it to the user. See the section below on
other alternatives on how a view can be created.</p><p>Assuming
RequestDispatcherProvider is used, the following example log shows the initial
response from AuthorizationCodeGrantService:</p><div class="code panel pdl"
style="border-width: 1px;"><div class="codeContent panelContent pdl">
<pre class="brush: java; gutter: false; theme: Default">12-Apr-2012 13:26:21
org.apache.cxf.jaxrs.provider.RequestDispatcherProvider logRedirection
INFO: Setting an instance of
"org.apache.cxf.rs.security.oauth2.common.OAuthAuthorizationData" as
HttpServletRequest
attribute "data" and redirecting the response to "/forms/oauthAuthorize.jsp".
@@ -205,7 +205,7 @@ INFO: updateCalendar-7_status=allow&
&redirect_uri=http%3A%2F%2Flocalhost%3A8080%2Fservices%2Freservations%2Freserve%2Fcomplete
&session_authenticity_token=4f0005d9-565f-4309-8ffb-c13c72139ebe&oauthDecision=allow&state=1&client_id=123456789
</pre>
-</div></div><p>AuthorizationCodeGrantService will use a
'session_authenticity_token' to validate that the session is valid and will
process the user decision next.</p><p>If the decision is "allow" then it will
check the status of the individual scope values. It relies on the
"scopename_status" convention, if the form has offered the user a chance to
selectively enable individual scopes then name/value pairs such as
"updateCalendar-7_status=allow" are submitted. If none of such pairs is coming
back then it means the user has approved all the default and additional (if
any) scopes.</p><p>Next it will ask OAuthDataProvider to generate an
authorization code grant and return it alongside with the state if any by
redirecting the current user back to the redirect URI:</p><div class="code
panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl">
+</div></div><p>The AuthorizationCodeGrantService will use the
'session_authenticity_token' to first check that the session is valid and if so
will process the user's decision.</p><p>If the decision is "allow" then it will
check the status of the submitted individual scope values. It relies on the
"scopename_status" convention (e.g., "updateCalendar-7_status=allow") in
name/value pairs, if the form offers the user a chance to selectively enable
individual scopes. If none such pairs are returned then it means the user has
approved all the default and any additional scopes.</p><p>Next it will ask the
OAuthDataProvider to generate an authorization code grant and return it
alongside with the state if any by redirecting the current user back to the
redirect URI:</p><div class="code panel pdl" style="border-width: 1px;"><div
class="codeContent panelContent pdl">
<pre class="brush: java; gutter: false; theme: Default">Response-Code: 303
Headers: {
Location=[http://localhost:8080/services/reservations/reserve/complete?state=1
@@ -222,11 +222,11 @@ Authorization=[Basic YmFycnlAcmVzdGF1cmF
Cookie=[JSESSIONID=1c289vha0cxfe],
}
</pre>
-</div></div><p>If a user decision was set to "deny" then the error will be
returned to the client.</p><p>Assuming the decision was "allow", the client has
now received back the authorization code grant and is ready to exchange it for
a new access token.</p><h3 id="JAX-RSOAuth2-HowtocreateAuthorizationView">How
to create Authorization View</h3><p>Typically one can use
RequestDispatcherProvider to redirect to a view handler like JSP. Overriding
RedirectionBasedService.startAuthorization by delegating to the superclass and
then converting the Response to HTML or writing a custom MessageBodyWriter that
will do the conversion are other two options.</p><p>Yet another option is to
register <a shape="rect"
href="http://cxf.apache.org/docs/jax-rs-advanced-xml.html#JAX-RSAdvancedXML-XSLTsupport";>XSLTJaxbProvider</a>
which would convert OAuthAuthorizationData to HTML or JAXBProvider set with a
reference to an XSLT stylesheet.</p><h3
id="JAX-RSOAuth2-EndUserNameinAuthorizationForm">EndUser Name
in Authorization Form</h3><p>You may want to display a resource owner/end
user name in the authorization form this user will be facing, you can get
org.apache.cxf.rs.security.oauth2.provider.ResourceOwnerNameProvider registered
with either AuthorizationCodeGrantService or ImplicitGrantService.<br
clear="none">org.apache.cxf.rs.security.oauth2.provider.DefaultResourceOwnerNameProvider,
if registered, will return an actual login name, the custom implementations
may choose to return a complete user name instead, etc.</p><h3
id="JAX-RSOAuth2-PublicClients(Devices)">Public Clients (Devices)</h3><p>Client
can be 'public' if it has been registered as a public client with no client
secret the service itself has a "canSupportPublicClients" property enabled. The
same property will also have to be enabled on AccessTokenService (described in
the next section) for a public client without a secret be able to exchange a
code grant for an access token.</p><h4 id="JAX-RSOAuth2-OOBResponse">OOB Resp
onse</h4><p>If a public client has not registered a redirect URI with the
Authorization service then the authorization code can be returned out-of-band
(OOB), see <a shape="rect" class="external-link"
href="https://github.com/apache/cxf/blob/master/rt/rs/security/oauth-parent/oauth2/src/main/java/org/apache/cxf/rs/security/oauth2/common/OOBAuthorizationResponse.java";
rel="nofollow">OOBAuthorizationResponse</a> bean. By default, it is returned
directly to the end user, unless 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/OOBResponseDeliverer.java";
rel="nofollow">OOBResponseDeliverer</a> is registered with
AuthorizationCodeGrantService which may deliver it to the client via some
custom back channel.</p><p>Having OOB responses supported is useful when a
public client (typically a device which can not keep the client secrets and
where no redirect U
RI is supported) needs to get a code grant. What will happen is that a device
owner will send a request to Authorization Service which may look like
this:</p><div class="preformatted panel" style="border-width: 1px;"><div
class="preformattedContent panelContent">
+</div></div><p>If a user decision was set to "deny" then the error will be
returned to the client.</p><p>Assuming the decision was "allow", the client has
now received back the authorization code grant and is ready to exchange it for
a new access token.</p><h3 id="JAX-RSOAuth2-HowtocreateAuthorizationView">How
to create Authorization View</h3><p>Typically one can use
RequestDispatcherProvider to redirect to a view handler like JSP. Overriding
RedirectionBasedService.startAuthorization by delegating to the superclass and
then converting the Response to HTML or writing a custom MessageBodyWriter that
will do the conversion are other two options.</p><p>Yet another option is to
register <a shape="rect"
href="http://cxf.apache.org/docs/jax-rs-advanced-xml.html#JAX-RSAdvancedXML-XSLTsupport";>XSLTJaxbProvider</a>
which would convert OAuthAuthorizationData to HTML or JAXBProvider set with a
reference to an XSLT stylesheet.</p><h3
id="JAX-RSOAuth2-EndUserNameinAuthorizationForm">EndUser Name
in Authorization Form</h3><p>You may want to display a resource owner/end
user name in the authorization form this user will be facing, you can get
org.apache.cxf.rs.security.oauth2.provider.ResourceOwnerNameProvider registered
with either AuthorizationCodeGrantService or ImplicitGrantService.<br
clear="none">org.apache.cxf.rs.security.oauth2.provider.DefaultResourceOwnerNameProvider,
if registered, will return an actual login name, the custom implementations
may choose to return a complete user name instead, etc.</p><h3
id="JAX-RSOAuth2-PublicClients(Devices)">Public Clients (Devices)</h3><p>The
Client can be 'public' if it has been registered as a public client with no
client secret if the service itself has a "canSupportPublicClients" property
enabled. The same property will also have to be enabled on AccessTokenService
(described in the next section) for a public client without a secret be able to
exchange a code grant for an access token.</p><h4
id="JAX-RSOAuth2-OOBResponse">O
OB Response</h4><p>If a public client has not registered a redirect URI with
the Authorization service then the authorization code can be returned
out-of-band (OOB), see <a shape="rect" class="external-link"
href="https://github.com/apache/cxf/blob/master/rt/rs/security/oauth-parent/oauth2/src/main/java/org/apache/cxf/rs/security/oauth2/common/OOBAuthorizationResponse.java";
rel="nofollow">OOBAuthorizationResponse</a> bean. By default, it is returned
directly to the end user, unless 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/OOBResponseDeliverer.java";
rel="nofollow">OOBResponseDeliverer</a> is registered with
AuthorizationCodeGrantService which may deliver it to the client via some
custom back channel.</p><p>Having OOB responses supported is useful when a
public client (typically a device which can not keep client secrets and/or
where no redi
rect URI is supported) needs to get a code grant. What will happen is that a
device owner will send a request to the Authorization Service which may look
like this:</p><div class="preformatted panel" style="border-width: 1px;"><div
class="preformattedContent panelContent">
<pre>GET
http://localhost:8080/services/social/authorize?client_id=mobileClient&response_type=code
</pre>
-</div></div><p>Assuming the 'mobileClient' has been registered as public one
with no secret and the service has been set up to support such clients, the end
user will get a chance to authorize this client the same way it can do
confidential clients, and after this user gets back a code (delivered directly
in the response HTML page by default) the user will enter the code securely
into the device which will then replace it for a time-scoped access token by
contacting AccessTokenService.</p><h4 id="JAX-RSOAuth2-PKCEsupport">PKCE
support</h4><p>CXF supports <a shape="rect" class="external-link"
href="https://tools.ietf.org/html/rfc7636"; rel="nofollow">RFC-7636</a>: Proof
Key for Code Exchange by OAuth Public Clients (PKCE). If you are using the
authorization code grant with public clients, it is recommended to use PKCE to
avoid attacks which exploit the lack of a binding between the authorization
code request and the token request. This binding is achieved for confidential
clients by i
ncluding the client_id in both requests, however with public clients we do not
have a registered client_id.</p><p>The public (mobile) client generates a
'code_verifier' value and includes a related 'code_challenge' and optional
'code_challenge_method' to the authorization service. The authorization service
will save the code_challenge value, with the help of the registered
AuthorizationCodeDataProvider into an instance of ServerAuthorizationCodeGrant.
The client will next request a token providing the 'code_verifier' - which will
be compared by AuthorizationCodeGrantHandler with the original 'code_challenge'
value. By default, the 'code_challenge' is expected to be equal to the original
'code_verifier', but the grant handler can be registered with the custom
org.apache.cxf.rs.security.oauth2.grants.code.CodeVerifierTransformer - CXF
ships a DigestCodeVerifier which implements a transformation mentioned in the
extension.</p><h3 id="JAX-RSOAuth2-FormPostResponseMode">Form Post Respons
e Mode</h3><p><a shape="rect" class="external-link"
href="http://openid.net/specs/oauth-v2-form-post-response-mode-1_0.html";
rel="nofollow">Form Post Response Mode</a> has been orinially introduced for
OpenId Connect but has been generally recomended recently as a possibly safer
option of returning OAuth2 Authorization Service response to the clients.
Starting from CXF 3.1.9, if a client sends a "response_mode=form_post"
parameter during the original redirect, CXF AuthorizationCodeService will
return  <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/OOBAuthorizationResponse.java";
rel="nofollow">OOBAuthorizationResponse</a> with its 'redirectUri' property
set - a JSP/etc handler will convert to an HTML form which will re-post the
data to the client callback address.</p><h2
id="JAX-RSOAuth2-AccessTokenService">AccessTokenService</h2><p>The role of <a
shap
e="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/AccessTokenService.java";
rel="nofollow">AccessTokenService</a> is to exchange a token grant for a new
access token which will be used by the client to access the end user's
resources. <br clear="none">Here is an example request log:</p><div class="code
panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl">
+</div></div><p>Assuming the 'mobileClient' has been registered as public one
with no secret and the service has been set up to support such clients, the end
user will get a chance to authorize this client the same way it can 
confidential clients, and after this user gets back a code (delivered directly
in the response HTML page by default) the user will enter the code securely
into the device which will then replace it for a time-scoped access token by
contacting AccessTokenService.</p><h4 id="JAX-RSOAuth2-PKCEsupport">PKCE
support</h4><p>CXF supports <a shape="rect" class="external-link"
href="https://tools.ietf.org/html/rfc7636"; rel="nofollow">RFC-7636</a>: Proof
Key for Code Exchange by OAuth Public Clients (PKCE). If you are using the
authorization code grant with public clients, it is recommended to use PKCE to
avoid attacks which exploit the lack of a binding between the authorization
code request and the token request. This binding is achieved for confidential
clients b
y including the client_id in both requests, however with public clients we do
not have a registered client_id.</p><p>The public (mobile) client generates a
'code_verifier' value and includes a related 'code_challenge' and optional
'code_challenge_method' to the authorization service. The authorization service
will save the code_challenge value, with the help of the registered
AuthorizationCodeDataProvider into an instance of ServerAuthorizationCodeGrant.
The client will next request a token providing the 'code_verifier' - which will
be compared by AuthorizationCodeGrantHandler with the original 'code_challenge'
value. By default, the 'code_challenge' is expected to be equal to the original
'code_verifier', but the grant handler can be registered with a custom
org.apache.cxf.rs.security.oauth2.grants.code.CodeVerifierTransformer. 
CXF ships a DigestCodeVerifier which implements a transformation mentioned in
the extension.</p><h3 id="JAX-RSOAuth2-FormPostResponseMode">Form Post R
esponse Mode</h3><p><a shape="rect" class="external-link"
href="http://openid.net/specs/oauth-v2-form-post-response-mode-1_0.html";
rel="nofollow">Form Post Response Mode</a> was originally introduced for OpenId
Connect but has been generally recommended recently as a possibly safer option
of returning OAuth2 Authorization Service responses to clients. Starting from
CXF 3.1.9, if a client sends a "response_mode=form_post" parameter during the
original redirect, CXF AuthorizationCodeService will return an <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/OOBAuthorizationResponse.java";
rel="nofollow">OOBAuthorizationResponse</a> with its 'redirectUri' property
set - which a JSP/etc handler will convert to an HTML form which will re-post
the data to the client callback address.</p><h2
id="JAX-RSOAuth2-AccessTokenService">AccessTokenService</h2><p>The role 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/services/AccessTokenService.java";
rel="nofollow">AccessTokenService</a> is to exchange a token grant for a new
access token which will be used by the client to access the end user's
resources. <br clear="none">Here is an example request log:</p><div class="code
panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl">
<pre class="brush: java; gutter: false; theme: Default">Address:
http://localhost:8080/services/oauth/token
Http-Method: POST
@@ -484,7 +484,7 @@ ModelEncryptionSupport.decryptAccessToke
</jaxrs:serviceBeans>
</jaxrs:server>
</pre>
-</div></div><p>See this <a shape="rect" class="external-link"
href="https://github.com/apache/cxf-fediz/blob/master/services/oidc/src/main/webapp/WEB-INF/applicationContext.xml";
rel="nofollow">application context</a> for another example.</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 me
ssage 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 AccessTokenService.</p><p>Please see <a
shape="r
ect" href="jaxrs-oauth2-assertions.html">JAXRS OAuth2 Assertions</a> section
for more information on how it may work.</p><h2
id="JAX-RSOAuth2-ClientCertificateAuthentication">Client Certificate
Authentication</h2><p>If a 2-way TLS is used to authenticate a client, and the
Client has a Base64 encoded representations of its X509Certificates available
in its "applicationCertificates" property, then the AccessTokenService will do
the additional comparison of these certificates against the ones available in
the current TLS session.</p><p>Also, <a shape="rect" class="external-link"
href="https://tools.ietf.org/html/rfc8705"; rel="nofollow">OAuth 2.0 Mutual-TLS
Client Authentication and Certificate-Bound Access Tokens</a> is completely
supported since CXF 3.1.12. After the client authenticates to the token
service, the token service will insert a digest of the client's certificate in
the issued (JWT based) access token. On the resource server side, the
OAuthRequestFilter will check the dige
st of the client certificate against the value stored in the token claim, and
will throw a 401 exception if they do not match. </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="https://github.com/apache/cxf/blob/master/rt/rs/security/oauth-parent/oauth2/src/main/java/org/apache/cxf/rs/security/oauth2/provider/SessionAuthenticityTokenProvider.java";
rel="nofollow">SessionAuthenticityTokenProvider</a> with either
AuthorizationCodeGrantService or ImplicitGrantService beans.</p><p>CXF ships <a
shape="rect" class="externa
l-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/JoseSessionTokenProvider.java";
rel="nofollow">JoseSessionTokenProvider </a>which uses <a shape="rect"
href="http://cxf.apache.org/docs/jax-rs-jose.html";>CXF JOSE</a> to create a
compact JWS and/or JWE sequence capturing all the data which need to be
available when the user returns an authorization form decision and this secure
sequence becomes a session token.</p><h3
id="JAX-RSOAuth2-Keepingthestateinthesession">Keeping the state in the
session</h3><p>Note that <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/SessionAuthenticityTokenProvider.java";
rel="nofollow">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 <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/JoseSessionTokenProvider.java";
rel="nofollow">JoseSessionTokenProvider </a>which uses <a shape="rect"
href="http://cxf.apache.org/docs/jax-rs-jose.html";>CXF JOSE</a> that can be
used as a SessionAuthenticityTokenProvider 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="https://github.com/apache/cxf/bl
ob/master/rt/rs/security/oauth-parent/oauth2/src/main/java/org/apache/cxf/rs/security/oauth2/provider/SessionAuthenticityTokenProvider.java"
rel="nofollow">SessionAuthenticityTokenProvider</a> has been updated in CXF
3.0.2 to accept request parameters and a reference to the authenticated 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 initiali
zation</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="https://github.com/apache/cxf/blob/master/rt/rs/security/oauth-parent/oauth2/src/main/java/org/apache/cxf/rs/security/oauth2/filters/OAuthRequestFilter.java";
rel="nofollow">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 th
e 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>See this <a shape="rect" class="external-link"
href="https://github.com/apache/cxf-fediz/blob/master/services/oidc/src/main/webapp/WEB-INF/applicationContext.xml";
rel="nofollow">application context</a> for another example.</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 me
ssage 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 AccessTokenService.</p><p>Please see <a
shape="r
ect" href="jaxrs-oauth2-assertions.html">JAXRS OAuth2 Assertions</a> section
for more information on how it may work.</p><h2
id="JAX-RSOAuth2-ClientCertificateAuthentication">Client Certificate
Authentication</h2><p>If a 2-way TLS is used to authenticate a client, and the
Client has a Base64 encoded representations of its X509Certificates available
in its "applicationCertificates" property, then the AccessTokenService will do
the additional comparison of these certificates against the ones available in
the current TLS session.</p><p>Also, <a shape="rect" class="external-link"
href="https://tools.ietf.org/html/rfc8705"; rel="nofollow">OAuth 2.0 Mutual-TLS
Client Authentication and Certificate-Bound Access Tokens</a> is completely
supported since CXF 3.1.12. After the client authenticates to the token
service, the token service will insert a digest of the client's certificate in
the issued (JWT based) access token. On the resource server side, the
OAuthRequestFilter will check the dige
st of the client certificate against the value stored in the token claim, and
will throw a 401 exception if they do not match.</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="https://github.com/apache/cxf/blob/master/rt/rs/security/oauth-parent/oauth2/src/main/java/org/apache/cxf/rs/security/oauth2/provider/SessionAuthenticityTokenProvider.java";
rel="nofollow">SessionAuthenticityTokenProvider</a> with either
AuthorizationCodeGrantService or ImplicitGrantService beans.</p><p>CXF ships <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/JoseSessionTokenProvider.java";
rel="nofollow">JoseSessionTokenProvider </a>which uses <a shape="rect"
href="http://cxf.apache.org/docs/jax-rs-jose.html";>CXF JOSE</a> to create a
compact JWS and/or JWE sequence capturing all the data which need to be
available when the user returns an authorization form decision and this secure
sequence becomes a session token.</p><h3
id="JAX-RSOAuth2-Keepingthestateinthesession">Keeping the state in the
session</h3><p>Note that <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/SessionAuthenticityTokenProvider.java";
rel="nofollow">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 <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/JoseSessionTokenProvider.java";
rel="nofollow">JoseSessionTokenProvider </a>which uses <a shape="rect"
href="http://cxf.apache.org/docs/jax-rs-jose.html";>CXF JOSE</a> that can be
used as a SessionAuthenticityTokenProvider 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="https://github.com/apache/cxf/blo
b/master/rt/rs/security/oauth-parent/oauth2/src/main/java/org/apache/cxf/rs/security/oauth2/provider/SessionAuthenticityTokenProvider.java"
rel="nofollow">SessionAuthenticityTokenProvider</a> has been updated in CXF
3.0.2 to accept request parameters and a reference to the authenticated 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 initializ
ation</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="https://github.com/apache/cxf/blob/master/rt/rs/security/oauth-parent/oauth2/src/main/java/org/apache/cxf/rs/security/oauth2/filters/OAuthRequestFilter.java";
rel="nofollow">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: java; gutter: false; theme: Default">Address:
http://localhost:8080/services/thirdPartyAccess/calendar
Http-Method: GET
Headers:
