ESOE Web Services Design

Enterprise Sign On Engine Technical Architecture
Written by Bradley Beddoes
September 2006

Architecture design by Bradley Beddoes
Incorporates SAML 2.0, and (L)XACML 2.0 OASIS standards

Contributions by:
Shaun Mangelsdorf
Andre Zitelli

Edited by:
Bradley Beddoes
Shaun Mangelsdorf
Andre Zitelli

The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
"SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY",
and "OPTIONAL" in this document are to be interpreted as
described in RFC 2119

Web Services Interfaces

Component Lead Shaun Mangelsdorf
Package com.qut.middleware.esoe.ws.\*

Web service interfaces in the ESOE are created using the Axis2, the ESOE makes use of RAWXMLInputOutput to ensure it gets the lowest level access possible to the creation and handling of the SOAP envelope.

All web serivce endpoints in the system are exposed using the Axis2 <-> Spring 2.0 IoC wiring interfaces to allow for customisable deployments.

WSClient

Component Lead Shaun Mangelsdorf
Package com.qut.middleware.esoe.ws.clients.WSClient
Exceptions WSClientException

The WSClient is responsible for communicating to SPEP's using web services when the IDP needs to provide them some kind of update.

This interface is only used to connect to SPEP, it does not specify an endpoint on which to receive incoming requests.

At the current time it implements functions for initiating an authz cache clear and single logout. These functions MUST be supplied with a valid SAML request document and a valid endpoint URI to connect to. The WSClient is solely responsible for handling all SOAP interactions and envelope wrapping/unwrapping.

Should the WSClient at any stage of communication encounter an exception or error state it MUST wrap this error or exception in WSClientException and throw for the caller to deal with.

WSProcessor

WSProcessor is the implementation of all logic for web services interfaces that the ESOE exposes for SPEP's to connect to. It is configured as the service class for Axis2 services.xml file and currently exposes three core functions.

Attribute Authority

This endpoint is responsible for receiving requests from the SPEP, this webservice does not initiate requests.

This service is accessible at the URL https://esoe.url/axis2/services/esoe/attributeAuthority

Using Spring, a processor will be injected into this descriptor, this object MUST implement the com.qut.middleware.esoe.aa.AttributeAuthorityProcessor interface. A bean which implements the interface com.qut.middleware.esoe.aa.bean.AAProcessorData interface must be created and SAML request object stored at com.qut.middleware.esoe.aa.bean.AAProcessorData.requestDocument. Once generated the execute function on the injected AttributeAuthorityProcessor MUST be called with the created bean as an argument.

Handled return values and actions

com.qut.middleware.esoe.aa.om.qut.middleware.esoe.aa.AttributeAuthorityProcessor.result.Successful

The value stored at com.qut.middleware.esoe.aa.bean.AAProcessorData.responseDocument should be wrapped in a SOAP response and sent back to the requestor.

Handled exceptions and actions

com.qut.middleware.esoe.aa.exception.InvalidRequestException

The value stored at com.qut.middleware.esoe.aa.bean.AAProcessorData.responseDocument should be wrapped in a SOAP response and sent back to the requestor.

Policy Decision Point

This endpoint is responsible for receiving requests from the SPEP, this webservice does not initiate requests.

This service is accessible at the URL https://esoe.url/axis2/services/esoe/policyDecisionPoint

Using Spring, a processor for lxacml requests will be injected into this descriptor, this object MUST implement the com.qut.middleware.esoe.pdp.AuthorizationProcessor interface. A bean which implements the interface com.qut.middleware.esoe.pdp.bean.AuthorizationProcessorData interface must be created. The SAML request document MUST be unwrapped from the SOAP message and stored at com.qut.middleware.esoe.pdp.bean.AuthorizationProcessorData.requestDocument. Once generated the execute function on the injected AuthorizationProcessor MUST be called with the created bean as an argument.

Handled return values and actions

com.qut.middleware.esoe.pdp.AuthorizationProcessor.result.Successful

The value stored at com.qut.middleware.esoe.pdp.bean.AuthorizationProcessorData.responseDocument should be wrapped in a SOAP response and sent back to the requestor.

Handled exceptions and actions

com.qut.middleware.esoe.pdp.exception.InvalidRequestException
The value stored at com.qut.middleware.esoe.pdp.bean.AuthorizationProcessorData.responseDocument should be wrapped in a SOAP response and sent back to the requestor.

com.qut.middleware.esoe.pdp.exception.InvalidPrincipalException
The value stored at com.qut.middleware.esoe.pdp.bean.AuthorizationProcessorData.responseDocument should be wrapped in a SOAP responseand sent back to the requestor.

SPEP Startup

This endpoint is responsible for receiving requests from the SPEP, this webservice does not initiate requests.

This service is accessible at the URL https://esoe.url/axis2/services/esoe/spepStartup

Using Spring, a processor for esoe requests will be injected into this descriptor, this object MUST implement the com.qut.middleware.esoe.spep.SPEPProcessor interface. A bean which implements the interface com.qut.middleware.esoe.spep.bean.SPEPProcessorData interface must be created and contain the SAML request object. Once generated the execute function on the injected ESOEProcessor MUST be called with the created bean as an argument.

Handled return values and actions

The startup service will not return a value, if no exception is thrown the value stored at com.qut.middleware.esoe.spep.bean.SPEPProcessorData.responseDocument should be wrapped in a SOAP evelope and HTTP document and sent back to the requestor.

Handled exceptions and actions

com.qut.middleware.esoe.spep.exception.CacheUpdateFailureException

The value stored at com.qut.middleware.esoe.spep.bean.SPEPProcessorData.responseDocument should be wrapped in a SOAP evelope and HTTP document and sent back to the requestor.

com.qut.middleware.esoe.spep.exception.InvalidRequestException

The value stored at com.qut.middleware.esoe.spep.bean.SPEPProcessorData.responseDocument should be wrapped in a SOAP evelope and HTTP document and sent back to the requestor.

com.qut.middleware.esoe.spep.exception.NoSuchSPEPException

The value stored at com.qut.middleware.esoe.spep.bean.SPEPProcessorData.responseDocument should be wrapped in a SOAP evelope and HTTP document and sent back to the requestor.

Delegated AuthN

This endpoint is responsible for receiving requests from the delegated Authn handlers with unique knowledge of some particular protocol, this webservice does not initiate requests.

This service is accessible at the URL https://esoe.url/axis2/services/esoe/delegatedAuthn

Further design doco to follow.