Identity assertion authentication method
When using the identity assertion (IDAssertion) authentication method, the security token generated is a <wsse:UsernameToken> element that contains a <wsse:Username> element.
On the request sender side, a callback handler is invoked to generate the security token. On the request receiver side, the security token is validated.
These two operations, token generation and token validation operations, are described in the following sections.
The request receiver retrieves the IDAssertion security token from the SOAP message and validates it using a JAAS login module. With identity assertion, special processing is required to establish trust before asserting the identity as the established identity of the running thread. This special processing is defined by the <IDAssertion> element in the deployment descriptor file, ibm-webservices-ext.xmi.
If all the validation checks are successful, the asserted identity is set as the identity of the running thread. If the validation fails, the request is rejected with a SOAP fault exception.
The JAAS login configuration is specified in the<LoginMapping> element of the bindings file. Default bindings are specified in the ws-security.xml file.
However, you can override these bindings using the application specific ibm-webservices-bnd.xmi file.
The configuration information consists of CallbackHandlerFactory and a ConfigName.
- CallbackHandlerFactory specifies the name of a class that is used for creating the JAAS CallbackHandler object. WAS provides the com.ibm.wsspi.wssecurity.auth.callback.WSCallbackHandlerFactoryImpl CallbackHandlerFactory implementation.
- ConfigName specifies a JAAS configuration name entry.
WAS searches the security.xml file for a matching configuration name entry. If a match is not found it searches the wsjaas.conf file. WAS provides the system.wssecurity.IDAssertion default configuration entry, which is suitable for the identity assertion authentication method.
The <IDAssertion> element in the ibm-webservices-ext.xmi deployment descriptor file specifies the special processing required when using the identity assertion authentication method. The <IDAssertion> element is composed of two sub-elements: <IDType> and <TrustMode>.
The <IDType> element specifies the method for asserting the identity. The supported values for asserting the identity are:
- Username
- Distinguished name (DN)
- X.509 certificate
When <IDType> is username, a username token (for example, Bob) is provided. This user name is mapped to a user in the user registry and is the asserted identity after successful trust validation. When the <IDType> value is DN, a user name token containing a distinguished name is provided, for example...
cn=Bob Smith, o=ibm, c=usThis DN is mapped to a user in the user registry and this user is the asserted identity after successful trust validation. When the <IDType> is X509Certificate, a binary security token containing an X509 certificate is provided and the SubjectDN value from the certificate (for example, cn=Bob Smith, o=ibm, c=us) is extracted. This SubjectDN value is mapped to a user in the user registry and this user is the asserted identity after successful trust validation.
The <TrustMode> element specifies how the trust authority, or asserting authority, provides trust information. The supported values are:
- Signature
- BasicAuth
- No value specified
When the <TrustMode> value is Signature the signature is validated. Then, the signer (for example, cn=IBM Authority, o=ibm, c=us) is mapped to an identity in the user registry (for example, IBMAuthority). To ensure that the asserting authority is trusted, the mapped identity (for example, IBMAuthority) is validated against a list of trusted identities. When the <TrustMode> element is BasicAuth, there is a user name token with a user name and password, which is the user name and password of the asserting authority.
The user name and password are validated. If they are successfully validated, that user name (for example, IBMAuthority) is validated against a list of trusted identities. If a value is not specified for <TrustMode>, trust is presumed and additional trust validation is not performed. This type of identity assertion is called presumed trust mode. Use the presumed trust mode only in an environment where the trust is established using some other mechanism.
If all the validations described previously succeed, the asserted identity (for example, Bob) is set as the identity of the running thread. If any of the validations fail, the request is rejected with a SOAP fault exception.
There is an important distinction between V5.x and V6.0.x applications. The information in this article supports Version 5.x applications only that are used with WAS Version 6.0.x and later. The information does not apply to V6.0.x applications.
Related concepts
Identity assertion in a SOAP message
Related tasks
Configure the client for identity assertion: specifying the method
Configure the client for identity assertion: collecting the authentication method