Web services authentication method overview

The Web Services Security implementation for WebSphere Application Server - Express supports the following authentication methods:

• BasicAuth
  When WebSphere Application Server - Express is configured to use the BasicAuth authentication method, the sender attaches the LTPA token as a BinarySecurityToken from the current security context or from basic authentication data configuration in the binding file in the Simple Object Access Protocol (SOAP) message header. The Web services security message receiver authenticates the sender by validating the user name and password against the configured user registry.

• Identity assertion
  The identity assertion authentication method, different from other three authentication methods, establishes the security credential of the sender based on the trust relationship. You can use the identity assertion authentication method, for example, when an intermediary server must invoke a service from a downstream server on behalf of the client, but does not have the client authentication information. The intermediary server might establish a trust relationship with the downstream server and then assert the client identity to the same downstream server.

• Digital signature
  With the digital signature authentication method, the sender attaches a BinarySecurityToken from a X509 certificate to the Web services security message header along with a digital signature of the message body, time stamp, security token, or any combination of the three. The receiver authenticates the sender by verifying the validity of the X.509 certificate and the digital signature using the public key from the verified certificate.

• Lightweight Third-Party Authentication (LTPA)
  With the LTPA method, the sender attaches the LTPA BinarySecurityToken it previously received in the SOAP message header. The receiver authenticates the sender by validating the LTPA token and the token expiration time.

Web services security supports the following trust modes:

• BasicAuth
• Digital signature
• Presumed trust

When you use the BasicAuth and Digital signature trust modes, the intermediary server passes its own authentication information to the down stream server for authentication. The Presumed trust mode establishes a trust relationship using some external mechanism.For example, the intermediary server may pass Simple Object Access Protocol (SOAP) messages through a secure socket layers (SSL) connection with the downstream server and transport layer client certificate authentication.

The Web services security implementation for WebSphere Application Server - Express validates the trust relationship by following this procedure:

1. The downstream server first validates the authentication information of the intermediary server.
2. The downstream server verifies whether the authenticated intermediary server is authorized for identity assertion. For example, the intermediary server must be in the trust list for the downstream server.

The client identity may be represented by a name string, a distinguished name (DN), or an X.509 certificate. The client identity is attached in the Web services security message in a UsernameToken with just a user name, DN, or in a BinarySecurityToken of a certificate.

The following table summarizes the type of security token that is required for each authentication method.

Multiple authentication methods can be supported by a Web service simultaneously. The receiver-side Web services deployment descriptor can specify all the authentication methods that are supported in the ibm-webservices-ext.xmi XML file. The receiver-side Web services, as shown in the following example, is configured to accept all the authentication methods described previously:

<loginConfig xmi:id="LoginConfig_1052760331326">
  <authMethods xmi:id="AuthMethod_1052760331326" text="BasicAuth"/>
  <authMethods xmi:id="AuthMethod_1052760331327" text="IDAssertion"/>
  <authMethods xmi:id="AuthMethod_1052760331336" text="Signature"/>
  <authMethods xmi:id="AuthMethod_1052760331337" text="LTPA"/>
</loginConfig>
<idAssertion xmi:id="IDAssertion_1052760331336" idType="Username" trustMode="Signature"/>

You can define only one authentication method in the sender-side Web services deployment descriptor. A Web service client can use any one of the authentication methods that are supported by the particular Web services application. The following example illustrates an identity assertion authentication method configuration in the Web service client deployment descriptor extension, ibm-webservicesclient-ext.xmi:

<loginConfig xmi:id="LoginConfig_1051555852697">
  <authMethods xmi:id="AuthMethod_1051555852698" text="IDAssertion"/>
</loginConfig>
<idAssertion xmi:id="IDAssertion_1051555852697" idType="Username" trustMode="Signature"/>

As shown in the previous example, the client identity type is Username and the trust mode is digital signature (Signature).

Figure 1: Security token generation and validation

The sender security handler invokes the handle() method of an implementation of the javax.security.auth.callback.CallbackHandler interface. The javax.security.auth.callback.CallbackHandler interface creates the security token and passes it back to the sender security handler. The sender security handler constructs the security token based on the authentication information in the callback array and inserts the security token into the Web services security message header.

The receiver security handler compares the token type in the message header with the expected token types configured in the deployment descriptor. If none of the expected token type are found in the Web services security header of the SOAP message, the request is rejected with an SOAP fault exception. Otherwise, the token type is used to map to a Java Authentication and Authorization Service (JAAS) login configuration for validating the token. If the authentication is successful, then a JAAS Subject is created and associated with the thread of execution. Otherwise, the request is rejected with an SOAP fault exception.