This article by Dimuthu Leelarathne describes how to introduce CardSpace authentication to J2EE Web applications using WSO2's Identity Solution.

Introduction

WSO2 Identity Solution [0] provides a set of components to enable CardSpace authentication for Web applications. It enables Windows CardSpace [1] authentication for J2EE applications using a servlet filter.

The servlet filter that introduces CardSpace is called "RelyingPartyFilter".  See Configuration manual of the RelyingPartyFilter [1] for details. This manual will be referenced in the rest of the rest of this document as "Java Servlet Filter Developer Guide".

Applies To

WSO2 Identity Solution	version 1.0
J2SE	version: jdk1.5

The article is organized into following sections.

• RelyingPartyFilter - A Servlet Filter
• Managed information card login or self issued information card login
• Implementing self Issued InfoCard login
• Implementing managed InfoCard login

RelyingPartyFilter - A Servlet Filter

RelyingPartyFilter must be deployed in your application to enable CardSpace login. You can deploy the servlet filter in your application in the same way you deploy any other servlet filter. Then it must be configured with the set of parameters in web.xml. For step by step information on how to install the RelyingPartyFilter and the complete list of parameters with sample possible values, please refer  "Java Servlet Fileter Developer Guide [1]".

CardSpace authentication can be enabled only on SSL protocol. Therefore, your Web application login must be secured using SSL. Private key of the SSL certificate will be used to encrypt SAML token sent to your Web application. Therefore, when giving configuration parameters required by RelyingPartyFilter in the web.xml, including values of Keystore, StorePass, KeyAlias, KeyPass, StoreType parameters must point to the keystore containing private key of the SSL certificate. If the keystore details are not given properly, the application will not startup.

What Happens Behind the Scene?

When a user submits an InforCard as a part of logging into the Web site, an encrypted SAML token will be generated as the login credentials. When RelyingPartyFilter is deployed in your Web application it will intercept this request. If the request contains "InfoCardSignin" parameter, then it will be processed.

Following list of actions will be performed by the RelyingPartyFilter:

• Extract encrypted SAML token from the request
• Decrypt the SAML token
• Validate the signature of the SAML token
• Check whether the SAML token meets policies specified in the web.xml. Namely IssuerPolicy and TokenValidationPolicy
• If the validation process is successful, the RelyingPartyFilter will add a parameter named "org.wso2.solutions.identity.rp.State" HTTP headers. The value will be "success" if successful, and it will contain "failure", if failed.
• Read other SAML attribute values as name value pairs and add it into the HTTP request.
• Read\issuer information and encapsulate it in a XML element. Then add it to the request.

After RelyingPartyFilter processes the request, it is then handed over to your application. Here is how you should read the values from the request.

 

String auth = (String)request.getAttribute(TokenVerifierConstants.SERVLET_ATTR_STATE);
	String welcomeString = "";
	
	if(auth != null && TokenVerifierConstants.STATE_SUCCESS.equals(auth)) {
		welcomeString = "Welcome "
		String issuerInfo = request.getAttribute("issuerInfo");
		//retrieving claims made by the user
		String givenName = (String)request.getAttribute(IdentityConstants.CLAIM_GIVEN_NAME);
		String surname = (String)request.getAttribute(IdentityConstants.CLAIM_SURNAME);
		String email = (String)request.getAttribute(IdentityConstants.CLAIM_EMAIL_ADDRESS);
		welcomeString = welcomeString + givenName + " " + surname + " "+email;
	}else{
		welcomeString = "Login Failure!!"
	}

 

Deploying the Sample Web Application

This article contains a couple of sample applications - one  that demonstrates CardSpace login [1] and the other demonstrating Card Registration [1]. Steps to run these samples are:

1. Install maven2 [2]
2. Build the project by typing "mvn clean install" inside the unzipped folder.
3. Enable SSL in your servlet container using the keystore available here [2]. The store password is "wso2is".
4. Drop the card-login-SNAPSHOT.war file to the webapps folder. Check whether SSL is working properly.
5. Point your browser to https://localhost:port/card-login-SNAPSHOT/index.jsp

Managed Information Card Login or Self Issued Information Card Login

You can enable Windows CardSpace authentication using - personal InforCards (also known as self-issued) and/or managed InfoCards, but there are several implications to consider before making a decision:

Personal Cards can be created by anybody with an Identity enabled Web browser. If the Web application is in a public site, where everyone is allowed to login then it should support personal cards. For example, Yahoo and Google, allow anyone to register without limiting it to a group of trusted users. A similar policy can be enforced using InfoCard Technology if the login supports personal cards.

If the Web application should be limited to a set of trusted users, with a set of certified claims, then managed InfoCard is the way to go. An example would be a bank account balance inquiry service that only allows account holders to login. Another example scenario is an enterprise wide intranet login. In this situation only staff should be able to login and an Identity Provider must be always present. Identity Provider (IdP) is a third party service that provides trust brokerage. WSO2 Identity Solution provides a configurable, easily manageable Identity Provider that can connect to standard set of enterprise user stores. It can be configured as a commercial IdP or an enterprise IdP - much more like a ticketing service in Keberos. If your Web application is in a public site with a set of users with tokens then you have to register you site with a commercial IdP.

As mentioned above InfoCard login will work only in the SSL transport protocol. Therefore your Web application must have a X509 certificate. For testing purpose you can create a self signed certificate using the Java key tool.

You can also support both managed and personal InfoCard authentication.

Different parameters must be present in different modes. The following table illustrates which parameters must be present in different modes:

