Comparison of external authentication mechanisms for WebSEAL

What requirements to look for when deciding between the C and HTTP external authentication interfaces

This article compares the two supported mechanisms for providing custom authentication services within IBM® Tivoli® Access Manager for e-business (TAMeB) WebSEAL, C and HTTP, and identifies key differences between them. These key differences are used to identify sets of requirements where one approach is more suitable than the other. A reader can then use these differences to determine which approach to use for their custom authentication processing.


Chris Choi, IT Specialist, IBM

Chris ChoiChris Choi is an IT specialist in the Tivoli Security Team based on the Gold Coast, Australia. Chris works in a customer related role, participating in both pre-sales and post-sales activities in Asia Pacific.

developerWorks Contributing author

Peter Cogill (, Software Engineer, IBM

Peter CogillPeter Cogill is a software engineer on the IBM Tivoli Access Manager team. He joined this team in 2003 after graduating from the University of Queensland with a Bachelor of Engineering (Software).

31 July 2007


Note: Not just WebSEAL

Throughout the document, reference will be made to using external authentication with WebSEAL. The same functionality, with the same key differences and characteristics, is also provided with Tivoli Access Manager Plug-in for Web Servers (AMWebPI).

Tivoli Access Manager WebSEAL provides a number of ready-to-use authentication mechanisms that cater to a wide variety of common uses including username and password, RSA SecurId Token and digital certificate. However, customers often have additional authentication requirements that go beyond the scope of the authentication mechanisms provided, such as integration with an existing authentication infrastructure or requirements for a more complex authentication scheme. To accommodate these customers, WebSEAL provides two external authentication mechanisms, the External Authentication C API (formerly the cross-domain authentication service, or CDAS) and the External Authentication HTTP Interface. WebSEAL can then offload all user identity related tasks (authentication and password change) to a custom authentication module written to either of these interfaces. For the remainder of the article, the terms C API and HTTP Interface will refer to the External Authentication C API and External Authentication HTTP Interface, respectively.

External Authentication C API

Prior to the release of Tivoli Access Manager WebSEAL 6.0, the External Authentication C API was the only supported custom authentication mechanism. To use the external authentication C API, you must create a shared library that implements the four functions defined in the API:

  • xauthn_initialize
  • xauthn_authenticate
  • xauthn_change_password
  • xauthn_shutdown

The shared library must then be deployed to the WebSEAL machine and WebSEAL must be configured to use that library for authentication.

Figure 1 below illustrates the authentication process when WebSEAL is configured to use a custom authentication module written to the External Authentication C API.

Figure 1. External Authentication C API module processing
External Authentication C API module processing

Figure 2 below shows the purpose of each interface function in the C API.

Figure 2. External Authentication C API functions
External Authentication C API functions

During initialization, WebSEAL loads the shared library into its process space and calls the xauthn_initialize function to initialize the custom authentication module. The shared library's xauthn_authenticate function is then called by WebSEAL to authenticate the user after the relevant authentication details have been gathered from the user. If this function successfully authenticates the user, it returns a TAMeB user identity, from which WebSEAL creates a credential for the user. Similarly, the xauthn_change_password will be called by WebSEAL to allow the custom authentication module to update the user's password after WebSEAL gathers the relevant information. Finally, the xauthn_shutdown function is called during the WebSEAL shutdown procedure to allow the shared library to clean up any necessary resources.

External Authentication HTTP Interface

The External Authentication HTTP Interface provides an additional custom authentication mechanism. The HTTP Interface does not specify a set of functions that the custom authentication module must implement. Instead the contract is that the custom authentication module provides either the user identity or a Tivoli Access Manager credential for the user to WebSEAL in a configurable HTTP header. Because the life-cycle of the custom authentication module is no longer tied to the life-cycle of WebSEAL, the External Authentication HTTP Interface does not define any initialization or shutdown requests, nor does it define password change requests. In fact, the number of functions the HTTP interface must implement is decided by the overall design of the WebSEAL system. This might include functions not limited to authentication and can include change password and general error processing.

Within WebSEAL, the External Authentication Interface (EAI) module manages the configuration and session state information required to handle authentications made using the External Authentication HTTP Interface. The WebSEAL configuration includes a pattern for the custom authentication mechanism's URI (also called the trigger URL), the header that will contain the user's identity or credential and the type of information that will be returned in the header.

Figure 3 below illustrates the authentication process when WebSEAL is configured to use the External Authentication HTTP Interface. The challenge and response messages, shown with dashed lines, can be omitted or repeated multiple times depending on the requirements of the authentication protocol.

Figure 3. External Authentication HTTP Interface processing
External Authentication HTTP Interface processing

Similar but different

Unlike WebSEAL, AMWebPI does not proxy the request to an external server; instead it allows the request to be handled by the underlying web server. The response generated by the web server is then captured and examined just like WebSEAL.

When WebSEAL receives a request for a URI that matches the pattern defined for the trigger URL, it forwards the request to the custom authentication module and waits for a response. If the response from the custom authentication module contains the user's identity, WebSEAL creates a credential for the user and treats them as authenticated. If the response contains the user's credential, this credential will be loaded without invoking the credential creation process within WebSEAL. Lastly, if the response does not contain the user's identity or credential, it will be forwarded to the client. Subsequent requests from the client to the trigger URL will be streamed through WebSEAL until the custom authentication module provides the user's identity or credential in the configured HTTP header. This streaming of requests allows the custom authentication module to perform multi-phase or challenge and response authentication techniques.

Key differences

The main concept to be gathered from the Introduction is that the two authentication methods are invoked by WebSEAL in two very different ways: Authentication modules written to the C API will be co-resident with the WebSEAL process and invoked natively, whereas authentication modules created with the HTTP Interface are not co-resident with WebSEAL and will be invoked via a HTTP request. Most of the characteristic differences between the two mechanisms arise from this fundamental difference.

Functional considerations

Although the two mechanisms both provide the same basic service to WebSEAL, there is a difference between the capabilities they provide. Using the C API, the authentication information is gathered by WebSEAL and presented to the custom authentication module for processing. The type of information that is gathered will depend on the type of authentication processing being performed (password, token, etc); however the data that is gathered is fixed. The authentication module cannot retrieve additional information or perform a multi-phase authentication operation. This is not the case for authentication modules written against the HTTP Interface, as the entire HTTP request data will be available for it to use. In addition, the reply from the authentication module will be streamed to the user if it does not contain the user's identity or credential. This allows modules written against the HTTP Interface to implement a multi-phase or challenge and response authentication algorithm.

Development and maintenance considerations

From a development view-point, the primary difference between the two custom authentication mechanisms is that the C API requires the module to be written in C for the platform that WebSEAL is running on. Using the HTTP Interface does not require the module to be written in any specific language, allowing the developer to choose a language, framework and tools that can allow for faster development, or have a richer set of standard libraries, or one that they're simply more familiar with. For example, an HTTP Interface-based implementation can be written in Java™ as an IBM WebSphere® application or in C# as a .NET application. In addition, the modules developed against the C API are loaded into the WebSEAL process, developers must be careful not to leak resources, such as memory or file descriptors, as this will directly impact on the WebSEAL process. More catastrophically, a crash within a C API custom authentication module will terminate the WebSEAL process that it is running within, causing an instant outage. Due to all these factors, some developers will find that a C API-based implementation is harder to develop and maintain compared to an HTTP Interface-based implementation written in an object-oriented language such as Java or C#.

Infrastructure considerations

One of the factors to consider is the additional infrastructure that is required to deploy the custom authentication solution. In the case of authentication modules written against the C API, there are no additional infrastructure requirements with WebSEAL managing the custom authentication module's entire life-cycle. In contrast to this, custom authentication modules written against the HTTP Interface require additional infrastructure. At a minimum this will be an HTTP server, however it is far more likely that this additional infrastructure will include a J2EE application server. This additional infrastructure will have to be provisioned and managed, increasing the total cost of a solution that uses the HTTP Interface compared to the C API.

Performance considerations

There are two aspects of system performance to consider when comparing the two authentication mechanisms. One aspect is how the choice of mechanism affects the performance of the authentication operation. The difference between the two mechanisms here is that authentication modules written against the HTTP Interface incur a larger overhead when invoked, because they require an HTTP request and response to be sent from WebSEAL to the application server as opposed to a C function call.

The other aspect of performance to consider is how the custom authentication module affects the performance of the system as a whole. In the case of authentication modules written against the C API, if the authentication module is performing computationally expensive operations, this can negatively impact on the ability of WebSEAL to process other requests, because WebSEAL and the custom authentication method compete for processor cycles. In the extreme case, all the WebSEAL worker threads might be tied up within the custom authentication mechanism preventing WebSEAL from handling any other requests. Authentication modules written against the HTTP Interface, when deployed on separate machines to WebSEAL, do not suffer from this problem.

Scalability considerations

The main point to keep in mind when considering scaling the two authentication mechanisms is that modules written against the C API are automatically scaled as the number of WebSEAL machines is increased, as the authentication module has to be deployed onto the WebSEAL machine. In contrast to this, custom authentication modules written against the HTTP Interface must be scaled proportionally as WebSEAL machines are added to ensure that the authentication module doesn't become a bottle-neck for the system. The flip-side to this is that if the usage characteristics of the system change resulting in a larger proportion of authentication operations than usual, then authentication modules written against the HTTP Interface can be scaled independently of WebSEAL.

Usage scenarios

As discussed, both the C API- and HTTP Interface-based external authentication implementations provide essentially the same function to WebSEAL. However, the implementation based on one interface will suit some situations better than the other. This section describes a number of real-world scenarios that demonstrates this.

Scenario one: Limited infrastructure

Often, the organization deploying the WebSEAL environment will have a limited infrastructure budget. To deploy an external authentication implementation based on the HTTP Interface, it would require more infrastructure resources to compensate for the overhead of running a separate process for the authentication. In order to ensure high availability of the authentication system, the process requires redundancy or fail-over capability, further increasing the infrastructure costs by requiring additional hardware and software.

Figure 4 illustrates the difference between two external authentication implementations in terms of the infrastructure requirements. It is evident that the C API-based implementation involves a significantly lower infrastructure cost, hence be more suitable for the organizations with a limited budget.

Figure 4. Infrastructure requirements
Infrastructure Requirements Comparison

Scenario two: Limited network performance

Another scenario that favors the C API implementation is one where the network infrastructure has a limited bandwidth and a high latency. The C API-based implementation is co-resident with the WebSEAL process, so it incurs no network cost when the authentication is invoked. However, for an HTTP Interface-based implementation, the authentication is usually invoked over the network. If the network infrastructure does not provide the sufficient response time, it quickly becomes a performance bottleneck for WebSEAL.

Scenario three: Functional load balancing

In most organizations, it's common for the authentication traffic to fluctuate over the course of a day, but maintain a standard daily profile. This is because users will generally log in when they arrive at work in the morning and then retain their session for an extended period of time. When using a C API custom authentication module, the only way to deal with surges in authentication traffic is to increase the number of WebSEAL machines. This, however, is an inflexible solution as the WebSEAL machines might go under utilized throughout the remainder of the day. Using the HTTP Interface, a completely separate set of resources can be allocated to handle the authentication, which allows for more efficient use of resources, provides better scalability and makes planning for infrastructure expansion easier.

Scenario four: Data zone proxy

A typical TAMeB network architecture consists of three zones: the demilitarized zone (DMZ), where WebSEAL resides, the application zone, which holds the applications, and the data zone, which contains the components that store the business data, such as databases and LDAP servers. Custom authentication modules generally require access to data zone components to perform the authentication operation. When written against the C API, this results in a component in the DMZ requiring access to a component in the data zone and bypassing the application zone, which is often a security concern for the customer. In contrast to this, a custom authentication module written against the HTTP Interface can reside in the application zone, receiving requests from WebSEAL in the DMZ and accessing the necessary components in the data zone. Using the HTTP Interface set up, no component needs to bypass a zone, instead each component communicates with only another component in its neighboring zones, so the security concern about the system architecture will not exist. Figure 5 shows the location of the various components in the two authentication mechanisms.

Figure 5. Data zone proxy
Data Zone Proxy Illustration

Scenario five: Complex authentication requirement

Some organizations might have very complex authentication requirements. The external authentication mechanism might have to interact with other components such as a database, an LDAP server, or another application. In this case, it would be beneficial to use the HTTP Interface-based implementation, because this gives the developers more freedom in terms of what software language, tools and frameworks can be used. For example, the HTTP Interface-based authentication application can be implemented as a WebSphere application. Such implementation can make use of the rich set of functions provided by Java framework as well as WebSphere software itself. This significantly reduces the development time, and the code will be easier to maintain.


Tivoli Access Manager WebSEAL allows a custom authentication service to be implemented using either the C API or the HTTP Interface. The C API-based implementation is ideal for environments where the authentication requirement is simple and the infrastructure budget is limited. On the other hand, the HTTP Interface-based implementation is suitable for satisfying a more complex authentication requirement at the expense of additional infrastructure cost. Every organization will have a different set of requirements and priorities, hence it is important to realize these differences and choose an implementation that best accommodates your needs.

The table below summarizes some of the differences discussed in this article.

Decision factorC API-basedHTTP Interface-based
Infrastructure costLowHigh
Development and maintenance costHighLow
Performance overheadLowHigh



developerWorks: Sign in

Required fields are indicated with an asterisk (*).

Need an IBM ID?
Forgot your IBM ID?

Forgot your password?
Change your password

By clicking Submit, you agree to the developerWorks terms of use.


The first time you sign into developerWorks, a profile is created for you. Information in your profile (your name, country/region, and company name) is displayed to the public and will accompany any content you post, unless you opt to hide your company name. You may update your IBM account at any time.

All information submitted is secure.

Choose your display name

The first time you sign in to developerWorks, a profile is created for you, so you need to choose a display name. Your display name accompanies the content you post on developerWorks.

Please choose a display name between 3-31 characters. Your display name must be unique in the developerWorks community and should not be your email address for privacy reasons.

Required fields are indicated with an asterisk (*).

(Must be between 3 – 31 characters.)

By clicking Submit, you agree to the developerWorks terms of use.


All information submitted is secure.

Dig deeper into Tivoli (service management) on developerWorks

Zone=Tivoli, Sample IT projects
ArticleTitle=Comparison of external authentication mechanisms for WebSEAL