You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@cxf.apache.org by bu...@apache.org on 2017/04/28 14:47:42 UTC
svn commit: r1011312 - in /websites/production/cxf/content:
cache/docs.pageCache docs/jax-rs-oauth2.html
Author: buildbot
Date: Fri Apr 28 14:47:41 2017
New Revision: 1011312
Log:
Production update by buildbot for cxf
Modified:
websites/production/cxf/content/cache/docs.pageCache
websites/production/cxf/content/docs/jax-rs-oauth2.html
Modified: websites/production/cxf/content/cache/docs.pageCache
==============================================================================
Binary files - no diff available.
Modified: websites/production/cxf/content/docs/jax-rs-oauth2.html
==============================================================================
--- websites/production/cxf/content/docs/jax-rs-oauth2.html (original)
+++ websites/production/cxf/content/docs/jax-rs-oauth2.html Fri Apr 28 14:47:41 2017
@@ -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.rbtoc1478882820758 {padding: 0px;}
-div.rbtoc1478882820758 ul {list-style: disc;margin-left: 0px;}
-div.rbtoc1478882820758 li {margin-left: 0px;padding-left: 0px;}
+div.rbtoc1493390826813 {padding: 0px;}
+div.rbtoc1493390826813 ul {list-style: disc;margin-left: 0px;}
+div.rbtoc1493390826813 li {margin-left: 0px;padding-left: 0px;}
-/*]]>*/</style></p><div class="toc-macro rbtoc1478882820758">
+/*]]>*/</style></p><div class="toc-macro rbtoc1493390826813">
<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>
@@ -141,7 +141,9 @@ div.rbtoc1478882820758 li {margin-left:
</li><li><a shape="rect" href="#JAX-RSOAuth2-OAuthServerJAX-RSendpoints">OAuth Server JAX-RS endpoints</a>
<ul class="toc-indentation"><li><a shape="rect" href="#JAX-RSOAuth2-AuthorizationCodeandImplicitServicesonthesamerelativepath">AuthorizationCode and Implicit Services on the same relative path</a></li></ul>
</li></ul>
-</li><li><a shape="rect" href="#JAX-RSOAuth2-ThirdPartyClientAuthentication">Third Party Client Authentication</a></li><li><a shape="rect" href="#JAX-RSOAuth2-UserSessionAuthenticity">User Session Authenticity</a>
+</li><li><a shape="rect" href="#JAX-RSOAuth2-ThirdPartyClientAuthentication">Third Party Client Authentication</a>
+<ul class="toc-indentation"><li><a shape="rect" href="#JAX-RSOAuth2-ClientCertificateAuthentication">Client Certificate Authentication</a></li></ul>
+</li><li><a shape="rect" href="#JAX-RSOAuth2-UserSessionAuthenticity">User Session Authenticity</a>
<ul class="toc-indentation"><li><a shape="rect" href="#JAX-RSOAuth2-Keepingthestateinthesession">Keeping the state in the session</a></li><li><a shape="rect" href="#JAX-RSOAuth2-MultipleFactorVerification">Multiple Factor Verification</a></li></ul>
</li><li><a shape="rect" href="#JAX-RSOAuth2-CustomizingEndUserSubjectinitialization">Customizing End User Subject initialization</a></li><li><a shape="rect" href="#JAX-RSOAuth2-ProtectingresourceswithOAuthfilters">Protecting resources with OAuth filters</a>
<ul class="toc-indentation"><li><a shape="rect" href="#JAX-RSOAuth2-OAuth2tokensandSOAPendpoints">OAuth2 tokens and SOAP endpoints</a></li></ul>
@@ -152,7 +154,7 @@ div.rbtoc1478882820758 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>Ehcache and JCache OAuthDataProviders can represent access tokens in JWT</li><li>JPA2 OAuthDataProvider improved</li><li>DynamicRegistrationService added<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 third-party providers to access their resources.</p><p>The OAuth2 flow which is clo
sely 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 application, the application logo URI, one or more redirect URIs, and other information th
at 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 resources 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 resources available on the WEB for more information you may need to know about OAuth
2.</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>Ehcache, JCache and JPA2 OAuthDataProviders 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 third-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 application, 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 resources 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 resources 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">
<pre class="brush: xml; gutter: false; theme: Default" style="font-size:12px;"><dependency>
<groupId>org.apache.cxf</groupId>
<artifactId>cxf-rt-rs-security-oauth2</artifactId>
@@ -364,11 +366,11 @@ return token;
// decrypt a token given a token key
ModelEncryptionSupport.decryptAccessToken(this, encryptedToken, key);</pre>
-</div></div><pre> </pre><h4 id="JAX-RSOAuth2-JWTTokens">JWT Tokens</h4><p>Starting from CXF 3.1.8 some of CXF OAuthDataProvider implementations (EhCache and JCache based) support Access Token representations in JWT. This means that ServerAccessTokens created by data providers are converted to a sequence of JSON JWT claims and then JWS signed and/or JWE encrypted.</p><p>Custom data providers can extend <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> to depend on the code which converts ServerAccessTokens to JWT and 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/utils/JwtTokenUtils.java" rel="nofollow">JwtTokenUtils</a> to convert JOSE token representat
ions back to ServerAccessToken.</p><p>For example, here is how one can configure an Ehcache or JCache based provider to use JWT:</p><div class="code panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl">
-<pre class="brush: java; gutter: false; theme: Default" style="font-size:12px;"><bean id="oauthProvider" class="org.apache.cxf.systest.jaxrs.security.oauth2.common.OAuthDataProviderImpl">
+</div></div><pre> </pre><h4 id="JAX-RSOAuth2-JWTTokens">JWT Tokens</h4><p>Starting from CXF 3.1.8 some of CXF OAuthDataProvider implementations (EhCache, JCache and JPA2 based) support Access Token representations in JWT. This means that ServerAccessTokens created by data providers are converted to a sequence of JSON JWT claims and then JWS signed and/or JWE encrypted.</p><p>Custom data providers can extend <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> to depend on the code which converts ServerAccessTokens to JWT and 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/utils/JwtTokenUtils.java" rel="nofollow">JwtTokenUtils</a> to convert JOSE token repre
sentations back to ServerAccessToken.</p><p>For example, here is how one can configure one of CXF data providers to use JWT:</p><div class="code panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl">
+<pre class="brush: java; gutter: false; theme: Default" style="font-size:12px;"><bean id="oauthProvider" class="org.apache.cxf.rs.security.oauth2.grants.code.DefaultEHCacheCodeDataProvider">
<property name="useJwtFormatForAccessTokens" value="true"/>
</bean></pre>
-</div></div><p> </p><p>Additionally, in order to sign and/or encrypt, this provider can be injected with 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/provider/OAuthJoseJwtProducer.java" rel="nofollow">OAuthJoseJwtProducer</a> or AccessTokenService endpoint where this provider is registered can be configured as follows:</p><p> </p><div class="code panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl">
+</div></div><p>Additionally, in order to sign and/or encrypt, this provider can be injected with 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/provider/OAuthJoseJwtProducer.java" rel="nofollow">OAuthJoseJwtProducer</a> or AccessTokenService endpoint where this provider is registered can be configured as follows:</p><p> </p><div class="code panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl">
<pre class="brush: java; gutter: false; theme: Default" style="font-size:12px;"><jaxrs:server id="oauthServer1" address="https://localhost:${testutil.ports.jaxrs-oauth2-serviceJwt}/services">
<jaxrs:serviceBeans>
   <ref bean="tokenService"/>
@@ -378,12 +380,12 @@ ModelEncryptionSupport.decryptAccessToke
<entry key="rs.security.signature.key.password.provider" value-ref="keyPasswordProvider"/>
</jaxrs:properties>
</jaxrs:server></pre>
-</div></div><p> </p><p>Note that Ehcache and JCache providers will still persist the complete ServerAccessToken representations - once JOSE sequence is created it becomes a new tokenId of the current ServerAccessToken, with the original tokenId becoming a JWT 'jti' claim.</p><p>One can configure the providers to persist access tokens only as these newly created JOSE sequences:</p><p> </p><div class="code panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl">
+</div></div><p>Note that in this case Ehcache, JCache and JPA2 providers will still persist the complete ServerAccessToken representations - once JOSE sequence is created it becomes a new tokenId of the current ServerAccessToken, with the original tokenId becoming a JWT 'jti' claim.</p><p>The main advantage is that such tokens can be introspected locally at the resource server side, thus avoiding the remote token validation calls.</p><p>One can configure the providers (Ehcache and JCache only at the moment) to persist access tokens only as these newly created JOSE sequences:</p><p> </p><div class="code panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl">
<pre class="brush: java; gutter: false; theme: Default" style="font-size:12px;"><bean id="oauthProvider" class="org.apache.cxf.systest.jaxrs.security.oauth2.common.OAuthDataProviderImpl">
<property name="useJwtFormatForAccessTokens" value="true"/>
<property name="storeJwtTokenKeyOnly" value="true"/>
</bean></pre>
-</div></div><p>Only a JOSE sequence representing a given ServerAccessToken will be persisted. The providers will recreate ServerAccessToken from this sequence when the token is needed by the runtime.</p><p> </p><p>Resource server (RS) will need to make a decision how to validate this JWT token. It can continue validating it remotely with AccessTokenValidationService or TokenIntrsopectionService (see below for more info about these services) or if RS has an access to the keys used to sign/encrypt JWT then it can use a local JWT validation, example:</p><p> </p><div class="code panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl">
+</div></div><p>Only a JOSE sequence representing a given ServerAccessToken will be persisted. The providers will recreate ServerAccessToken from this sequence when the token is needed by the runtime, while requiring much less storage to keep such tokens. In this case, if it is preferred, one can further optimize it not to even store these secure string token representations - however the major downside is that it will be impossible to manage such tokens from the administration consoles due to no record of such tokens will be available in the storage.</p><p>Resource server (RS) will need to make a decision how to validate this JWT token. It can continue validating it remotely with AccessTokenValidationService or TokenIntrsopectionService (see below for more info about these services) or if RS has an access to the keys used to sign/encrypt JWT then it can use a local JWT validation, example:</p><p> </p><div class="code panel pdl" style="border-width: 1px;"><div class="codeContent
panelContent pdl">
<pre class="brush: java; gutter: false; theme: Default" style="font-size:12px;"><bean id="jwtTokenValidator" class="org.apache.cxf.rs.security.oauth2.filters.JwtAccessTokenValidator"/>
<bean id="oAuthFilterLocalValidation" class="org.apache.cxf.rs.security.oauth2.filters.OAuthRequestFilter">
<property name="tokenValidator" ref="jwtTokenValidator"/>
@@ -480,7 +482,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>If a 2-way TLS is sued
to authenticate a client and Client has a Base64 encoded representations of its X509Certificates available in its "applicationCertificates" property then AccessTokenService will do the additional comparison of these certificates against the ones available in the current TLS session.</p><p>Please see <a shape="rect" href="jaxrs-oauth2-assertions.html">JAXRS OAuth2 Assertions</a> section for more information on how it may work.</p><h1 id="JAX-RSOAuth2-UserSessionAuthenticity">User Session Authenticity</h1><p>Redirection-based Authorization Code and Implicit flows depend on end users signing in if needed during the initial redirection, challenged with the client authorization form and returning their decision. By default, CXF will enforce the user session authenticity by keeping the session state in a servlet container's HTTPSession. If the alternative storage is preferred then you can register a new <a shape="rect" class="external-link" href="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/b
lob/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" p
roperty 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/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 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 ses
sion authentication property, using a "session_authenticity_token_param_name" property name. This allows for the 'rotation' of hidden form properties containing the actual session authenticity values.</p><h1 id="JAX-RSOAuth2-CustomizingEndUserSubjectinitialization">Customizing End User Subject initialization</h1><p>By default, redirection based authorization services will the the current CXF SecurityContext to initialize a subject representing the authenticated resource owner/end user. If the customization if needed: custom CXF filter can be used to create UserSubject and set it on the message or org.apache.cxf.rs.security.oauth2.provider.SubjectCreator interface implementation can be registered with either AuthorizationCodeGrantService or ImplicitGrantService.</p><h1 id="JAX-RSOAuth2-ProtectingresourceswithOAuthfilters">Protecting resources with OAuth filters</h1><p><a shape="rect" class="external-link" href="https://github.com/apache/cxf/blob/master/rt/rs/security/oauth-parent/oau
th2/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">
+</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 Client has a Base64 encoded representations of its X509Certificates available in its "applicationCertificates" property then AccessTokenService will do the additional comparison of these certificates against the ones available in the current TLS session.</p><p><strong>New</strong>: <a shape="rect" class="external-link" href="https://tools.ietf.org/html/draft-campbell-oauth-mtls-01" rel="nofollow">Mutual TLS Profiles for OAuth2 Clients</a> is completely supported since CXF 3.1.12. Note some parameters used in this draft may change.</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 in
itial 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 cre
ate 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/JoseSession
TokenProvider.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/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 updated in CXF 3.0.2 to accept request parameters and a reference to the authenticated user. This allows for introduci
ng a multiple factor session verification: when the provider created a session property it can for example sent a message to a user's mobile phone expect the authorization consent form return the sent value.</p><p>The other minor enhancement is that RedirectionBasedGrantService will check the authorization content form for the name of the form property that contains a session authentication property, using a "session_authenticity_token_param_name" property name. This allows for the 'rotation' of hidden form properties containing the actual session authenticity values.</p><h1 id="JAX-RSOAuth2-CustomizingEndUserSubjectinitialization">Customizing End User Subject initialization</h1><p>By default, redirection based authorization services will the the current CXF SecurityContext to initialize a subject representing the authenticated resource owner/end user. If the customization if needed: custom CXF filter can be used to create UserSubject and set it on the message or org.apache.cxf.rs.s
ecurity.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: xml; gutter: false; theme: Default" style="font-size:12px;">Address: http://localhost:8080/services/thirdPartyAccess/calendar
Http-Method: GET
Headers: