JAX-RS: Token Authorization

Introduction

CXF JAX-RS offers an extension letting users to enforce a new fine-grained Claims Based Access Control (CBAC) based on Claim and Claims annotations as well as ClaimMode enum class. It works with SAML tokens and with JWT tokens (from the 3.3.0 release onwards).

See also JAX-RS XML Security, JAX-RS SAML and JAX-RS JOSE.

Backwards compatibility configuration note

From Apache CXF 3.1.0, the WS-Security based configuration tags used to configure XML Signature or Encryption ("ws-security-*") have been changed to just start with "security-". Apart from this they are exactly the same. Older "ws-security-" values continue to be accepted in CXF 3.1.0. To use any of the configuration examples in this page with an older version of CXF, simply add a "ws-" prefix to the configuration tag.

The package for Claim, Claims and ClaimMode annotations has changed from "org.apache.cxf.rs.security.saml.authorization" to "org.apache.cxf.security.claims.authorization". Starting from CXF 2.7.1, the default name format for claims is "urn:oasis:names:tc:SAML:2.0:attrname-format:unspecified" instead of "http://schemas.xmlsoap.org/ws/2005/05/identity/claims".

From the 3.3.0 release, the Claims access control annotations/interceptors now work with JWT tokens (as well as SAML tokens). This resulted in the following package changes:

• The package name of the ClaimsAuthorizingInterceptor has changed: from org.apache.cxf.rt.security.saml.interceptor.ClaimsAuthorizingInterceptor to org.apache.cxf.rt.security.claims.interceptor.ClaimsAuthorizingInterceptor.
• The package name of the ClaimsAuthorizingFilter  has changed: from org.apache.cxf.rs.security.saml.authorization.ClaimsAuthorizingFilter to org.apache.cxf.rs.security.claims.ClaimsAuthorizingFilter

Maven dependencies

<dependency>
  <groupId>org.apache.cxf</groupId>
  <artifactId>cxf-rt-rs-security-xml</artifactId>
  <version>3.3.0</version>
</dependency>

Claims based access control

Claims annotations

Here is a simple code fragment to secure a service object using Claims annotations:

import org.apache.cxf.security.claims.authorization.Claim;
import org.apache.cxf.security.claims.authorization.Claims;

@Path("/bookstore")
public class SecureClaimBookStore {
    
    @POST
    @Path("/books")
    @Produces("application/xml")
    @Consumes("application/xml")
    @Claims({ 
        @Claim({"admin" }),
        @Claim(name = "http://claims/authentication-format", 
               format = "http://claims/authentication", 
               value = {"fingertip", "smartcard" })
    })
    public Book addBook(Book book) {
        return book;
    }
    
}

SecureClaimBookStore.addBook(Book) can only be invoked if Subject meets the following requirement: it needs to have a Claim with a value "admin" and another Claim confirming that it got authenticated using either a 'fingertip' or 'smartcard' method. Note that @Claim({"admin"}) has no name and format classifiers set - it relies on default name and format values, namely "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/role" and "urn:oasis:names:tc:SAML:2.0:attrname-format:unspecified" ("http://schemas.xmlsoap.org/ws/2005/05/identity/claims" before CXF 2.7.1) respectively. These default values may change in the future depending on which claims are found to be used most often - but as you can see you can always provide name and format values which will scope a given claim value.

Note that in the above example, a Claim with the name "http://claims/authentication-format" has two values, 'fingertip' and 'smartcard'. By default, in order to meet this Claim, Subject needs to have a Claim which has either a 'fingertip' or 'smartcard' value. If it is expected that Subject needs to have a Claim which has both 'fingertip' and 'smartcard' values, then the following change needs to be done:

import org.apache.cxf.security.claims.authorization.Claim;
import org.apache.cxf.security.claims.authorization.Claims;

@Path("/bookstore")
public class SecureClaimBookStore {
    
    @POST
    @Path("/books")
    @Produces("application/xml")
    @Consumes("application/xml")
    @Claims({ 
        @Claim({"admin" }),
        @Claim(name = "http://claims/authentication-format", 
               format = "http://claims/authentication", 
               value = {"fingertip", "smartcard" },
               matchAll = true)
    })
    public Book addBook(Book book) {
        return book;
    }
    
}

Claims can be specified using individual @Claim annotation, they can be set at the class level and overridden at the method level and finally a lax mode of check can be specified:

import org.apache.cxf.security.claims.authorization.Claim;
import org.apache.cxf.security.claims.authorization.Claims;

@Path("/bookstore")
@Claim({"user"})
public class SecureClaimBookStore {
    
