Wednesday, November 9, 2011

SAML Claims-Based Authorization for JAX-RS endpoints

SAML has been around for a while and is used in real-world applications. CXF WS-Security framework is already offering a second-to-none support for SAML, especially with the introduction of the CXF's own STS, please check Colm's and Oliver's blogs and have some exciting read if you work with WS. Actually, STS can become quite important even for the advanced RESTful security - so follow those blogs even you don't work with WS :-).

The good thing about SAML is that SAML-based solutions do not have to be WS-* based only. SAML is an extensible and rich language and all sort of SAML profiles can be utilized for RESTful applications too. Arguably SAML is complex but the fact it's being used around is critical.

CXF JAX-RS is 'keen' to help users start working with SAML. CXF 2.5.0 offers an initial support for including SAML assertions in the HTTP request payloads and using them to enforce the Claims-Based or legacy Role-Based Access Control rules on the deployed JAX-RS endpoints.

One can get a SAML Assertion posted to the server inside a wrapper XML element which will include the actual application payload such as Book and the assertion itself, with the complete envelope being signed only or with both the application payload and the assertion itself being signed individually. All of it is done by registering a couple of client and server side handlers which will transparently add an envelope, signatures and then validate it all on the server side with the application payload (Book) becoming a root XML node in the end, ready to be processed by the JAX-RS runtime.

With REST we do not always post the XML data so what you can also do is easily add an optionally deflated and then base64-encoded assertion either to the Authorization header or a form field. Such encoded values might also be signed - something we may support in due time.

Having a SAML assertion available as part of the application payload raises a question as to what can actually be done with it. SAML is often used to provide SSO solutions for RESTful services, but we are not there yet, so the best thing that we could come up with at this initial stage is to let JAX-RS users utilize SAML claims in order to enforce the access control rules.

SAML claims are much richer than those which can be asserted with the RBAC rules. However @RolesAllowed and friends are still used a lot and probably will be so it was important to make sure that the legacy rules can work with SAML assertions having claims which are actually representing roles and also offer the way to assert much richer rules which are possible with SAML claims.

Have a look please at this sample code fragment and the follow-up comments. One have a lot of flexibility in the way the claim-based rules can be expressed and also complement the existing RBAC rules without even modifying the code which can also be important.

Before such rules can be enforced, the assertion needs to be validated. The SAML handler will do its own validation, and if you have STS deployed them you may actually want to delegate to it to do some validation too (recall the advice at the start of this post :-)). See also how you can setup an STS client.

The question which has not been seriously addressed yet is how one will create SAML assertions in the first place. At this stage one can start experimenting with using a callback approach and I think we can offer a support for utilizing a WS STSClient on the client side for getting the assertions and transparently adding them to the payload easily enough - please note, the fact that STSClient is a WS client is the least important fact here, it's a perfect mediator between the client code and STS and it does not matter if a SAML assertion which will make it into a non-SOAP payload was actually fetched using a SOAP client.

Note that supporting other interesting SAML-based solutions is of interest to us, that involves the possibility of supporting a WEB Browser SSO profile, etc.

In meantime, please write your simple SAML callback implementation which will generate SAML assertions and start stressing your endpoints secured by claim-based rules, or even invent a new SAML profile along the way :-)

Stay tuned !


Reaper said...

Hi Sergey,

Do you have an end-to-end sample of using SAML with RESTful services?



Sergey Beryozkin said...

We have a demo depending on Web SSO (SAML2-based), it is OAuth2 demo, but you can still have a look at how CXF SAML2 SP module is used:

Regarding embedding SAML directly into the client code (for the purpose of authentication and possibly authorization), we only have tests AFAIK at the moment, see: