WSO2 Identity Solution – Implementation of a CardSpace Authentication Framework

Archived Content
This article is provided for historical perspective only, and may not reflect current conditions. Please refer to relevant product page for more up-to-date product information and resources.
  • By Dimuthu Leelarathne
  • 24 Aug, 2008


Microsoft CardSpace specification 1.0[1] is a Microsoft open standard[2]. The main goal of the specification is to connect disparate authentication systems by offering a technology that provides seamless interoperability between them. It is important to note that the CardSpace specification does not compete or replace existing authentication systems. Rather, it plays a role analogous to that of the Internet Protocol (IP) in the realm of networking.

Table of Contents

List of terms

User - is the entity that is associated with a digital identity.

Claim - is a piece of information about the subject that identity issuer asserts valid.

Identity provider(IdP) - Is an entity that provides a digital identity to a user. Digital identities created by different identity providers can carry different information and providing different levels of assurance on who the user claims to be.

Relying party(RP) - A relying party is an application that in some way relies on a digital identity. A relying party will frequently use an identity to authenticate a user. A typical example is an Internet Web site.

InfoCard (IC) - A statement issued by IdP to the user. It is digitally signed and is a XML file issued by the IdP, and includes information such as types of tokens and claims that can be issued.

Identity Selector - This is a piece of software that runs on a user's browser. It manages InfoCards and helps a user manage his identities.


While the Internet continues to generate increasing value for individuals and businesses, users are forced to maintain several digital online identities. People are used to entering their personal data without evaluating trustworthiness of Websites. There is no consistent framework that allows them to evaluate the authenticity, of Web sites they visit. As a result, online identity theft has become a common occurrence, and users are easily tricked into releasing banking and other important information. According to[3] phishing and pharming are thought to be one of the fastest growing segments of the computer industry, with an annual compound growth rate of 1000%.

The problem with the Internet is that it was designed without a digital identity layer. This has been described as follows. The Internet was built without a way to know who and what you are connecting to. Since this essential capability is missing, everyone offering an Internet service has had to come up with a workaround. It is fair to say that today's Internet, while missing a native identity layer, is based on a patchwork of identity one-offs[4].

Widows CardSpace specification attempts to give a solution to the identity problem by defining a common platform for existing identity technologies. It is a system of systems - a meta-identity system. The following figures demonstrate the user experience in using CardSpace. CardSpace is icing, on top of existing authentication systems such as OpenId and SAML. It checks authenticity of RP, as well as users.

Figure1 : User downloads a InfoCard Figure 2 : How InfoCard is used to login to a RP

  1. Download the login page
  2. Identity Selector shows available InfoCards
  3. User selects preferred identity
  4. Identity Selector sends requests to IdP asking for a security token to be issued to RP. IdP checks the authenticity of RP
  5. IdP issues security token encrypted by the public key of RP.
  6. Identity Selector forwards it to RP

Microsoft has implemented a complete set of CardSpace components for Windows-based systems. Other platforms are expected to produce a robust set of tools and components, to support these standards. WSO2 Identity Solution stepped up to address this problem. It has released an open-source Identity Provider and a set of RP components that can activate CardSpace authentication for Web applications hosted on the Apache Web server and J2EE Web applications.

As the Internet grows it is invaluable to implement and experiment in order to come up with a better solution to the identity problem. CardSpace is yet to stand the test of time and user response.

WSO2 Implementation of CardSpace

WSO2 Identity Solution is an open-source project and CardSpace implementation is it's main component. It contains an Identity Provider and several Relying Party components. Relying party components support web applications hosted in Apache Web Server and J2EE Web containers. There are a few vendors world-wide who has complete or partial implementations of the CardSpace specification. It is essential that numerous components built by different vendors inter-operate in order to achieve a meta-system of identity.

A subset of CardSpace specification was identified for the 1.X release of the Identity Provider. The identified subset of the features can be summarized as follows.

  • Issue SAML and OpenId tokens and allow users to download InfoCards based on UsernameToken and Self Issued SAML Tokens.
  • As diverse identity systems will be introduced into CardSpace over time, our implementation of Identity Provider should be highly extensible and modular in order to plugin any authentication technology that might be integrated in the future.

