ESOE Administrators Guide

Bradley Beddoes
Andre Zitelli
Shaun Mangelsdorf

Applicable Versions
Beta 2


Welcome to this Administrators guide to the Enterprise Sign On Engine (ESOE), we hope you'll find it an invaluable resource for configuring and managing your own deployments of this software.

The ESOE is built on the Java language and platform which provides a wealth of functionality to aid the implementation of what is a very complex set of requirements. Alongside the base platform are many open source projects including Spring, Apache XML Security, Apache Axis 2, JAXB, iBatis and others. Each of these projects lead the field in their particular areas of expertise which is why they have been selected and we thank the many developers on these projects for their excellent contributions.

Additionally the ESOE itself is open source and released under the Apache 2.0 license, so once you've become more familiar with the system we invite you to check out the developers section to customize for your own needs.

The Enterprise Sign On Engine (ESOE) is an advanced system which combines into a standards compliant solution identity management, single sign on to the web tier and deployment of advanced, centralized authorization policies to restrict access to content in a flexible and extensible manner.

In addition to these features the ESOE provides native understanding of many user centric and federated authentication solutions such as OpenID and Shibboleth. This allows enterprise to easily connect into the possibilities which these collaborative technologies bring without risking security or requiring modification to their internal systems. As future solutions come on board (for example Yahoo BBAuth) the ESOE is easily extensible to provide support for them allowing single point of implementation to automatically populate to all your applications.

The ESOE is designed around the OASIS SAML 2.0 specification and it's powerful authorization engine is built around a reduced version of the OASIS XACML 2.0 standard which is dubbed Lightweight eXtensible Authorization Control Markup Language or "LXACML".

With its ability to integrate identity from unlimited data repositories, automatically create sessions for users whom are logged into Windows Active Directory (actual true single sign on!), release only approved attributes about users to potentially untrusted applications and provide centralized, audit able authorization we believe that the ESOE presents an excellent choice amongst the varied SSO systems available today, commercially or otherwise.

Usage Scenarios

We'll discuss two usage scenarios here, there are many more possibilities however and we'd like to know how your using the system in ways which we may not have even thought of for inclusion here.

Scenario 1

The Queensland University of Technology has an in house developed system that web applications use, it provides a very basic form of single sign on, but always requires at least one entry of Username and Password from the principal. This system generates a cookie which is stored across the entire domain and presented to various applications which run some special code again developed in house for Java and Apache. Applications are managed by local service providers who are not necessarily experts in web server technology. These applications read that cookie do some basic cryptography and make LDAP connections to validate information and retrieve attributes about users. Each application requires much complex configuration, a unique LDAP account requiring contact with ITS and a turn around time of a few days. Authorization is adhoc and done locally from local on disk configuration files which have again an inhouse developed syntax, to provide assistance. No one knows what versions of software are running for any given service, who is the technical administrator of the service, or indeed what services are even using this solution. To provide assistance to administrators local accounts are required on hosts, sometimes requiring fire wall changes which can take a long time to become approved due to security approval processes. Finally the University is wanting to push all these great applications to federated users, some using shibboleth, some using openID, others still looking at Yahoo BB Auth, naturally with the IT security team screaming about all of this not being secure.

How the ESOE solution addresses these issues:

  • As an open source product this solution breaks down the problems associated with being developed in house and then left to rot or being poorly maintained by other developers who come along in the future to find no documentation and no way to contact the original authors. They make some hacks, get it to work deploy it somewhere and leave, the cycle then repeats itself a few months later.
  • Using automated signon methods the ESOE can get to the point where it requires no user credentials to ever be manually entered. At the present we support this with integration to Windows Active Directory credentials, in the future we'll expand this to PKI solutions for other operating systems, smart cards and more
  • The system still uses cookies, but they are stored as 1 cookie per service both in domain and path, with the only value they contain being a 32 byte randomly generated hex encoded value with greater then 2 ^ -320 chance of being duplicated, these cookies are also restricted for presentation to SSL enabled sites only.
  • Applications never talk to an identity store, via LDAP, Database or any other method. They communicate using SAML assertions directly with the ESOE which provides everything they need in a standardized secure way without any requirement for local accounts or involvement by any central administrator.
  • Authorization is completely centrally controlled for each resource the principal tries to access the application will ask the ESOE if this is allowed and process a simple Allow/Deny response again wrapped in a SAML assertion.
  • Authorization policies are also centrally stored and modifiable via web browser management interface, allowing collaboration amongst application administrators and support staff with ease. Policies are simple to read XML markup which will be made even easier once the planned web based policy editing GUI is available.
  • Support requests are all able to be handled centrally, support staff can see the exact configuration details which are deployed remotely, can see advanced details about the service including versioning for the software being used, the operating system, IP addresses and more. The ESOE is even smart enough to report why an application may be failing to start correctly.
  • In addition to the above central system administrators can easily see what software needs to be upgraded when patches are released and contact technical staff to carry out this work appropriately. Due to the historical data gathered by the ESOE upgrade trends can be established over time. Should application administrators not be following policy and upgrading software in defined time lines their service can be disabled until they do so.
  • Federation support is simple for the ESOE. It understands Shibboleth, OpenID and in the future others. A principal can login through one of these methods and be provided automatic access to deployed applications. Of course as an enterprise you probably won't want to allow these external principals access to all your applications. Using the authorization policies they will only get access to the applications and content that they specifically should.