Parameters	Required for Managed Card Authentication	Required for Info Card Authentication	Usage
Keystore, StorePass, KeyAlias, KeyPass, StoreType	Yes	Yes	Details about the private key store
TrustedIdP.KeyStore, TrustedIdP.StorePass, TrustedIdP.StoreType	Yes	No	This keystore must contain all the certificates of trusted IdPs
IssuerPolicy	Yes	Yes	Indicates InfoCard type - "Self", "Managed", "SelfAndManaged"
TokenValidationPolicy, WhiteList, BlackList	Yes	No	SAML tokens will be signature validated and then checked against BlackList OR WhiteList.
MultiValueClaimsPolicy	Optional	Optional	Optional

Implementing Self Issued Information Card Login

Let me provide some background information that will help you make decisions when implementing self issued information card authentication.

• What is required by your application users?

Your Web application users are required to install an identity enabled Web browser. Users component that enables InfoCards in Web browser is called the Identity Selector. IE7 has an in-built Identity Selector. When they click on InfoCard login logo, Identity Selector will guide them to create a self issued card.

• Add Identity provider servlet filter to your application

As per the instructions given in "Java Servlet Filter Developer Guide", add Relying party servlet filter to you Web application. Follow steps from 1 to 4. If you built the samples provided all jar dependencies will be found in the lib directory of the war file. Since you are enabling self issued information cards, only specify the few parameters in the web.xml as mentioned in the above table. Value of the "IssuerPolicy" must be "Self" since you are using self issued login. After the request passes through the RelyingPartyFilter all the information you need will be in the HTTP header, use it as described in the above section.

• Going an extra mile - Creating accounts for users

Naturally we must have a unique identifier per user when creating accounts. CardSpace defines a site specific unique identifier associated with the user called PPID (Private Personal Identifier). When user creates a personal card, a PPID is automatically generated and associated with the card . The PPID will exist throughout the card lifetime. Therefore PPID can be used as the "username" of the user. PPID is sent as a user claim in the token issued for the personal card.

Web application can request a PPID to be included in the token in the login page as given in the second step of the "Java Servlet Filter Developer Guide".

If the user logs into the Web application using a new computer, or if he looses the card, he can face a problem because he no longer has the PPID.

There are several workarounds to the problem,

• Ask the user backup cards - User has to exports/import options to import cards to the new machine. Drawback is, if user looses a card, then, he has to create a new account all over again.
• Or allow user to type PPID as the user name, if he looses the card. Drawback in that situation is that he must type some meaningless text as password
• When creating accounts user create it with a user name/password pair and allow him to associate several personal cards to it. The above drawbacks are not present in this case, but still user name/password account creation must be provided in your Web site. So when a user sings up for the first time, he needs to give a user name/password. It is only then that he can associate personal cards that he can use to login. So if the user wants, he can maintain different personal cards in different computers to logging into the same account. Sample application Card Registration [2] demonstrates this functionality.

Implementing Managed Card Logins

You have to find solutions to several practical problems when implementing managed information card authentication.

• What is required by your application users?

Users have to obtain a managed InfoCard from a trusted IdP and install it in their Identity Selector. You have to provide users details on where to find the IdP.

• Where is a trusted IdP?

You can host the IdP shipped with WSO2 Identity Solution, assign it as the trusted IdP, and configure it to trust your site and users. Alternatively, you can register your Web site at one of the public IdPs. You have to inform users where to get a managed InfoCard from the IdP in the login page.

• Add Identity provider servlet filter to your applcation

As per the documentation, "Java Servlet Filter Developer Guide", add RelyingPartyServlet filter to you Web application following step 1 to 4. If you built the samples all  jar dependencies can be found in the lib directory of the war file. Since you are enabling managed information cards, you need to specify in the web.xml more parameters than in the case of self issued InfoCard. Please refer to the table above for details on this. Confirm that you have correctly added the certificates of trusted IdPs to the Trusted IDP key store. Otherwise RelyingPartyFilter will not be able to decrypt the SAML token.

You can read user paramters from the HTTP request as given in section 1.

• Going the Extra Mile - Creating Accounts for Users

When creating accounts for users we need to figure out which data to be used as the user name or unique identifier? Managed cards login has the range of options to obtain a unique identifier. Any unique claim that can be provided by IdP can be used as user name in managed card situation.

• The site specific identifier - PPID, which defined in the Windows CardSpace specification can be used as the user name. IdPs can generate the PPID.
• The Email Claim defined by Widows Cardspace can be used.
• A custom claim can be used as a user name. For example, DN of a company LDAP can be used as the person's user name. WSO2 IdP can provide these information as it claims in the token.

On the Web application's login page you can indicate the required claims as follows. It is how you specify a custom claim with a custom IdP.

<form name="frm" id="frm" method="post" action="InfoCardLogin.action">  
		<input type="hidden" name="InfoCardSignin" value="Log in" /><br/>
		<OBJECT type="application/x-informationCard" name="xmlToken">
			<PARAM  Name="tokenType"
					Value="urn:oasis:names:tc:SAML:1.0:assertion">
			<PARAM  Name="requiredClaims"
					Value="http://custom.claim.wso2.org/ws/weird-claim">
			<PARAM Name="issuer" value="http://wso2.org/sts">
		</OBJECT>
  </form>

Summary

You can add CardSpace authentication to J2EE web application using RelyingPartyFilter provided by WSO2 Identity Solution. It must be configured giving values in the web.xml. We also discussed several important design aspects when implementing InfoCard logins.

Author

Dimuthu Leelarathne, Senior Software Engineer, dimuthul@wso2.com