    @POST
    @Path("/books")
    @Produces("application/xml")
    @Consumes("application/xml")
    @Claims({ 
        @Claim({"admin" }),
        @Claim(name = "http://claims/authentication-format", 
               format = "http://claims/authentication", 
               value = {"fingertip", "smartcard" },
               matchAll = true)
    })
    public Book addBook(Book book) {
        return book;
    }

    @GET
    @Claim(name = "http://claims/authentication-format", 
               format = "http://claims/authentication", 
               value = {"password" },
               mode = ClaimMode.LAX)
    public Book getBook() {
        //...
    }

    @GET
    public BookList getBookList() {
        //...
    }
    
    
}

In the above example, getBookList() can be invoked if Subject has a Claim with the value "user"; addBook() has it overridden - "admin" is expected and the authentication format Claim too; getBook() can be invoked if Subject has a Claim with the value "user" and it also must have the authentication format Claim with the value "password" - or no such Claim at all.

org.apache.cxf.rt.security.claims.interceptor.ClaimsAuthorizingInterceptor ("org.apache.cxf.rt.security.saml.interceptor.ClaimsAuthorizingInterceptor" before CXF 3.3.0) enforces the CBAC rules. This filter can be overridden and configured with the rules directly which can be useful if no Claim-related annotations are expected in the code. Map nameAliases and formatAliases properties are supported to make @Claim annotations look a bit simpler, for example:

@Claim(name = "auth-format", format = "authentication", value = {"password" })

where "auth-format" and "authentication" are aliases for "http://claims/authentication-format" and "http://claims/authentication" respectively.

Given the above example, the question is how to extract the information available in a received token (SAML/JWT) for the current request to succeed in passing through the security filter enforcing the CBAC rules.

The first and most important thing which needs to be done is to verify that an assertion Subject can be mapped to a recognized identity instance.

There is a number of ways a Subject can be validated.

If STS is asked to validate the assertion then a successful response from IDP will likely be good enough for CXF to trust the identity of the provider.
If the assertion signature is verified locally using the public key of IDP then it could a good enough confirmation too.

Alternatively, a custom validator, extending either org.apache.ws.security.validate.SamlAssertionValidator or CXF SAML SecurityContextProvider implementation can be registered with the server side SAML handler.

The latter option is preferred because not only one can validate Subject - but also ensure that a resulting SecurityContext will return a user Principal with a proper name - given that the actual Subject name available in the assertion may need to be translated to a name recognized by the local security stores or application. A combination of the assertion's Subject and AttributeStatement elements may need to be checked to establish a real name.

In cases like this you may want to register a custom SecurityContextProvider even if you have STS validating the assertion. Yet another reason is to retrieve the information about roles for a given Subject or map the assertion claims to roles for working with the RBAC to succeed, see the next section for more information.

Have a look please at this server configuration example:

<bean id="serviceBeanClaims" class="org.apache.cxf.systest.jaxrs.security.saml.SecureClaimBookStore"/>
<bean id="samlEnvHandler" class="org.apache.cxf.rs.security.saml.SamlEnvelopedInHandler">
 <property name="securityContextProvider">
    <bean class="org.apache.cxf.systest.jaxrs.security.saml.CustomSecurityContextProvider"/>
 </property>
</bean>
    
<bean id="claimsHandler" 
     class="org.apache.cxf.rs.security.saml.authorization.ClaimsAuthorizingFilter">
    <property name="securedObject" ref="serviceBeanClaims"/>   
</bean>

<jaxrs:server address="/saml-claims"> 
       <jaxrs:serviceBeans>
          <ref bean="serviceBeanClaims"/>
       </jaxrs:serviceBeans>
       <jaxrs:providers>
          <ref bean="samlEnvHandler"/>
          <ref bean="claimsHandler"/>
       </jaxrs:providers>
</jaxrs:server>

An instance of org.apache.cxf.rs.security.saml.authorization.ClaimsAuthorizingFilter (note org.apache.cxf.rs.security.claims.ClaimsAuthorizingFilter from CXF 3.3.0) is used to enforce CBAC. It's a simple JAX-RS filter wrapper around ClaimsAuthorizingInterceptor. SamlEnvelopedInHandler processes and validates SAML assertions and it also relies on a simple CustomSecurityContextProvider to help it to figure out what the actual Subject name is. A more involved implementation can do some additional validation as well as override few more super class methods, more on it next. The claims themselves have already been parsed and will be made available to a resulting SecurityContext which ClaimsAuthorizingFilter will rely upon.

Role based access control