Scenario 2

As an online service provider I have many nodes which load balance requests for content, each of which the user must have a valid login to access. With much hype in the identity arena we are under increased pressure to support multiple methods to allow our paying customers to sign in, without forcing them to create and manage local accounts. The issue is everyone wants something different, OpenID for business, Shibboleth for higher education even direct connections to one customers LDAP server. The problem is we can't support all these technologies in the backend we'd have to deploy service providers for each type of authentication we want to support.

  1. The ESOE is designed to solve this issue with ease, in this particular case there are no internal authentication methods as their are no local users, which is more then fine.
  2. Shibboleth, OpenID etc are already supported in dedicated authentication delegators by the ESOE, the backend nodes would only need to understand the service provider enforcement point (SPEP) applicable to their technology set (Java/Apache/IIS) and this problem is solved.
  3. Additional authentication delegators are easy to write, if you choose to support connections directly to a customers LDAP server (or database or Web Services engine or even a flat text file) you could easily write this functionality, of course releasing it to the community for the good of others :).
  4. You may choose to then take advantage of the power of our authorization engine or leave this for a future software revision and continue using an in house developed solution, the option is yours.
  5. Load balancing across nodes is no problem at this point so long as its configured to always send the user requests to the same backend node. In the future our planned ESOE and SPEP cluster support will make this easier still.

Description of core components

Below we will describe in overview terms what each major component of the ESOE does. More in depth technical specifications and implementation details are located in the developers guide.

Authentication Processor

The authentication processor is designed to process all events which an individual deployment of the ESOE considers to be part of authentication. In most instances this will simply include the act of principal identification via some means supported by one of the base handlers documented below.

Handlers are configured in a pipleline which the authentication processor executes one by one. Handlers may choose to take some action or simply pass the request on down the line not invoking any logic, this may be the case when for example the principal is accessing the ESOE from outside the enterprise or if they are not running an Active Directory connected Windows host. Handlers themselves are grouped as Principal Identifiers and Non Principal Identifiers. Each group has upto four subclasses of handler which specify what rules the handler adheres to.

  • Automated - An automated handler is one which while it may interact with user-agent (browser) does not require the principal to enter any additional information to complete the identification process
  • Non Automated - A non automated handler is one which will require the principal to explicitly enter credentials to complete the identification process
  • Passive - A passive handler is one which MUST NOT take control of the principals user-agent in order to perform principal identification or other operations
  • Non Passive - A non passive handler is one which MUST take control of the principals user-agent in order to perform principal identification or other operations
  • Catch All - A special case of Non Automated handler which will actually block the authentication pipeline from completing until some condition is satisfied

Once a successful authentication has taken place the authentication processor will create a unique session identifier to be stored in the principals browser as cookie value which is a 32 byte randomly generated hex encoded value with greater then 2 ^ -320 chance of being duplicated. It then asks the session processor to create a session for the principal.

Once all this is completed the principal is redirected back to the original content which they came from, or if they access then authentication system directly an administrator configured welcome page.

Base Handlers

Username/Password form input authentication

The Username/Password Handler allows a principal to submit their username and password to a web form to identify themselves to the system, this is the most popular of methods currently in use today but the least secure and most intrusive.

This handler is of type Non Automated, Non Passive and Catch All. This means that it should be configured as the last handler in the pipeline to be capable of performing principal identification, of course other handlers which rely on the principal to be identified may still be configured after this.

If this handler detects that the principal is already successfully authenticated by an earlier stage of the pipeline it performs no operation and returns control to the authentication processor.

Automated Windows authentication

The Windows authentication handler processes special tickets which are generated by an Active Directory enabled Windows host that are created when the user logs in to Windows. Successful validation of these tickets against an AD domain controller will result in the principal identification being successfully established. Failure to do so will cause the handler to return control to the authentication processor.

This handler is of type Automated, Passive. This means it can be configured anywhere in the pipeline before a catch all handler.

If this handler detects that the principal is already successfully authenticated by an earlier stage of the pipeline it performs no operation and returns control to the authentication processor, it will also return control if it determines the principal is not a member of Active Directory.

Single Sign On Processor for Services

The single sign on processor for services handles principal requests for access to each service's SPEP that is deployed. These services may be wiki's, portals, blogs, static web pages infact anything that the principal may choose to interact with using a standard web browser. As the principal navigates to a new service the SPEP generates a SAML 2.0 compliant request and transfers this to the ESOE for validation by one of the supported profiles for principal to service identification. The supported profiles are listed below, it is envisaged this list will grow over time to fulfill more of the options in the SAML 2.0 specification.

Once this processor has received the request it will process it internally using the previously generated session data from the authentication processor and using the same profile as for the request returns an assertion decreeing that the principal should be or should not be granted a session on that service, along with some other important information, including a private ESOE and SPEP identifier that represents the principal. This identifier is once again unique from any identifier the principal ever sees in a session cookie.

