org.picketlink.identity.federation.core.wstrust.handlers

Class STSSecurityHandler

java.lang.Object

org.picketlink.identity.federation.core.wstrust.handlers.STSSecurityHandler

All Implemented Interfaces:

Handler<SOAPMessageContext>, SOAPHandler<SOAPMessageContext>

Direct Known Subclasses:

STSSaml20Handler

public abstract class STSSecurityHandler
extends Object
implements SOAPHandler<SOAPMessageContext>

STSSecurityHandler is a server-side JAX-WS SOAP Protocol handler that will extract a Security Token from the SOAP Security Header and validate the token with the configured Security Token Service (STS).

This class is abstract to simpify is usage as the intention is for a handler to be specified in a server side handler chain. Here different Security Header specifications and security token specifications can be specified using class names instead of using properties which would force users to finding and setting the correct namespaces. Hopefully this will be easier and less error prone.

Concrete implementations

Subclasses a required to implement two methods:

• getSecurityElementQName() This should return the qualified name of the security header. This lets us support different versions.
• getTokenElementQName() This should return the qualified name of the security token element that should exist in the security header. This lets us support different tokens that can be validated with the configured STS.

Configuration

handlerchain.xml example:

 
 <?xml version="1.0" encoding="UTF-8"?>
 <jws:handler-config xmlns:jws="http://java.sun.com/xml/ns/javaee">
   <jws:handler-chains>
     <jws:handler-chain>
       <jws:handler>
         <jws:handler-class>org.picketlink.identity.federation.core.wstrust.handlers.STSSaml20Handler</jws:handler-class>
       </jws:handler>
     </jws:handler-chain>
   </jws:handler-chains>
 </jws:handler-config>
 
 

This class uses STSClient to interact with an STS. By default the configuration properties are set in a file named STSClientConfig.DEFAULT_CONFIG_FILE. This can be overridden by specifying environment entries in a deployment descriptor. For example in web.xml:

 
 <env-entry>
   <env-entry-name>STSClientConfig</env-entry-name>
   <env-entry-type>java.lang.String</env-entry-type>
   <env-entry-value>/sts-client.properties</env-entry-value>
 </env-entry>
 
 

Username and password for the STS can be configured as shown above in the sts-client.properties file. But it may also be specified by a handler earlier in the handlerchain. Such a handler is expected to extract the username and password for the desired location and put these values into the SOAPMessageContext using:
USERNAME_MSG_CONTEXT_PROPERTY
PASSWORD_MSG_CONTEXT_PROPERTY
These will then be used when contacting the STS, overriding any such values that were parsed from the configuration file.

Author:

Daniel Bevenius

Field Summary

Fields

Modifier and Type	Field and Description
protected static PicketLinkLogger	logger
static String	PASSWORD_MSG_CONTEXT_PROPERTY Constant that can be used by handlers to set the password in the SOAPMessageContext.
static String	USERNAME_MSG_CONTEXT_PROPERTY Constant that can be used by handlers to set the username in the SOAPMessageContext.

Constructor Summary

Constructors

Constructor and Description
STSSecurityHandler()

Method Summary

Modifier and Type	Method and Description
void	close(MessageContext messageContext) Called at the conclusion of a message exchange pattern just prior to the JAX-WS runtime disptaching a message, fault or exception.
Set<QName>	getHeaders() Gets the header blocks that can be processed by this Handler instance.
abstract QName	getSecurityElementQName() Subclasses can return the QName of the Security header element in usage.
abstract QName	getTokenElementQName() Subclasses can return the QName of the Security Element that should be used as the token for validation.
boolean	handleFault(SOAPMessageContext messageContext) The handleFault method is invoked for fault message processing.
boolean	handleMessage(SOAPMessageContext messageContext) Will process in-bound messages and extract a security token from the SOAP Header.
void	parseSTSConfig() Post construct will be called when the handler is deployed.
void	setConfigFile(String configFile) This setter enables the injection of the jboss-sts-client.properties file path.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

logger

protected static final PicketLinkLogger logger

USERNAME_MSG_CONTEXT_PROPERTY

public static final String USERNAME_MSG_CONTEXT_PROPERTY

Constant that can be used by handlers to set the username in the SOAPMessageContext.

See Also:

Constant Field Values

PASSWORD_MSG_CONTEXT_PROPERTY

public static final String PASSWORD_MSG_CONTEXT_PROPERTY

Constant that can be used by handlers to set the password in the SOAPMessageContext.

See Also:

Constant Field Values

Constructor Detail

STSSecurityHandler

public STSSecurityHandler()

Method Detail

getSecurityElementQName

public abstract QName getSecurityElementQName()

Subclasses can return the QName of the Security header element in usage.

Returns:

QName

getTokenElementQName

public abstract QName getTokenElementQName()

Subclasses can return the QName of the Security Element that should be used as the token for validation.

Returns:

QName

parseSTSConfig

@PostConstruct
public void parseSTSConfig()

Post construct will be called when the handler is deployed.

Throws:

WebServiceException

handleMessage

public boolean handleMessage(SOAPMessageContext messageContext)

Will process in-bound messages and extract a security token from the SOAP Header. This token will then be validated using by calling the STS..

Specified by:

handleMessage in interface Handler<SOAPMessageContext>

Parameters:

messageContext - The messageContext.

Returns:

true If the security token was correctly validated or if this call was an outbound message.

Throws:

WebServiceException - If the security token could not be validated.

getHeaders

public Set<QName> getHeaders()

Description copied from interface: SOAPHandler

Gets the header blocks that can be processed by this Handler instance.

Specified by:

getHeaders in interface SOAPHandler<SOAPMessageContext>

Returns:

Set of QNames of header blocks processed by this handler instance. QName is the qualified name of the outermost element of the Header block.

handleFault

public boolean handleFault(SOAPMessageContext messageContext)

Description copied from interface: Handler

The handleFault method is invoked for fault message processing. Refer to the description of the handler framework in the JAX-WS specification for full details.

Specified by:

handleFault in interface Handler<SOAPMessageContext>

Parameters:

messageContext - the message context

Returns:

An indication of whether handler fault processing should continue for the current message

• Return true to continue processing.
• Return false to block processing.

close

public void close(MessageContext messageContext)

Description copied from interface: Handler

Called at the conclusion of a message exchange pattern just prior to the JAX-WS runtime disptaching a message, fault or exception. Refer to the description of the handler framework in the JAX-WS specification for full details.

Specified by:

close in interface Handler<SOAPMessageContext>

Parameters:

messageContext - the message context

setConfigFile

public void setConfigFile(String configFile)

This setter enables the injection of the jboss-sts-client.properties file path.

Parameters:

configFile -