...

Introduction

OAuth 2.0 supports different types of access token grants. The OAuth2 Assertions draft spec "provides a framework for the use of assertions with OAuth 2.0 " and in the form of a new client authentication mechanism and a new authorization grant type". More specifically, the SAML2 Bearer Assertion Profiles for OAuth2 draft specifically spec provides for the use of SAML2 Bearer assertions, and the JSON Web Token (JWT) Profile for OAuth 2.0 Client Authentication and Authorization Grants spec providers for the use of JWT Bearer tokens.

These assertions can be used as token grants, but also, if needed, for getting 3rd party clients authenticated. Note the clients can use assertions as grants but use for example Basic authentication mechanism, or use say an authorization code grant and the assertion to authenticate, and finally, they can use assertions as a grant and as an authentication token.

Currently CXF supports both SAML2 Bearer and JWT Bearer assertions as grants and authentication tokens.

See the JAX-RS OAuth2 page for information about OAuth 2.0 support in CXF. Please also check the JAX-RS SAML page for more information about SAML support.

SAML2 Bearer

Maven dependencies

<dependency>
  <groupId>org.apache.cxf</groupId>
  <artifactId>cxf-rt-rs-security-oauth2-saml</artifactId>
  <version>2.7.4<<version>${cxf.version}</version>
</dependency>

...

Access Token Grant

This section explains how SAML2 Bearer assertions can be used as token grants. The value of grant_type parameter is "urn:ietf:params:oauth:grant-type:saml2-bearer".

...

JAXRSClientFactoryBean bean = new JAXRSClientFactoryBean();

Map<String, Object> properties = new HashMap<String, Object>();
properties.put("security.callback-handler", 
               "org.apache.cxf.systest.jaxrs.security.saml.KeystorePasswordCallback");
properties.put("security.saml-callback-handler", 
               "org.apache.cxf.systest.jaxrs.security.oauth2.SamlCallbackHandler2");
properties.put("security.signature.username", "alice");
properties.put("security.signature.properties", CRYPTO_RESOURCE_PROPERTIES);
properties.put("security.self-sign-saml-assertion", "true");
bean.setProperties(properties);
        
bean.getOutInterceptors().add(new Saml2BearerAuthOutInterceptor());
        
WebClient wc = bean.createWebClient();
wc.type(MediaType.APPLICATION_FORM_URLENCODED).accept(MediaType.APPLICATION_JSON);

// Use whatever token grant is required 
AccessTokenGrant accessTokenGrant = new ClientCredentialsGrant();
       
ClientAccessToken at = OAuthClientUtils.getAccessToken(wc, accessTokenGrant);

JWT Bearer

...

Access Token Grant

This section explains how SAML2 Bearer assertions can be used as token grants. The value of grant_type parameter is "urn:ietf:params:oauth:grant-type:saml2-bearer".

It is really just another grant type, but whose actual value is a SAML assertion. The specification provides an example of how such an assertion may look like.

The additional restriction is that the assertions have to be encoded using Base64Url encoding.
Here is how a request may look like:

POST /token HTTP/1.1
Content-Type: application/x-www-form-urlencoded

grant_type=urn%3Aietf%3Aparams%3Aoauth%3Agrant-type%3Asaml2-bearer&
assertion=Base64UrlEncoded-SAML2-Bearer-Assertion

Client code

The following example shows how to use SAML2 Bearer assertion as a grant with CXF OAuth2 client code:

import org.apache.cxf.jaxrs.client.WebClient;
import org.apache.cxf.rs.security.common.CryptoLoader;
import org.apache.cxf.rs.security.oauth2.client.OAuthClientUtils;
import org.apache.cxf.rs.security.oauth2.common.AccessTokenGrant;
import org.apache.cxf.rs.security.oauth2.common.ClientAccessToken;
import org.apache.cxf.rs.security.oauth2.grants.saml.Saml2BearerGrant;
import org.apache.cxf.rs.security.saml.SAMLUtils;
import org.apache.cxf.rs.security.saml.SAMLUtils.SelfSignInfo;
import org.apache.ws.security.components.crypto.Crypto;

//1: create web client
String address = "https://localhost:8080/oauth2/token";
WebClient wc = WebClient.create(address);
wc.type(MediaType.APPLICATION_FORM_URLENCODED).accept(MediaType.APPLICATION_JSON);

//2. Create and self-sign SAML assertion        
Crypto crypto = new CryptoLoader().loadCrypto(CRYPTO_RESOURCE_PROPERTIES);
SelfSignInfo signInfo = new SelfSignInfo(crypto, "alice", "password"); 
        
String assertion =  SAMLUtils.createAssertion(new SamlCallbackHandler(),
                                              signInfo).assertionToString();

//3. Send it as a token grant to Access Token Service and get some access token back
AccessTokenGrant grant = new Saml2BearerGrant(assertion);
ClientAccessToken at = OAuthClientUtils.getAccessToken(wc, 
                                                       new OAuthClientUtils.Consumer("alice", "alice"), 
                                                       grant,
                                                       false);

The code above prepares an info for a new SAML assertion be self-signed, loading a Crypto instance with crypto properties, and uses SAMLUtils to create and sign the assertion (using Crypto, plus user alias and password). Saml2BearerGrant will get the assertion Base64Url-encoded - unless the assertion has already been encoded with CXF Base64UrlUtility or came encoded from IP - in this case Saml2BearerGrant constructor accepting an 'encoded' property will have to be used, with the value set to "true".

This is nearly as simple as using other token grants, the step 2 will often me omitted in more involved cases as it will be the job of Identity Providers to issue OAuth2 SAML2 Bearer assertions. Step 2 needs to be done when testing or when getting client acting on behalf of itself for example.

Instead of using SelfSignInfo utility one can create an empty CXF Message and set required properties on it and passing it to SAMLUtils - see the example on how to use SAML Bearer assertions for the authentication below.

When doing step 2, the main effort is to do with getting a SAML assertion populated - use a SAML callback handler like this one, it is actually quite easy to build the assertion.

Access Token Service

Here is how one may configure Access Token Service:

<bean id="dataProvider" class="org.apache.cxf.systest.jaxrs.security.oauth2.OAuthDataProviderImpl"/>
<bean id="samlGrantHandler" class="org.apache.cxf.rs.security.oauth2.grants.saml.Saml2BearerGrantHandler">
  <property name="dataProvider" ref="dataProvider"/>
</bean>
<bean id="oauthJson" class="org.apache.cxf.rs.security.oauth2.provider.OAuthJSONProvider"/>

<bean id="serviceBean" class="org.apache.cxf.rs.security.oauth2.services.AccessTokenService">
  <property name="dataProvider" ref="dataProvider"/>
  <property name="grantHandlers">
     <list>
       <ref bean="samlGrantHandler"/>
     </list>
  </property>
</bean>

<jaxrs:server address="https://localhost:${testutil.ports.jaxrs-oauth2}/oauth2">
   <jaxrs:serviceBeans>
      <ref bean="serviceBean"/>
   </jaxrs:serviceBeans>
   <jaxrs:providers>
      <ref bean="oauthJson"/>
   </jaxrs:providers>
   <jaxrs:properties>
     <entry key="security.signature.properties" value="org/apache/cxf/systest/jaxrs/security/alice.properties"/>
   </jaxrs:properties>
</jaxrs:server>

Authentication Token

As noted in the introduction, JWT Bearer tokens may also act as client authentication credentials, when requesting an access token, irrespectively of the actual grant type. For example:

...

The following example shows how to use JWT Bearer tokens as an authentication token: TODO

Access Token Service

Here is how one may configure Access Token Service:

...