000025708 - Howto: NTLM Authentication via the Runtime API

Document created by RSA Customer Support Employee on Jun 16, 2016Last modified by RSA Customer Support Employee on Apr 21, 2017
Version 2Show Document
  • View in full screen mode

Article Content

Article Number000025708
Applies ToRSA ClearTrust 5.5.x Runtime API
IssuePerform NTLM authentication using the Runtime API

The following sample code is a single Java method that, given a connected Runtime API object and a valid username, domain, and password, will authenticate the user against an authorization server that is correctly configured to perform NTLM authentication (this can be tested by using a ClearTrust agent configured for NTLM authentication; if the user can authenticate through the agent, this code will likewise return a valid token).

This code requires the ClearTrust Runtime API library (ct_runtime_api.jar or cleartrust.jar) and the jCIFs library (jcifs.jar).  In this code, base 64 encoding and decoding is handled by this open source Java class.

/* @param proxy A connected intance of RuntimeAPI to an authorization server 
 *              configured to perform NTLM authentication.
 * @param domain The NT domain in which the user will be authenticated
 * @param username The user's domain ID
 * @param password The user's password
 * @return A java.util.Map containing the mapped ClearTrust user Id and a token,
 *         for a successful authentication, or an authorization server response
 *         indicating a failure to either authenticate the user against the
 *         domain or to map the user successfully within ClearTrust.  This map
 *         is the same as that returned from the RuntimeAPI.authenticate( )
 *         method; see the Runtime API documentation for more details.

public Map doNTLMAuthentication( RuntimeAPI proxy, 
                                 String domain,
                                 String username,
                                 String password )
    // This is the initial handshake in the NTLM protocol, requiring no
    // username or password

    Type1Message type1 = new Type1Message( ) ;
    String handshake = new String( Base64.encode( type1.toByteArray( ) ) ) ;

    // The handshake is submitted to the authenticate method as part of the
    // user map.  A username and password is still not required because the
    // expected response is a Type 2 Message, the NTLM server's response to
    // Type 1 message
    Map user = new HashMap( ) ;
    user.put( UserConstants.AUTHENTICATION_TYPE, AuthTypes.SC_NTLM ) ;
    user.put( UserConstants.SC_NTLM_HANDSHAKE, handshake ) ;
    Map result = proxy.authenticate( user ) ;

    // The Type 2 Message is returned as a base 64 encoded string; decoding
    // it yields an lmResponse or an ntResponse that is the essential data
    // in a Type 2 Message, and is used to construct a new Type 2 Message
    handshake = (String) result.get( UserConstants.SC_NTLM_HANDSHAKE ) ;
    Type2Message type2 = new Type2Message( Base64.decode( handshake ) ) ;

    // A Type 3 Message is constructed using the server's response in the
    // Type 2 Message, and the user's credentials.  When the authorization
    // receives a Type 3, it can authenticate the user against the domain
    // and map the domain user to a ClearTrust user.
    Type3Message type3 = new Type3Message( type2, password, domain, user, null ) ;
    handshake = new String( Base64.encode( type3.toByteArray( ) ) ) ;

    // The original Type 1 Message is replaced with the Type 3 Message
    user.put( UserConstants.SC_NTLM_HANDSHAKE, handshake ) ;

    // The authenticate method returns a result map containing the mapped
    // ClearTrust user ID and a ClearTrust token.

    return proxy.authenticate( user ) ;

Legacy Article IDa36504