The user-base of Identity Provider is designed as a configurable module. The intention is that it should authenticate users from an existing company user storage or from the database shipped internally. This is expected to add, a huge marketing value to the Identity Solution. The design goals of Identity Provider can be listed as follows:

  • Use an extensible, modular architecture to allow future identity system plug-ins, plus high configurability.
  • Authenticate users and extract claims from the internally shipped user store or external user store. Can be LDAP servers or external RDBMS .
  • The user store should be configurable by the administrator
  • Provide a simple yet powerful administrative GUI. The administrator should be able to switch on/off features and configure them as desired
  • Identity Provider must have a GUI for users, so that they can download cards, register/un-register themselves as configured by the administrator.

WSO2 Identity Solution contains a set of relying party components. The intention is to enable developers integrate these InfoCards to Web applications with minimal work. Objectives of relying party can be listed as follows:

  • Provide generic implementations that process SAML/OpenID InfoCard logins in Apache Web servers and J2EE containers
  • Simplicity: The component should handle all complex processing and provide only required results to Web developers.
  • Power: The component should be powerful enough to allow developers perform validations at their discretion.

Technologies Used

Java and Java related technologies are used for the implementation of Identity Solution. The RP component for Apache Web Server was implemented using C . The CardSpace specification is based on SOAP, WS Security, WS-Security Policy, WS-Trust and WS-Message Exchange (WS-MEX) specifications. Following the nature of the CardSpace Specification, WSO2 Identity Solution has been designed to use existing open-source implementations as building blocks, rather than re-inventing the wheel.

  • Apache Axis2 /Java
  • Apache Rampart and WSS4J
  • WSO2 WS-MEX implementation
  • OpenID for Java
  • OpenSAML 2.0 implementation from OpenSAML
  • C libraries xmlsec, libxml, openssl

The real challenge was to build a system with all of the above different components from different open-source groups. Apache Struts was chosen over AJAX, to develop the UI of the Identity Provider because the UI needs minimal user interactions. This decision was supported by non-technical constraints such as resources and time.

Architecture of Identity Provider

Apache Rampart became the primary building block of the IdP implementation. Apache Rampart and WSS4J have a mature implementation of WS-Security, WS-Security Policy and WS-Trust specifications. It is analogous to the fact that InfoCard specification is mainly based on these WS Security specifications.

The four main components of the WSO2 IdP are,

  • Security Token Service (STS) by Apache Rampart
  • User Realm module
  • Card Issuer module
  • Administrator module

We are only going discuss about STS and User Realm modules as they were the components that required new design decisions. The other two modules have less architectural value.

Figure 3 : The four main components of IdP STS, User Realm, Card Issuer, STS by Apache Rampart

Security Token Service

This is the most important part of the IdP. Identity Solution used the Security Token Service (STS) provided by Apache Rampart. Rampart STS allows any authentication system to be plugged in. Therefore our design goal to allow many identity systems was automatically achieved.

However we had to shed a lot sweat coding the SAML token issuer module and OpenID token issuer module and testing the interoperability with the Microsoft Identity Selector. Rampart STS can issue SAML tokens, but it was not possible to configure the Rampart SAMLIssuer to support all the extensions required by the CardSpace specification. Therefore a new implementation of SAML generation was implemented and plugged into the Rampart STS. This became very useful when implementing SAML2.0 support in the post 1.0 releases using OpenSAML2.0 library.

Another Issuer was implemented to generate OpenId tokens. OpenId for Java library was used when implementing OpenId token issuer. WS-MEX implementation was plugged into Rampart STS successfully to perform the initial message exchange successfully with the Microsoft Identity Selector. Interoperability testing were done starting from the early development stages as and when new piece of code is written. This was the key factor for successful interoperability.

User Realm

The architecture of the IdP allows users to come from an external user store or the default user store shipped with the Identity Solution. This is facilitated by coding to an interface. User authentication and claim/value extraction implementation is done behind an interface named the Realm Interface and the rest of the system is blind to the actual implementation. Therefore, user authentication information and claim value information can be extracted from an existing company LDAP, or an RDBMS or from the internal database shipped with the product transparent to the rest of the system. If IdP is using the default internal database then user claim data has to added when new users are being registered. Current RDBMS implementation is designed to cover the most common use-cases. Anybody can write their own implementations of the Realm interface and plug-in their own user databases as preferred.

