OpenSAML how-to: adding transport to context

[Brent Putman]

On 5/19/15 4:27 AM, Misagh Moayyed wrote:
>
>  
>
> V3 code:
>
>  
>
> Something like this perhaps?
>
>  
>
> SimpleRequestAdapter inTransport = new SimpleRequestAdapter(…);
>
> MessageContext<SimpleRequestAdapter> inCtx = new
> MessageContext<SimpleRequestAdapter>();
>
> inCtx.setMessage(inTransport);
>


No, not really.  The messaging stuff (message decoding, encoding and
handlers) is the part of v3 that changed the most from v2.  It's
completely different and bears almost no resemblance to the v2 design.

In particular, the notion of the various "-Transport-" interfaces is
completely gone.

If you haven't found your way to this document [1] yet, this is
probably the best we have at the moment on the design of the new
messaging API in v3 (although there's no code examples, read on).  Some
of the terminology, class/interface names changed a little bit from
that document.

The gist of it is:

- A MessageContext represents a single message, the type of which is
represented by the generic parametrization of the context.  The generic
type could be literally anything, but for our own SAML code it's
usually just a SAMLObject, since that is the "payload" of a SAML
binding.  For another protocol like OpenID or CAS, etc, it would be a
similar type which represents the protocol message data structure.  For
SOAP, it *could* be *either* an Envelope or the type of the payload,
depending on whether you want to do "message oriented" vs "payload
oriented" messaging; all the OpenSAML SOAP impls do payload, so the
context will be paramed as SAMLObject like the other non-SOAP bindings.

- The MessageDecoders and MessageEncoders operate directly on the type
of input they support, e.g. HttpServletRequest and
HttpServletResponse.  See the interfaces and abstract impls in
messaging-api and messaging-impl.  Unlike v2, they generally don't do
anything other than decode/encode the message from/to the
MessageContext, and possibly populate some binding- or protocol-
specific subcontexts.

The unit tests for the decoders and encoders are probably the best
non-IdP examples of this code that you could look at.

- MessageHandlers operate on a single MessageContext and can do
anything: evaluate security policy (inbound), populate subcontexts
(inbound/outbound), build or mutate the message (outbound), etc.

- An operation context binds 2 or more MessageContexts together to
implement a message exchange pattern.  The only current one is the
InOutOperationContext, which represents and inbound and outbound flow
(either server-side or client) side.

- As mentioned in the wiki doc, message flows are modeled as a logical
pipeline.  For a server-side one, it's something like:

Inbound MessageContext decoded -> invoke inbound MessageHandler ->
"business logic" (aka profile handling) -> invoke
outboundMessageHandler  -> outbound MessageContext encoded.

That's conceptually what the IdP does, but it's a little convoluted at
this point, with all the SWF and ProfileAction stuff.

You can actually now see a good example of a client-side flow in the
new SOAP client [2] that I'm literally just finishing up.  It's on
trunk only, so not released yet.  The logic in the send(...) method of
org.opensaml.soap.client.http.AbstractPipelineHttpSOAPClient is pretty
much the client-side conceptual pipeline model. 

I don't have at the moment any code to illustrate, but a simple
server-side pipeline impl would look very similar, except based on
HttpServletMessagePipeline and of course the order of operations would
be reversed, with inbound decoding first and then outbound encoding
last.  There would likely be a "business logic" step in between those
2, possibly based on a ProfileAction (which assumes a
ProfileRequestContext subtype).  When I have a few minutes I will do up
an abstract impl of a server-side pipeline, to serve as an example for
non-SWF, non-IdP OpenSAML usage.  It would actually be simpler than the
client-side code in the SOAP client, I think.


[1]
https://wiki.shibboleth.net/confluence/display/DEV/MessagingAPIRefactoring

[2]
http://svn.shibboleth.net/view/java-opensaml/trunk/opensaml-soap-api/src/main/java/org/opensaml/soap/client/http/AbstractPipelineHttpSOAPClient.java?view=markup


-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://shibboleth.net/pipermail/dev/attachments/20150519/7088c6ed/attachment-0001.html>