<<if: ZXIDBOOK>>
<<else: >>ZXID Integration Guide for TAS3
##########################
<<author: Sampo Kellomäki (sampo@symlabs.com)>>
<<cvsid: $Id: zxid-java.pd,v 1.4 2009-08-30 15:09:26 sampo Exp $>>
<<class: article!a4paper!!ZXID-JAVA 01>>
<<define: ZXDOC=ZXID Java Interface>>

<<abstract:

ZXID.org Identity Management toolkit implements standalone SAML 2.0 and
Liberty ID-WSF 2.0 stacks. This document describes how to use ZXID to
implement the TAS3 architecture.

>>

<<maketoc: 1>>

1 Introduction
==============

TAS3 (http://www.tas3.eu/) is an advanced architecure for web services
ecosystems. ZXID has an implementation of the most of the core
technologies required to build TAS3 compliant systems. This doecument
describes how this is to be done.

> *Acknowledgement*: The research leading to these results has
> received funding from the European Community's Seventh Framework
> Programme (FP7/2007-2013) under grant agreement number 216287 (TAS3
> - Trusted Architecture for Securely Shared Services - www.tas3.eu).

1.1 Other documents
-------------------

<<doc-inc.pd>>

<<fi: >>

2 TAS3 Integration Strategies
=============================

2.1 TAS3 Proxy
--------------

In TAS3 Proxy strategy, the legacy application is not modified at
all. Instead it is shileded by a proxy that will handle TAS3 related
identity management, seucrity, and authorization aspects and
then call the legacy application. If the legacy application needs
to call TAS3 compliant web service, it makes the call against
the TAS3 Proxy, which will add TAS3 related features and then
call the real web service, wait for result, and process TAS3
aspects of the result.

Main complexities of the TAS3 proxy approach arise when
some of the identity information needs to be passed from
the proxy to the legacy application (and from legacy app to
the proxy in case of web services client). Generally this
tends to involve awkward and nonstandard methods or keeping
a session and passing reference to the session so that the
legacy app can obtain the needed information from the session.

Whereas the main attraction of the TAS3 Proxy integration strategy is
that there is no API for the legacy app to call, the complications
with the information passing still seem to necessitate an API and
some TAS3 awareness on part of the legacy app, thus negating the
main benefit of the proxy approach.

Three cases need to be considered.

2.1.1 TAS3 SSO Proxy (front channel)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Needs to establish a session, extract attributes and bootstraps
from the SSO assertion, and pass session id to legacy app.

The session ID is most conveniently passed has HTTP-Header "Cookie"
where the legacy app then needs to use it in the customary way to
access the session. ZXID does not currently (2009) support any
platform specific session systems, but built-in JSESSION
support could make those specific types of integration simpler.

Another possible approach is to pass the identity
of the user directly as Authorization header conveying HTTP
Basic Authentication parameters (where password field is just
ignored). This is similar to REMOTE_USER trick we will see
in the mod_auth_saml. Session cookie and basic authentication
can be combined.

2.1.2 TAS3 WSC Proxy
~~~~~~~~~~~~~~~~~~~~

Adds TAS3 headers to SOAP request and sends the request to the real destination.

Processes TAS3 response, making authorization checks, and returns the response
to the legacy app.

The information on whose behalf the call is being made is passed by
passing the session ID as Cookie so that the TAS3 WSC Proxy
can lookup user identity information for inclusion to the message
headers. The TAS3 WSC Proxy is also responsible for any discovery
activity, if needed.

2.1.3 TAS3 WSP Proxy
~~~~~~~~~~~~~~~~~~~~

Processes and authorizises the SOAP request and then sends it to the
legacy app, passing identity information along. Decorates the
response and returns it to the caller.

Identity information is passed to legacy app in form of faked basic
authentication and cookie carrying the session ID.

2.2 Apache Module Approach (mod_auth_saml)
------------------------------------------

This approach is similar to proxy approach in that the legacy app does
not need to call any API, but differs in that TAS3 processing simply
happens in the same Apache httpd process as serves the legacy application
pages.

The Apache module approach is not very amenable to WSC enablement. For WSC either
proxy approach or API approach needs to be used.

mod_auth_saml currently implements the module approach to SSO. It is foreseeable
that mod_auth_saml could be extended to support TAS3 WSP as well.

2.3 Servlet Approach
--------------------

The servlet approach is similar to mod_auth_saml approach in that the
legacy application generally does not require modification. It is
also similar in that it focusses on frontend SSO and authorization.
It offers little by way of actual web service call or web service
responder implementation, but can be complemented with the Filter
approach for these tasks.

For more detail about servlet approach, see zxid-java.pd, section
"Java Servlet Example Using Tomcat".

2.4 Filter Approach
-------------------

In the filter approach, the TAS3 API calls are hooked in to the web service
processing environment without modifying the actual legacy app. This approach
tends to work well for Java Application Servers and Frameworks that
have built in concepts of filters and interceptors.

* *** Name the filter technology for servlets (WSP)
* *** Name the filter technologies for clients (WSC)

The filter approach only works on those platforms where the concept is
available. Such concept is generally not available on the front channel,
i.e. filter is seldom applicable to SSO.

2.5 API Approach
----------------

In the API approach the legacy application is simply modified to call the
TAS3 APIs where appropriate.

3 ZXID APIs for TAS3
====================

3.1 SSO
-------

* zxid_simple() API as complete solution
* Java wrapper which allows registration of callbacks for session and
  *** Custodix, Sym collaboration to supply
* Alternatively: by steps approach

3.2 Authorization
-----------------

* Implicit authorization steps in zxid_simple() SSO
* zxid_az() family
* Appication Independent PEP configuration to process
  data items.

3.3 WSC
-------

* zxid_simple_call() family
  - String based approach to the SOAP Envelope and Body
  - Can specify URL and use Discovery (or STS) to obtain the token

3.4 WSP
-------

* *** functions for parsing SOAP messages

    zx_prepare_dec_ctx(cf->ctx, zx_ns_tab, qs2, qs2+cl);
    r = zx_DEC_root(cf->ctx, 0, 1);

* *** functions for checking TAS3 SOAP headers and signatures
  - Message signature validation
  - Token validation
  - Target audience check

* *** functions for TAS3 decorating response
  - zx_EASY_ENC_SO_e_Envelope(cf->ctx, env);

3.5 Auxiliary
-------------

* zxid_add_attr_to_ses()
* zxid_add_qs_to_ses()

8 TAS3 Demo
===========


http://sp.tas3.pt:8080/zxidservlet/zxidHLO?o=E
http://sp.tas3.pt:8080/zxidservlet/appdemo      # Protected content
http://sp.tas3.pt:8080/zxidservlet/sso?o=E      # mod_auth_saml sso

mini_httpd -p 8081 -c 'zxid*'

http://idp.tas3.pt:8081/zxididp?o=B

<<if: ZXIDBOOK>>
<<else: >>

96 License
==========

Copyright (c) 2009 Symlabs (symlabs@symlabs.com), All Rights Reserved.
Author: Sampo Kellomäki (sampo@symlabs.com)

See file COPYING for complete information.

<<references:

[SAML2core] "Assertions and Protocols for the OASIS Security Assertion Markup Language (SAML) V2.0", Oasis Standard, 15.3.2005, saml-core-2.0-os


>>

<<doc-end.pd>>
<<notapath: TCP/IP a.k.a xBSD/Unix n/a Perl/mod_perl PHP/mod_php Java/Tomcat>>
<<EOF: >>
<<fi: >>
