WSO2 SOA Enablement Server's WS-Security provides three built-in types of security tokens: X509 binary security token, Username token, and SymmetricKey binary security token. These are sufficient for most use cases. If a custom security token must be used, WSO2 SOA Enablement Server provides a framework for implementing them.
Tokens are primarily distinguished by their unique localName. Binary security tokens are further distinguished by their unique valueType. For more details, please see the WS-Security specification.
Implementation of a custom security token consists of implementing token handler and the token itself.
Security token handler is the interface between the WS-Security and custom security token implementations. It takes care of the instantiation of custom security token from given configurations or DOM representation.
The security token implementation handles the DOM representation of the security token instance and represented keys. During the processing of the security token, an instance of org.systinet.wasp.security.ws.SecurityContext is available. It provides the processing context (namespaces, message configuration, PStore and SOAP message).
The processing of security tokens is described in org.systinet.wasp.security.ws.SecurityTokenHandlerSPI.
Follow these steps to implement the custom security token:
Design the processing of the token (for example, if it will always be an external security token, what resources it will use, what keys it will provide, etc.)
Design XML schema of security token. Custom binary security tokens must follow the BinarySecurityToken schema as defined by the OASIS WS-Security specification.
Choose namespace, localName and/or valueType. Note that the current WS-Security specification allows the URI to define the value type, for example, http://company.com/smart-token-profile-1.0#Smart.
Create a class that implements the following methods from the abstract class org.systinet.wasp.security.ws.SecurityTokenHandlerSPI :
createFromConf(SecurityTokenConf tokenConf, SecurityContext securityContext, boolean isExternal) Returns instance of security token created from given configuration in SecurityTokenConf. Initialization and/or validation of security can be implemented here or in the implementation of Security Token.
createFromXML(Element tokenElement, SecurityContext securityContext) Returns instance of security token created from a given DOM element. Initialization and/or validation of security can be implemented here or in the implementation of Security Token.
getLocalValueType() Returns an identifier that is used to recognize the right handler implementation for processing the token.
For a URI that contains a fragment identifier (for example, http://company.com/smart-token-profile-1.0#Smart), getLocalValueType() returns the fragment (such as Smart in the example). For a URI without a fragment identifier (for example, http://company.com/token/Smart), getLocalValueType() returns the whole URI (such as http://company.com/token/Smart in the example). The custom binary security token should override this method.
getLocalElementName() Returns the local part of token element that is used to recognize the correct handler implementation for processing the token. Custom security tokens other than binary tokens should override this method.
Create a class that implements the following methods from the abstract class org.systinet.wasp.security.ws.SecurityTokenSPI:
A constructor that passes the SecurityContext and the isExternal flag to the SecurityTokenSPI constructor.
A constructor that passes the Element, the SecurityContext and the isExternal flag to the SecurityTokenSPI constructor.
getType() Returns the same value as the handler's getLocalValueType.
getValueType() Returns the full valueType (if supported by the token), such as http://company.com/smart-token-profile-1.0#Smart from step 3.
getBaseLocalName() Returns the local part of token element. Should match the return value of handler's getLocalElementName() method. Custom security tokens other than binary tokens should override this method.
getBaseNamespace() Returns the token element namespace. Custom security tokens other than binary tokens should override this method.
getReceivedConf() Returns the instance of org.systinet.wasp.security.ws.conf.SecurityTokenConf of the received security token.
doFinal(mode) Performs the following on the given mode (/RECEIVE):
GENERATE - cleanup of sent security tokens
RECEIVE - process received DOM and initialize Security Token
getKeyIdentifier() Returns the key idenfifier value, if supported by the token.
getEncryptingKey() Returns encryption key if it is supported/provided by the token. Otherwise it should return null.
getDecryptingKey() Returns decryption key if it is supported/provided by the Security Token. Otherwise it should return null.
getSigningKey() Returns signing key if it is supported/provided by the Security Token. Otherwise it should return null.
getAuthenticatingKey() Returns authenticating key if it is supported/provided by the Security Token. Otherwise it should return null.
Register SecurityTokenHandler implementation In runtime this is done through SecurityTokenHandlerSPI.addSecurityTokenHandler(...) . In persistent deployment, create a server and/or client package with a deployment descriptor registering the custom token handler. Copy the server package to WASP_HOME/app and/or include the client package in the client application classpath.
Example 9. Deployment Descriptor For Custom Token Handler Package
<?xml version="1.0" encoding="UTF-8"?>
<package name="smart_security_token"
version="1.0"
library="true"
client-package="false"
targetNamespace="http://company.com/smart_security_token"
xmlns="http://systinet.com/wasp/package/1.3"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:security_providers="http://systinet.com/wasp/app/security_providers"
xsi:schemaLocation="http://systinet.com/wasp/package/1.3
http://systinet.com/wasp/package/1.3">
<dependency ref="security_providers:security_providers" version="6.5.4"/>
<securityProviderPreferences name="SmartSecurityToken"
xmlns="http://systinet.com/wasp/package/extension">
<securityTokenHandler>com.company.SmartTokenHandler</securityTokenHandler>
</securityProviderPreferences>
</package>