WSO2 Identity Solution, v1.5 : Java Servlet Filter Developer Guide : Part II

Introduction

This servlet filter org.wso2.solutions.identity.relyingparty.servletfilter.RelyingPartyFilter can be used with a servlet based web application to provide information card and OpenID login to that application.The Part II of this guide explains how you can add OpenID with Simple Registration and OpenID Information Card support to a relying party web application. The developer should follow the steps described below in intgrating this servlet filter:

Adding OpenID Information Card Support

Step 1 : Add the servlet filter to your application

Include the following entry in the web.xml file of the application:


    <filter>
        <filter-name>TokenValidator</filter-name>
        <filter-class>org.wso2.solutions.identity.relyingparty.servletfilter.RelyingPartyFilter</filter-class>
        	<init-param>
	    	    <param-name> ................ </param-name>
		    <param-value> ............... </param-value>
  		</init-param>
		<init-param>
			......................
  		</init-param>
			......................
			......................
    </filter>
	
    <filter-mapping>
        <filter-name>TokenValidator</filter-name>
        <url-pattern>/*</url-pattern>
    </filter-mapping>

Add the following as init-params to the web.xml

ParameterName Required Description
Keystore Yes Relative path to the keystore holding private key
StorePass Yes Password to the keystore holding private key
KeyAlias Yes Private key alias
KeyPass Yes Private key pass
StoreType Yes Store type of the keystore holding private key - e.g. JDK
TrustedIdP.KeyStore Relative path to the trusted keystore
TrustedIdP.StorePass If TokenValidationPolicy is NOT Promiscuous Trust store password
TrustedIdP.StoreType If TokenValidationPolicy is NOT Promiscuous Trust store type
MultiValueClaimsPolicy No - default applied Must be either MultiValueClaimsAllowed or MultiValueClaimsNotAllowed. Default is MultiValueClaimsNotAllowed
IssuerPolicy No - default applied Must be one of SelfAndManaged, Self, Managed. Default is self and managed
TokenValidationPolicy No - default applied Must be one of Promiscuous, WhiteList, BlackList, CertValidate. Default is CertValidate. Please read more about this below.
WhiteList Yes, if TokenValidationPolicy is WhiteList This is required to indicate the list of allowed DNs. If not specified in WhiteList mode none of the users can login
BlackList Yes, if TokenValidationPolicy is BlackList This is required to indicate the list of rejected DNs. If not specified in BlackList mode all users who pass CertValidity can login

TokenValidationPolicy

There are 4 modes of token validations.

Step 2 : Add the OpenID Information Card login page

The user loging page must contain a form with an object tag as shown below:


   <form name="frm" id="frm" method="post" action="openidinfocardloggedin.jsp">  
		    <input type="hidden" name="InfoCardSignin" value="Log in" />

	       <OBJECT type="application/x-informationCard" name="xmlToken">
                    <PARAM Name="tokenType" Value="http://specs.openid.net/auth/2.0">
                    <PARAM Name="requiredClaims" Value="http://schema.openid.net/2007/05/claims/identifier">
                    <PARAM name="optionalClaims" Value="http://axschema.org/contact/email http://axschema.org/namePerson/first 
                                                        http://axschema.org/namePerson/last http://axschema.org/contact/phone/default 
                                                        http://axschema.org/contact/postalAddress/home http://axschema.org/contact/city/home 
                                                        http://axschema.org/contact/postalCode/home 
                                                        http://axschema.org/contact/country/home 
                                                        http://axschema.org/contact/web/blog">
               </OBJECT>               

  </form>

The object tag here is the standard information card object as defined here .

It is important that you include the hidden field called "InfoCardSignin" with the value "Log in". The filter will process the HTTP POST request to extract the token sent when this request parameter is available.

Step 3 : Add the following jars to your classpath

Step 4 : Obtain the information in the verified token and process

The results of token processing will be available as attributes in the ServletRequest object.

To indicate whether token verification was successful or not there will be an attribute by the name "org.wso2.solutions.identity.rp.State". On successful verification value of this attribute will be "success". Otherwise it will be "failure".

The ServletRequest will also contain a set of attributes by the names of the claims (the part of claim URI after the final "/")

with their values.

These values can be used by the developer to initiate a user session in a web application.

Adding OpenID Support with Simple Registration

Step 1 : Add the servlet filter to your application

Include the following entry in the web.xml file of the application:


    <filter>
        <filter-name>TokenValidator</filter-name>
        <filter-class>org.wso2.solutions.identity.relyingparty.servletfilter.RelyingPartyFilter</filter-class>
        	<init-param>
	    	    <param-name> ................ </param-name>
		    <param-value> ............... </param-value>
  		</init-param>
		<init-param>
			......................
  		</init-param>
			......................
			......................
    </filter>
	
    <filter-mapping>
        <filter-name>TokenValidator</filter-name>
        <url-pattern>/*</url-pattern>
    </filter-mapping>

Step 2 : Add signin page

<form name="openidsignin" id="openidsignin" method="post" action="openidsubmit.jsp">
    Enter Your OpenID Url:<input type="text" name="openIdUrl"/>
    <input type="submit" name="submit" value="Login" />
</form>

As per above scenario openidsubmit.jsp page will accept the OpenID url and will do authentication using Identity Solution's relying parting components.

Step 3 : Create OpenID authentication request[openidsubmit.jsp]

// imports
<%@page import="org.wso2.solutions.identity.openid.relyingparty.OpenIDAuthenticationRequest"%>
<%@page import="org.wso2.solutions.identity.openid.relyingparty.OpenIDConsumer"%>
<%@page import="org.wso2.solutions.identity.relyingparty.openid.OpenIDRequestType"%>
<%@page import="org.wso2.solutions.identity.relyingparty.RelyingPartyException"%>
<%@page import="org.wso2.solutions.identity.IdentityConstants"%>

<%

try
{
   OpenIDAuthenticationRequest openIDAuthRequest = null;

   openIDAuthRequest = new OpenIDAuthenticationRequest(request,response);

   openIDAuthRequest.setOpenIDUrl((String)request.getParameter("openIdUrl"));

   // you need to set an absolute url as the return url.
   // once the user authenticated successfully or failed at the OpenID
   // Provider, the browser will be redirected to this url

   openIDAuthRequest.setReturnUrl("http://myapp.com/openidcallback.jsp");

   // Use Simple Attribute Registration 1.1
   openIDAuthRequest.addRequestType(OpenIDRequestType.SIMPLE_REGISTRATION);

   // Set the required claims - I need these claims from the OpenID
   // Provider.
   openIDAuthRequest.addRequiredClaims(IdentityConstants.OpenId.SimpleRegAttributes.NICK_NAME);
   openIDAuthRequest.addRequiredClaims(IdentityConstants.OpenId.SimpleRegAttributes.FULL_NAME);
   openIDAuthRequest.addRequiredClaims(IdentityConstants.OpenId.SimpleRegAttributes.EMAIL);
   openIDAuthRequest.addRequiredClaims(IdentityConstants.OpenId.SimpleRegAttributes.DOB);
   openIDAuthRequest.addRequiredClaims(IdentityConstants.OpenId.SimpleRegAttributes.GENDER);
   openIDAuthRequest.addRequiredClaims(IdentityConstants.OpenId.SimpleRegAttributes.POSTAL_CODE);
   openIDAuthRequest.addRequiredClaims(IdentityConstants.OpenId.SimpleRegAttributes.COUNTRY);
   openIDAuthRequest.addRequiredClaims(IdentityConstants.OpenId.SimpleRegAttributes.LANGUAGE);
   openIDAuthRequest.addRequiredClaims(IdentityConstants.OpenId.SimpleRegAttributes.TIMEZONE);

   // Performs authentication : this will redirect you to OpenID Provider for authentication
   OpenIDConsumer.getInstance().doOpenIDAuthentication(openIDAuthRequest);

}
catch(RelyingPartyException e)
{
   // handle exceptions
   out.println(e.getMessage());
}

%> 

Step 4 : Add OpenID callback page[openidcallback.jsp]

After being authenticated at the OpenID Provider, user will be redirected to this page.

// imports
<%@page import="org.wso2.solutions.identity.IdentityConstants"%>
<%@page import="org.wso2.solutions.identity.relyingparty.TokenVerifierConstants"%>
<%@page import="org.wso2.solutions.identity.openid.relyingparty.OpenIDConsumer "%>

<%

String nickname = null;
String auth = (String)request.getAttribute(TokenVerifierConstants.SERVLET_ATTR_STATE);

 if(auth != null && TokenVerifierConstants.STATE_SUCCESS.equals(auth)) {

    //user authenticated successfully at his OpenID Provider
    //let me get his nick name - which I requested.

    if (request.getAttribute(IdentityConstants.OpenId.SimpleRegAttributes.NICK_NAME) != null)
    {
           nickname = request.getAttribute(IdentityConstants.OpenId.SimpleRegAttributes.NICK_NAME);

    }else {

       // there can be OpenID Providers, who do not maintain a list of user
       // attributes. In such case you won't receive any value here -
       // though you requested.
    }
 }
 else
 {
  //user authentication failed at his OpenID Provider
 }
%> 

Step 5 : Add the following jars to your classpath