Living Architecture Document
This document describes the architecture of the Liberty Identification Web-Services Framework (“ID-WSF”) Web-Services Consumer ("WSC") Client library (“ClientLib”). In order to fully specify this architecture, this document also provides significant information about related components in the ID-WSF architecture and also makes reference to the WSC requirements as defined in various Liberty specification documents.
The ClientLib defined herein is built upon a series of open document-model and messaging standards at multiple levels. To keep this document concise and usable as possible, we’ve attempted to include hyperlinks to definitions rather than attempt to define each of these standards and their respective lists of acronyms in this document. Additionally, we refer readers to the Liberty Glossary for Liberty-specific definitions.
Hyperlinks notwithstanding, this document does assume some familiarity with these underlying standards as well as with the ID-WSF specifications. As the ClientLib is part of an open-source initiative, the information herein is authored by the community of participants in the openLiberty project rather than any single author.
This document is based on the a document developed by Professor Gary Pollice.
- Software Architecture Document, for use with the Rational Unified Process
- Christopher Alexander: An Introduction for Object-Oriented Designers
The purpose of this document is to specify a real-world architecture for the ID-WSF version 2.0 WSC profile. It is also intended to capture and convey the significant ID-WSF architectural decisions that have been made. Using this document, together with the related WSC library, a software developer with sufficient contextual knowledge should be equipped to design and build applications that are able to consume web services from a Liberty ID-WSF-compliant web-services provider ("WSP").
The architecture specified herein is in conformance with, and makes references to, the existing specifications for this, and related ID-WSF entities, and should serve to foster the general development of Liberty-interoperable products.
The result of this initial project will be an ID-WSF 2.0 WSC Client Library. This document is meant to document the approach that will be taken to develop this library both philosophically and technically. It is meant to apply to a Java Client Library, which is our first goal, but also to any other platform that is planned. Ruby and .NET libraries are planned, and will likely follow the same philosophical approach, but will differ in technology decisions (such as layering) due to the requirements and available libraries.
The practical scope of the architecture document is the Java implementation. It is also likely that during the development process this scope may change.
Definitions, Acronyms and Abbreviations
Please reference the "Liberty Technical Glossary," Version v2.0, Liberty Alliance Project (30 July, 2006) [LibertyGlossary]
This document should contain all of the elements necessary to guide development of the ID-WSF 2.0 WSC Client Library. The ↓ Architectural Representation outlines how the ID-WSF 2.0 is represented in the Identity space as of the writing of this document. It has information and links to other projects. The ↓ Architectural Goals and Constraints section describes the requirements, objectives, development tools, and libraries that will be used and adhered to during the development process. The ↓ Use Case section identifies the initial goal of the project, which is to provide the library for a web hosted WSC. The ↓ Logical View provides a breakdown of components and classes of the API.
From the Logical View, Some sections of note:
- ↓ org.openliberty.wsc.services - Contains descriptions of the various service client classes that will be built to model interaction with various ID-WSF Services. The information within has been distilled from specifications and discussions with industry experts to contain only what is necessary to build classes from the WSC perspective.
- ↓ org.openliberty.wsc - Describes the building blocks that are used to define the service clients, keep track of context, and model the specific ID-WSF Messaging.
Currently there are a number of open-source projects and commercial products targeting ID-WSF 2.0 WSC (see the → Identity Landscape document on this wiki) that will be used to varying degrees to confirm ClientLib's general ID-WSF interoperability, including:
- → Connor Cahill's OpenSource ID-WSF Tools (C++ implementation)
- → Lasso (Liberty Alliance Single Sign On) Project (C implementation w/.NET bindings)
- → ZXID Project (C implementation)
For an up to date list of software that has gone through Liberty Interoperability (LIOP) testing for ID-WSF 2.0 see the ID-WSF 2.0 Interoperable Product Table. At the time that this document was authored, none of the open-source projects are fully complete. However, some implementations are well developed and are being tested with test harnesses to exercise portions of the functionality.
Architectural Goals and Constraints
This section describes the software requirements and objectives that have some significant impact on the architecture. It also captures decisions that have been made regarding development tools to be used and industry standards to be adopted.
The following is a set of WSC Library requirements extracted from multiple openLiberty specifications:
Use and distribution of the ClientLib project deliverables (i.e., the library itself) must comply with the Apache Software Foundation's license terms.
Development Tools and Resources
Eclipse / Subversion
The ClientLib developers will be using subversion for version control and Eclipse for a development platform. However, there is nothing keeping developers from using vi and javac. Subversion is an open source version control system that is an excellent replacement for CVS. It is full featured, well supported, and easy to use. Eclipse is an open source development platform, written in Java. We will be using it as our IDE. Its sole requirement is a Java Runtime Environment. As of this writing Eclipse is designed to run on a Java 1.4 environment. However, it is used widely with Java 1.5.
SourceForge.net is the world's largest open-source software development web site. It is also a centralized resource for managing projects, issues, communications, and code.
J2SE 5.0 (Java 1.5)
We expect to be taking advantage of the performance and language improvements introduced with Java 1.5. These include concepts like Collections. Also, some of the libraries that we've chosen to use rely on Java 1.5, such as the OpenSAML libraries.
Below we've listed the important standards upon which the project will be based. Of course this could be broken into many subsets, ad nauseum, but we have chosen to keep it clear.
This library is based entirely on the specifications set forth by the Liberty Alliance project for web services. ID-WSF 2.0 specifications are available on the Liberty Alliance Project's website. The ClientLib will focus on implementing only those features that pertain to the Web Services Client role (WSC).
ID-WSF 2.0 utilizes SOAP as the foundation layer for ID* messaging, uses WS-Addressing to include end point addressing that does not rely on HTTP, and uses WS-Security to apply security mechanisms to the SOAP exchanges.
"Liberty ID-WSF uses SAML as the mechanism by which the authentication status of a user and the identity and authorizations of web sites can be communicated as part of a SOAP request for some piece of that user's personal information." (Paul Madsen, SAML 2: The Building Blocks of Federated Identity)
Document Object Model (DOM)
We will be using DOM as specified the W3C. DOM allows for dynamic access to the XML documents upon which all of the ID* messages are based. It does this by first loading the entire XML document into memory. Among other things, using DOM will allow us to integrate with OpenSAML's libraries which will give us the ability to take advantage of signing.
Java API for XML Processing
We will be using the DOM API as represented by JAXP 1.3. We have decided at this point that the project will rely on Apache's Xerces2 for this functionality - which is also used by OpenSAML.
Open Source Libraries
In order to take advantage of a great deal of already written code that implements some very difficult and central aspects of web services, the openLiberty developers have decided to use some of the OpenSAML 2.0 java libraries. These libraries are the basis for the Java version of Shibboleth, an open source, standards based, Web Single SignOn (SSO) middleware.
java-xmltooling is OpenSAML's Java XML Tooling library. The ClientLib will be using this library to model the ID-* XML messages (SOAP Documents). The XML will be broken down into logical fragments which will be implemented by subclasses of XMLObject, XMLObjectBuilder, XMLObjectMarshaller, XMLObjectUnmarshaller, and the XMLObjectValidator classes. These will become the low level objects that the ClientLib uses to interact with the SOAP layer.
The WSC ClientLib will take advantage of the built in security mechanisms that the OpenSAML project supports. This includes XML Signature.
java-openws is OpenSAML's Java SOAP implementation. It is built on java-xmltooling.
java-opensaml2 is the Java OpenSAML version 2 library. The WSC ClientLib will utilize this library to manage SAML2 tokens properly, and to generate and SAML2 assertions as needed. This library is build on the java-xmltooling library.
Apache Xerces 2.9.0
We will likely be relying on Xerces2 for high performance and fully compliant XML parsing. This dependency will primarily be through the OpenSAML libraries.
Xalan-Java 2.7.0 will be an underlying dependency and will be used for any XSLT processing that we do.
Initial Use Case: Web Hosted WSC
The initial use case that we will be using for development is the Web Hosted WSC. We’ll be focusing on 1. a WSC that uses a Discovery Service and 2. a WSC with preset EPRs using SSOS. The ClientLib will be a full implementation of the ID-WSF WSC, so any use case you can think of will be applicable.
This section illustrates how the software actually works by giving a few selected use-case (or scenario) realizations, and explains how the various design model elements contribute to their functionality.
As a reminder for what we hope to achieve with this section: This section describes the architecturally significant parts of the design model, such as its decomposition into subsystems and packages. And for each significant package, its decomposition into classes and class utilities. You should introduce architecturally significant classes and describe their responsibilities, as well as a few very important relationships, operations, and attributes.
It is planned that this portion of the architecture document will eventually become the basis for documentation and sample code (outside of the javadoc), and therefore, we will be adding to, correcting, and clarifying this section on an ongoing basis.
As described in the Implementation View, our initial thinking is that the ClientLib will be divided into two logical layers, Kit and Core. The goal of the Core Layer is to implement the ID-WSF 2.0 WSC as closely to the specifications as possible, with an emphasis on performance, allowing for the ClientLib User to have granular access to service interaction. The Kit will be designed for maximum usability, modeling the most widely used mechanisms and defaults, allowing for rapid integration and easy adoption.
In this section we have allocated (mostly for thinking purposes) the various major objects into org.openliberty.wsc and org.openliberty.wec.services. Both of these are likely to exist in part across both logical layers. org.openliberty.wsc models the basic elements that will be employed by the ClientLib. org.openliberty.wec.services contains information and details of the various service clients that the ClientLib will define and implement.
This is the heart of the WSC ClientLib. All of the basic elements defined in WSF 2.0 are modeled here. We also define a "Context" which when instantiated will manage persistent data.
Context is the master object within which all operations take place. It contains everything required to serialize a set of service instances in motion and bring them back to life. It may also be valuable to initialize some basics which may take a good deal of time, like a cryptographic pseudorandom number generator for generating message ids.
NOTE: It is entirely possible that the ClientLib does not provide any context handling but rather leaves that up to the User. That said each Service Client and any stored message / EPR will need to be serializable.
An endpoint reference is a reference to a service instance. It contains the address, security tokens, and other metadata necessary for contacting the identified service instance.
A Service Client is the base class that is created to wrap the process and components required to invoke and utilize a service. It will be an abstract super class and is extended by all service clients within the ClientLib (e.g. - Discover Service Client). Each service client will have its own service specific features and processing.
A chain of EPRs will be stored within the client representing the EPR used to invoke the service and any EPRs that were invoked as a result of redirection from the instantiated services. In general this chain is likely to be a single EPR.
- After a service is invoked with an EPR, a the Service Client is capable of sending and processing ID-* messages.
- Will define a mechanism for handling SOAP Message Status. This will be extended as needed by actual service clients
ServiceInstance will be represented by the Service Client↑
ServiceRequest extends WSFMessage
An ID-* message which represents a request made by the WSC.
ServiceResponse extends WSFMessage
An ID-* message which represents the response from a WSP to a WSC.
This class will model all ID-* required SOAP bindings. ID-WSF SOAP binding defines a "mapping of ID-* messages onto SOAP [SOAPv1.1], an XML-based [XML] messaging protocol." We expect to be using the java-openws from OpenSAML 2 to model the basic SOAP requirements and then extending them to include ID-WSF specifics.
The SOAP header and body of each ServiceRequest will contain XML fragments, some universal, some specific to a service, and some not defined withing the ClientLib. These fragments will be represented (and objectified) by extending and implementing the necessary java-xmltooling and java-openws classes.
The status of an ID-* message.
The ClientLib User will have the ability to access message status at all levels through this class. This will include SOAP level, WS-Addressing level, and ID-* Fault Messages.
This class stores Security and Identity Tokens. These tokens are contained within the SecurityContext element of an EPR, and they will be either (urn:liberty:security:tokenusage:2006-02:SecurityToken) or (urn:liberty:security:tokenusage:2006-08:TargetIdentity).
- At some level, these tokens will need to be extracted from the EPRs and placed in the header of messages to services requiring these tokens.
- Tokens of type 2006-02:SecurityToken are placed inside of the <wsse:Security> header block. If multiple SecurityTokens are within the DS security context, then they will all be placed in the security header block.
- Tokens of type 2006-08:TargetIdentity is placed in the <sb:TargetIdentity> header block.
See ↑ Security Token
This package contains the details of the specific ID-WSF 2.0 Service Clients.
Discovery Service Client
An ID-WSF Discovery Service Client (DS Client) will query a Discovery Service (DS) to find and retrieve EPRS for other ID-WSF Service Instances. The EPRs returned, if any, will fit the requirements specified by the DS Client in the DS query and provide the address and meta-data required to invoke the service described in the EPR.
Authentication Service Client
- based on LibertyAuthnContext
The ID-WSF Single Sign-On Service (SSO Service, or SSOS) provides requesters with an ID-WSF-based means to obtain SAML 2.0 authentication assertions enabling them to interact with SAML 2.0 Service Providers as well as other services that accept SAML 2.0 assertions as security tokens, such as web services (including ID-WSF WSPs). - LibertyAuthnContext
DST Service Client (abstract)
The Data Service Template ("DST") is a template that may be used by an ID-WSF Service for providing access to data services. The DST Client Service that will be implemented in the Clientlib will model the WSC's access to a service employing the DST template. It will model creation, query, modification, and deletion of data attributes exposed by a data service as related to a Principal. However, this class will be abstract, requiring the ClientLib user to define its own DTS Service Client which will be written specifically to fulfill the requirements of the ID-WSF Service that employing DST.
Personal Profile Service
The Liberty ID-SIS Personal Profile ("ID-SIS-PP") is an instance of the DST specification and defines a web service that offers information about Principles themselves.
Subscription Service Client
Planned for second pass development.
Interaction Service Client
As of now this service, which facilitates interaction with the principal, is not planned for the first round of development on the ClientLib. If you would like to see this developed, please contact us.
People Service Client
The ID-WSF People Service Client (PS Client) will provide the necessary mechanisms for interaction with PS instances.
This section describes the overall physical structure of the ClientLib software, including its constituent layers and components. It also discusses practical implementation details that should help maximize the usefulness of the library and enable its effective operation in real-world scenarios.
In the sections below, we discuss the various code layers that define the WSC and the boundaries between them. We also discuss the implementation of these layers as it pertains to undertanding and using the ClientLib.
The ClientLib library exposes its WSC functions at two different levels: The “core” level and the “kit” level as shown in the following diagram:
The objective behind exposing two interface levels (and of the Kit layer functions in particular), is to facilitate rapid, painless development of more common solutions. In this way, developers can achieve quick results which should result in quicker adoption of the Liberty model by various interested parties – and ideally lead to success-driven organic growth in the ID-WSF community.
WSC Service Client Kit Layer
Objects and Methods exposed at the Kit level in the ClientLib are intended to streamline development of the most-commonly used elements in the more typical WSC-to-WSP configurations. At this level, the number of components and the complexity of those components are kept to a minimum in order to facilitate rapid development of straightforward implementations.
High performance will be an objective of the Kit layer, but not to the detriment of usability. We believe that the Kit should not only expose a common usage but to some degree encourage and demonstrate desirable use-cases. If the API has human readable logic to it, adoption will be more likely.
Components exposed at the Kit level may utilize multiple Core level components. It is also likely that some kit level components will be simple wrappers around Core components with some established default values.
WSC Service Client Core Layer
The Core level of the ClientLib is a lower-level interface that exposes the primary mechanics of the WSC. It allows for more control and flexibility in the usage of WSC functions and exposes less common features and functions that may be of interest to the developer. Within the requirements set forth by the ID-WSF 2.0 Specs, the core level will have an emphasis on performance. We expect that most high performance users of the ClientLib will chose to use the core library over the kit.
At the core level, the ClientLib will integrate with the necessary libraries from OpenSAML, which include java-openws and java-xmltooling. Objects will be modeled after the method prescribed by java-xmltooling. The SOAP bindings will be implemented as an extension of java-openws. SAML2 tokens will be managed transparently through the use of OpenSAML libraries, but are not necessarily required for implementation.
In order to extend the ClientLib a clear understanding of the Core layer will be required. Unlike the Kit layer, very few of the details of the Liberty ID-WSF 2.0 specification will be hidden.
Size and Performance
It is our goal to make the ClientLib as lightweight as possible. The ↑initial use case calls for the ability to potentially process a huge number requests asynchronously in a thread safe environment. Although DOM is known to be memory intensive, we believe that the size of ID-WSF SOAP messages is not significant enough to pose a memory problem with most modern day servers, and the advantages of using DOM are many, including the ability to easily handle signing.
ID-WSF Messaging protocol adds timing constraints to the soap message structure to insure security and validity of the interactions. The ClientLib will be aware of these limitations. It should also be noted that the library aims to be fully serializable so that transactions and messaging that may not be taking place in a session based environment can easily be accomplished in as little memory as possible through offloading into a database or a file system.
As mentioned in descriptions of the Kit and Core layers, one of the primary objectives of the ClientLib is to provide as high performance a mechanism as possible for ID-WSF interaction within the constraints of Java and the ID-WSF 2.0 specifications. SOAP (and XML for that matter), for example, has been criticized for inefficiency imposed by its lengthy format. Furthermore, in order to embed necessary security and addressing mechanisms, ID-WSF requires SOAP use of additional industry standard SOAP extensions (such as WS-Addressing). However, it should be noted that once trust and identity have been established between the WSC and the WSP, it is likely, where high performance interaction is required, that the Service Provider and Service Consumer will be utilizing mechanisms outside of ID-WSF.
As an open-source initiative, the ClientLib library itself will continue to evolve over time. As with any open-source product, the quality – in terms of performance, reliability, and overall robustness – will be derived not by a single all-encompassing QA process, but rather by feedback and contributions from the community of critical early users and the continual improvements that define its evolution.