Login mappings, found in the ibm-webservices-bnd.xmi Extended
Markup Language (XML) file, contains a mapping configuration. This
mapping configuration defines how the Web Services Security handler
maps the token <ValueType> element that is contained within
the security token extracted from the message header, to the corresponding
authentication method. The token <ValueType> element is contained
within the security token extracted from a SOAP message header.
Important: There is an important distinction between Version
5.x and Version 6 and later applications. The information supports
Version 5.x applications only that are used with WebSphere® Application
Server Version 6.0.x and later. The information does not apply
to Version 6 and later applications.
The sender-side Web Services Security handler generates and attaches
security tokens based on the <AuthMethods> element that is specified
in the deployment descriptor. For example, if the authentication method
is BasicAuth, the sender-side security handler
generates and attaches UsernameToken (with
both user name and password) to the SOAP message header. The Web Services
Security run time uses the Java Authentication
and Authorization Service (JAAS) javax.security.auth.callback.CallbackHandler
interface as a security provider to generate security tokens on the
client side (or when web services are acting as client).
The sender security handler invokes the handle() method
of a javax.security.auth.callback.CallbackHandler interface implementation.
This implementation creates the security token and passes the token
back to the sender security handler. The senders security handler
constructs the security token based on the authentication information
in the callback array. The security handler then inserts the security
token into the Web Services Security message header.
The
CallbackHandler interface implementation
that you use to generate the required security token is defined in
the <loginBinding> element in the
ibm-webservicesclient-bnd.xmi Web
Services Security binding file. For example,
<loginBinding xmi:id="LoginBinding_1052760331526" authMethod="BasicAuth"
callbackHandler="com.ibm.wsspi.wssecurity.auth.callback.StdinPromptCallbackHandler"/>
The <loginBinding> element associates the com.ibm.wsspi.wssecurity.auth.callback.StdinPromptCallbackHandler
interface with the BasicAuth authentication method. WebSphere Application
Server provides the following set of CallbackHandler interface implementations
you can use to create various security token types:
- com.ibm.wsspi.wssecurity.auth.callback.GUIPromptCallbackHandler
- If there is no basic authentication data defined in the login
binding information (this information is not the same as the HTTP
basic authentication information), the previous token type prompts
for user name and password through a login panel. The implementation
uses the basic authentication data defined in the login binding. Use
this CallbackHandler with the BasicAuth authentication method. Do
not use this CallbackHandler implementation on the server because
it prompts you for login binding information.
- com.ibm.wsspi.wssecurity.auth.callback.StdinPromptCallbackHandler
- If basic authentication data is not defined in the login binding
(this information is not the same as the HTTP basic authentication
information), the implementation prompts for the user name and password
using standard in (stdin). The implementation uses the basic authentication
data defined in the login binding. Use this CallbackHandler implementation
with the BasicAuth authentication method. Do not use this CallbackHandler
implementation on the server because it prompts you for login binding
information.
Restriction: If you have a multi-threaded
client and multiple threads attempt to read from standard in at the
same time, all the threads will not successfully obtain the user name
and password information. Therefore, you cannot use the com.ibm.wsspi.wssecurity.auth.callback.StdinPromptCallbackHandler
implementation with a multi-threaded client where multiple threads
might attempt to obtain data from standard in concurrently.
- com.ibm.wsspi.wssecurity.auth.callback.NonPromptCallbackHandler
- This CallbackHandler implementation does not prompt. Rather, it
uses the basic authentication data defined in the login binding (this
information is not the same as the HTTP basic authentication information).
This CallbackHandler implementation is meant for use with the BasicAuth
authentication method. You must define the basic authentication data
in the login binding information for this CallbackHandler implementation.
You can use this implementation when web services is running as a
client and needs to send basic authentication (<wsse:UsernameToken>)
to the downstream call.
- com.ibm.wsspi.wssecurity.auth.callback.LTPATokenCallbackHandler
- The CallbackHandler generates Lightweight Third Party Authentication
(LTPA) tokens from the run as JAAS Subject
(invocation Subject) of the current WebSphere Application
Server security context. However, if basic authentication data is
defined in the login binding information (not the HTTP basic authentication
information), the implementation uses the basic authentication data
and LTPA token generated. The Token Type URI and Token Type
Local Name values must be defined in the login binding information
for this CallbackHandler implementation. The token value type is used
to validate the token to the request sender and request receiver binding
configuration. The Web Services Security run time inserts the LTPA
token as a binary security token (<wsse:BinarySecurityToken>)
into the message SOAP header. The value type is mandatory. (See LTPA for more information).
Use this CallbackHandler implementation with the LTPA authentication
method.
Figure 1 shows the sender security handler in the request sender
message process.
Figure 1. Request sender SOAP message process
You can configure the receiver-side security server to support
multiple authentication methods and multiple types of security tokens.
The following steps describe the request sender SOAP message process:
- After receiving a message, the receiver Web Services Security
handler compares the token type (in the message header) with the expected
token types configured in the deployment descriptor.
- The Web Services Security handler extracts the security token
form the message header and maps the token <ValueType> element
to the corresponding authentication method. The mapping configuration
is defined in the <loginMappings> element
in the ibm-webservices-bnd.xmi XML file. For
example:
<loginMappings xmi:id="LoginMapping_1051977980074" authMethod="LTPA"
configName="WSLogin">
<callbackHandlerFactory xmi:id="CallbackHandlerFactory_1051977980081"
classname="com.ibm.wsspi.wssecurity.auth.callback.WSCallbackHandlerFactoryImpl"/>
<tokenValueType xmi:id="TokenValueType_1051977980081"
uri="http://www.ibm.com/websphere/appserver/tokentype/5.0.2" localName="LTPA"/>
</loginMappings>
The com.ibm.wsspi.wssecurity.auth.callback.CallbackHandlerFactory
interface is a factory for javax.security.auth.callback.CallbackHandler.
- The Web Services Security run time initiates the factory implementation
class and passes the authentication information from Web Services
Security header to the factory class through the set methods.
- The Web Services Security run time invokes the newCallbackHandler()
method to obtain the javax.security.auth.CallbackHandler object, which
generates the required security token.
- When the security handler receives an LTPA BinarySecurityToken,
it uses the WSLogin JAAS login configuration
and the newCallbackHandler() method to validate the security token.
If none of the expected token types are found in the SOAP message
Web Services Security header, the request is rejected with an SOAP
fault. Otherwise, the token type is used to map to a JAAS login configuration
for token validation. If authentication is successful, a JAAS Subject
is created and associated with the running thread. Otherwise, the
request is rejected with a SOAP fault.
The following table shows
the authentication methods and the JAAS login configurations.
Table 1. Authentication methods and JAAS login
configurations. The authentication methods map to the
JAAS login configuration for token validation.Authentication method |
JAAS login configuration |
BasicAuth |
WSLogin |
Signature |
system.wssecurity.Signature |
LTPA |
WSLogin |
IDAssertion |
system.wssecurity.IDAssertion |
Figure 2 shows the receiver security handler in the
request receiver message process.
Figure 2. Request receiver SOAP
message process
The default <LoginMapping>
is defined in the following files:
- Cell-level ws-security.xml and
server-level ws-security.xml files
If nothing is defined in the binding file
information, the
ws-security.xml default is used.
However, an administrator can override the default by defining a new <LoginMapping>
element in the binding file.
- The client reads the default binding information in the ${install_dir}/properties/ws-security.xml file.
- The server runtime component loads the following files if they
exist:
- Cell-level ws-security.xml file
and the server-level ws-security.xml file. The
two files are merged in the run time to form one effective set of
default binding information.
On
a base application server, the server run time component only loads
the server-level ws-security.xml file. The server-side ws-security.xml file
and the application Web Services Security binding information are
managed using the administrative console. You can specify the binding
information during application deployment using the administrative
console. The Web Services Security policy is defined in the deployment
descriptor extension (ibm-webservicesclient-ext.xmi)
and the bindings are stored in the IBM® binding
extension (ibm-webservicesclient-bnd.xmi). However,
the ${install_dir}/properties/ws-security.xml file
defines the default binding value for the client. If the binding information
is not specified in the binding file, the run time reads the binding
information from the default ${install_dir}/properties/ws-security.xml file.