Relying Party Components

Today, there are many relying party implementations are one-off implentations. WSO2 took a different approach by developing a set of generic relying party components that can be reused by Web application developers. It will target Web applications running on Apache Web servers and J2EE containers. The components should handle complexity introduced by InfoCard logins and make life easy for Web developers.

Relying Party Component Processing Pattern

All WSO2 relying party components follow the same processing pattern. The design was targeted to give simple results to the Web developer. These actions were refined over and over based on trail and error, until we achieved the required simplicity. In the end the Web developer was reduced to reading a set of HTTP headers.

  1. Intercept the HTTP request to the application
  2. If it is a Login request, check whether the Token is present
  3. Decrypt the token
  4. Validate the signature of the token according to the validation mode
  5. Add a HTTP header named Status . The value will be true if successful or false if failed.
  6. Inject claim values as HTTP headers into the HTTP request so that the Web developer can read claims as HTTP headers.

Web developer is relieved of all of the above steps. He just can check the value of status header and read claim/values required.

Figure 4 : Relying party implementation Concept

Validation Modes of RP

One of the main objectives was that the component should be powerful enough to allow developers to do validations at their own discretion. Therefore all WSO2 relying party components have 4 modes of token validations. These modes are not listed in the CardSpace specification. WSO2 came up with the idea of 4 modes of validation to provide maximum flexibility and control to the web developer. The web developer has to pick one of the operating modes depending on his requirements. The default is CertValidate mode.

  • Promiscuous - In this mode, all tokens that has a valid signature are allowed
  • CertValidate - In this mode, all tokens that has a valid signature by an IDP who has a trusted certificate are allowed
  • WhiteList - First CertValidity checked and after that if the issuer DN is in the white list, the token is allowed
  • BlackList - First CertValidity checked and after that if the issuer DN is not listed in the BlackList, the token is allowed

All components read validation mode as a configuration parameter and performs the processing accordingly.

OpenSAML/OpenID InfoCard Relying Party

A servlet filters can intercept requests to the servlet containers based on request patterns. This concept was used when developing the generic relying party component and it became our revolutionary design decision. Hence OpenSAML/OpenID relying party component is completely based on a servelet filter named RelyingPartyServeletFilter . When RelyingPartyServeletFilter is deployed into a servlet container, it successfully intercept HTTP requests and processes the InfoCards according to the processing steps mentioned above. The parameters needed to process the Token must be given in the web.xml. For example, to validate the signature, the web.xml should contain information on public keys of accepted Identity Providers.

Relying Party Component for Apache2 (mod_cspace)

The goal was to design a module that can be used with any Web application running on Apache2, irrespective of its implementation language. Hence it should be able to add CardSpace authentication to Ruby, Python, CGI and etc.. Taking all these factors into consideration, we implemented CardSpace authentication as an Apache module in C, rather than providing many language specific implementations.

As mentioned in processing steps, the module intercepts HTTP request and processes them using libxml and xmlsec for C libraries.

Future Developments and Conclusion

Current implementation of Identity Provider, generates tokens backed by UsernameToken and SelfIssued SAML tokens. According to Cardspace specification it should be able to issue token issuance backed by X.509 v3 certificates and Kerberos tokens.

WSO2 CardSpace implementation was taken to User-Centric Identity Interop at Catalyst in Barcelona held in October 2007. Fifteen projects participated in the interoperability testing. The results are available here[5]

The major challenge was to maintain interoperability of WSO2 Identity provider, relying party components with other implementations. The meaning of CardSpace would be lost without such interoperability.


  3. Anti-Phishing Working Group Phishing Activity Trends Report of February 2005 cites an annual monthly growth rate in phishing sites between July through February of 26% per month, which represents a compound annual growth rate of 1600%.
  4. [5]


Dimuthu Leelarathne dimuthul at wso2 dot com