Leveraging Trust Association Interceptors (TAIs)

Advanced Topic Use of TAI is considered an advanced topic and should not be required for most applications. The target audience for TAI support for Project Zero is for current users of TAI who want to leverage existing TAI implementations. If you want to extend or implement your own security handlers, see the Extending security section that provides information about the the preferred method for extending security in Project Zero.

Project Zero provides an extensible framework for single sign on (SSO) with external authentication services such as reverse proxies through trust associations. When trust association is enabled, Project Zero is not required to authenticate a user if a request arrives from a trusted source that has already performed authentication.

The following sections provide information regarding the conversion of existing TAI implementations designed for the J2EE platform (such as WebSphere Application Server) to Project Zero.

For a good overview of one of the more common TAI implementations, see the Tivoli Access Manager Trust Association Interceptor developerWorks article.

Working with existing TAIs in Project Zero

Most security providers set security context in http request headers and TAIs retrieve that information from the HttpServletRequest headers. There are two options for calling TAI implementations from Project Zero.

• Rewriting the existing TAI implementation (preferred) to leverage the Global context instead of the HttpServletRequest and HttpServletResponse objects that are more typically used. While this could be time consuming, it is the the suggested method for implementing TAI implementations for Project Zero. For an exhaustive list of information that can be retrieved from the global context see the Global context reference.

• Creating a a bridge between what is in the global context and the HttpServletRequest and HttpServletResponse classes required by TAI. This is an option if there are many TAI implementations already in existence. Because Project Zero is based on J2SE and not J2EE, this is not included as part of Project Zero but this could be done by a TAI implementor.

Project Zero security provides an extension point for registering a TAIExtensionHandler object as an event handler. The TAI extension is called by the security component when the onSecure event runs and TAI is configured for that resource.

Implementation of TAI extension handler

The TAI extension handler must be implemented based on following rules:

• All must be implemented in onTAIValidateRequest method.
• An appropriate http status code must be set to GlobalContext with key /request/status.
• An authenticated user must be set to GlobalContext as java.util.Set<java.security.Principal> with key /event/taiValidatedsetOfPrincipals. If the handler can obtain group names for an authenticated user, they should be included in the set of principals.
• Security context must be converted between GlobalContext and a context container that a TAI implementation uses including javax.servlet.http.HttpServletRequest/Response.

The following example shows pseudo code for an example SecurityContextHandler :

public class TestSecurityContextHandler {
        // wrapper class for the GlobalContext related request keys
        private class CustomHttpServletRequest implements HttpServletRequest{
                
                public CustomHttpServletRequest(){
                }
                
                public String getHeader (String headerValue){
                        return GlobalContext.zget (Request.Headers.in +"/" +headerValue);
                }
        }
        // wrapper class for the GlobalContext related response keys
        private class CustomHttpServletResponse implements HttpServletResponse{
                public CustomHttpServletResponse(){
                }
                
                public void setStatus(int status){
                        return GlobalContext.zput(Request.status,status);
                }
        }
        
        //Event Handler Method
        public void onTAIValidateRequest() {
                
                //Get security contexts from GlobalContext 
                //   and put them to an appropriate context container like javax.servlet.http.HttpRequestContext 
                HttpServletRequest httpServletRequestImpl = new CustomHttpServletRequest();
                HttpServletResponse httpServletResponseImpl = new CustomHttpServletResponse();
                String authHeaderVal = httpServletRequestImpl.getHeader(....,....);
                
                
                //Validate the request with 3rd party Security Provider
                boolean validateResult = taiImpl.validateRequestWith3rdPartySecurityProvider( httpServletRequestImpl , httpServletResponseImpl );
                
                if(validateResult){
                        //Validation succeeds
                        //Add a user principal to a set of principals
                        Set<Principal> principals = new HashSet<Principals>();
                        principals.add(userPrincipal);
                        //If group principals can be obtain, set them to the set of principals
                        if(groupPrincipals != null){		 
                                principals.addAll(groupPrincipals);
                        }
                        //Set the set of principals to GlobalContext
                        GlobalContext.zput("/event/taiValidatedSetOfPrincipals", principals);
                        //Http status "200" should be set by application.
                        //So , when validation succeeds, no status code is set to GlobalContext
                }else{
                        //As validation result, set 403 to GlobalContext
                        GlobalContext.zput(Request.status, HttpURLConnection.HTTP_FORBIDDEN);
                }	  
        }
}

Authorization

Only Project Zero authorization is supported. Project Zero security authorizes the request using the user name and group names in GlobalContext. If there are no group names in GlobalContext, Project Zero security tries to obtain group names for the user from the user service registry. The most common user registry is LDAP because it is easily accessible for both trusted servers and Project Zero.

Configuring zero.config

The following example shows how zero.config is used for third party token validation:

/config/handlers += [{
	"events" : "TAIValidateRequest",
	"handler" : "acme.TestSecurityContextHandler.class"
}]

@include "security/rule.config"{
	"conditions":"/request/path =~ /secure(/.*)? ",
	"authType" : "TAI",
	"users" : ["user1"],
	"groups" : ["CUSTOMERS"],
	"roles" : ["ADMIN"]
}

# override the default registry type from file to ldap
/config/security/userservice/registryType="ldap"

/config/security/userservice/ldap += {
	"jndiProviderUrl":"ldap://localhost:10390/",
	"jndiSecurityPrincipal":"uid=admin,ou=system",
	"jndiSecurityCredentials":"secret",
	"jndiInitialContextFactory":"com.sun.jndi.ldap.LdapCtxFactory",
	"ldapSearchScope":2,
	"ldapSearchTimeLimit":30000,
	"ldapUserIdRdnPattern":"uid={0}",
	"ldapUserIdBaseDn":"ou=people,o=hq,dc=yourco,dc=com",
	"ldapGroupAttributeType":"cn",
	"ldapGroupBaseDn":"o=hq,dc=yourco,dc=com",
	"ldapGroupSearchFilterPattern":"(&(uniqueMember={0}))"
}

An implementation class name of SecurityContextHandler must be specified using the /config/handlers stanza so that it can be invoked when the TAIValidateRequest event runs. The /config/security/rule.config stanza is configuration for secured URIs and authorized users, groups and roles. See the Security considerations article for more information about this stanza. The /config/security/userservice stanza is part of the user registry configuration used by authorization. See the LDAP user service article for more information about this stanza.