WAS v8.5 > Secure applications > Secure web services > Secure web services > Web Services Security concepts > Web Services Security concepts for v5.x applications

Login mappings

Login mappings, found in the ibm-webservices-bnd.xmi XML file, contains a mapping configuration that defines how the Web Services Security handler maps the token <ValueType> element contained within the security token extracted from the message header, to the corresponding authentication method. <ValueType> is contained within the security token extracted from a SOAP message header.

There is an important distinction between v5.x and v6 and later applications. The information in this article supports v5.x applications only used with WebSphere Application Server v6.0.x and later. The information does not apply to v6 and later applications.

The sender-side Web Services Security handler generates and attaches security tokens based on the <AuthMethods> element 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 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 we 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. WAS provides the following set of CallbackHandler interface implementations we 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.

If we 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, we 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. We 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 LTPA tokens from the run as JAAS Subject (invocation Subject) of the current WAS 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

We 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:

  1. 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.
  2. 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.

  3. 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.
  4. The Web Services Security run time invokes the newCallbackHandler() method to obtain the javax.security.auth.CallbackHandler object, which generates the required security token.

  5. 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.

    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:

    • Server-level ws-security.xml file

    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.

  6. The client reads the default binding information in the ${install_dir}/properties/ws-security.xml file.
  7. The server runtime component loads the following files if they exist:

    • Server-level ws-security.xml file

    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 dmgr console. We can specify the binding information during application deployment using the dmgr 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.


Related concepts:

LTPA
Request sender
Request receiver


Related


Secure web services for v5.x applications using basic authentication
Secure web services for v5.x applications using identity assertion authentication
Secure web services for version 5.x applications using signature authentication
Secure web services for version 5.x applications using a pluggable token


Reference:

Login mappings page
Login mapping configuration settings
Default configuration for WAS


+

Search Tips   |   Advanced Search