Generally it would be expected that a principal would navigate to a service before having been identified by the authentication processor. If this is the case the single sign on processor for services will redirect the principal to the authentication processor for identification, upon successful completion of which they will be transfered back to the single sign on processor for services. The process documented above then continues as normal.

HTTP-POST profile

This is the default profile for ESOE and its SPEP software connectors.

When the user first vists SPEP protected content a SAML request is issued and stored in the response from the SPEP to the clients browser. This is then posted to the ESOE which uses it to undertake SSO processing. The ESOE likewise response with a SAML document to the clients browser. This is the posted to the SPEP which uses it to establish a session with the local service and redirect the user to the original content. (of course it may also cause a session to be denied).

HTTP-GET Profile

This is an optional profile for the ESOE.

When the user first connects to a remote service that service will generate a query string bound for the ESOE per SAML specification. The users browser is then issued a HTTP 302 redirect and sends a standard get request to the ESOE containing the created query string. In most circumstances the ESOE will respond to HTTP-GET with a HTTP-POST profile response (per SAML specification) due to the size of data being returned.

Single Logout Processor

The single logout processor handles logout for all services connected to the ESOE which a user has visited during their session. Once the user navigates to the ESOE logout page web service calls are made in the backend to each service to terminate local sessions for the user. This is different to the way you may be experienced with logout working in that there is no browser redirect to each service. Infact cookies for each service are actually retained with this process. The key is if the client does infact attempt to visit a service again after logout the SPEP will at that time void their cookies along with any application specific cookies that the service owner may wish to terminate, for example a cookie which sets an internal ID.

Principal Session Processor

The principal session processor is responsible for tracking all data about a user while they have an active session established with the ESOE and supporting SPEP's. It creates user sessions, updates them and removes them on logout or session timeout.

Part of its job is to map on the ESOE side the transient identifiers which change each session that are communicated to SPEP's with the real local identifiers of that user. The other important piece of work it does is to track user identifiers. In the case of remote login via an authentication delegator this information is communicated directly into the processor. For users who authenticate locally the processor is responsible for aggregating identity details to provide to SPEP's

Disparate identity source integrator

At startup the ESOE is configured with a number of identity resolvers, by default it is configured with an LDAP source but you may add any source you deem necessary with plugins. Using ESOE Manager administrators can configure with pieces of identity they wish to get from each backend system. Where identity attributes exist in multiple systems possibly under multiple names these can all be aggregated by the ESOE and presented in a clean unified namespace to SPEP's.

In this way your backend identity infrastructure can now be protected from applications in client space. This allows you to safely and easily perform backend changes while only needing to modify the configuration of the ESOE. If applications need some additional data you can configure it centrally and have it delivered to them easier then ever before.

Attribute Authority Processor

To use the above attribute data SPEP software will make a web service call to the ESOE when a user establishes a session to retrieve attribute data. Based on configured policies set by administrators the ESOE will then release attributes to the SPEP. This means that sensitive data will never be delivered to your wiki software for example while your finance system which is more trusted is able to utilize it.

Authorization Processor

The authorization processor is responsible for processing authorization policies for protected resources accessed by authenticated users and returning a decision based on the outcome of the policy evaluation. The processor will attempt to match resources against the set of policies defined for a given SPEP, returning the authorization value specified by the policy. If no policy rules can be matched against the requested resource, a default decision is returned. This default decision is configured in the ESOE global configuration parameter:


# Default authorization action

Where mode can ONLY be one of ALLOW or DENY

Authorization process

When a resource protected by an SPEP is requested, the SPEP will send a SAML 2.0 extension called a LXACML request to the authorization processor via a backend web service call. It will supply the users transient identifier so the authenticated user can be identified by the PDP. It also provides details on the resource being accessed in the form of a string.

The authorization processor will first attempt to retrieve the policy set associated with the requesting SPEP, using the supplied SPEP identifier. If no policies can be found for that SPEP, DENY is returned. This overrides any default authorization policy set in the ESOE global config. NOTE: The processor will retrieve said policy set from it's policy cache. The cache is updated from the central data store at regular intervals specified in the configuration parameter:

# Time in seconds to attempt to refresh updated policies from data repository

This being the case, policy changes made via the esoemanager web interface may take up to 'interval time' to be updated in the policy cache.

Next, the authorization processor will attempt to match the requested resource against the the targets specified in the authorization policy associated with the requesting SPEP. If a match is found the authorization processor will evaluate the rule that matched the requested resource. If no target match is found for the requested resource, the default authorization decision is returned.

We recommend that administrators read the document [Configuring Authorization Policies] to learn how to build LXACML policy documents. This is also useful reading for your service administrators.

While this document refers to resources primarily in terms of web level resources the PDP itself is actually generic. In the near future some powerful examples of using the PDP right down in internals of applications to control function access, database row access etc will be made available.


We aim to continually improve this documentation set to make it as easy as possible for new ESOE administrators to come online. We welcome any comments or additions you may have on the ESOE users mailing list at any time.

Also available in: HTML TXT