README.SSO

===============================================================================
                        Windows Single Sign On in jTDS
                             ~~~~~~~~~~~~~~~
              Patch Submitted by Magendran Sathaiah (mahi@aztec.soft.net)
===============================================================================

Introduction
============

    This document describes the design of the Single Sign On implementation in
    the jTDS JDBC driver.

    (Note: This feature requires DES and MD5 implementations. The JCA/JCE 
    is used to access such implementations. The algorithms were previously 
    implemented directly in jTDS' sources, but to eliminate export control 
    restrictions, they were removed and the code now uses the JCA/JCE. Note
    that MD4 is still implemented directly in jTDS.)

    Releases 0.9.1 and earlier of jTDS driver support Windows authentication by
    means of the NTLM protocol. That is, clients using the JDBC Driver passes
    a valid Windows-Domain-Name, a Windows User and Windows Password; the JDBC
    driver will submit these to Microsoft SQL Server via NTLM protocol in order
    to gain access to the database. (This approach still works with all later
    versions, allowing Windows Authentication to work for non-Windows clients
    or clients that don't/can't have the native library installed.)

    In the above approach the client will have to maintain a configuration file
    to keep the windows logon credentials. That is, the domain name, user name
    and password need to be stored in encrypted or plain text format. This
    might not be an acceptable solution for everybody.

    Starting with release 0.9.2 jTDS is capable of using the Windows
    credentials of the current user under whose account the client program is
    running to login to SQL Server (Windows Single Sign On).

    Using Windows Single Sign On (SSO) clients will be able to connect to
    Microsoft SQL Server without providing credentials. It would dynamically
    read current user's credentials and connect to the database. provided that
    the Windows account has enough rights in the database. This is done using a
    native (Windows-only) library, ntlmauth.dll.


Installation
============

    In order for Single Sign On to work, jTDS must be able to load the native
    SPPI library (ntlmauth.dll). Place this DLL anywhere in the system path
    (defined by the PATH system variable) and you're all set.


Usage
=====

    In order to set up the jTDS driver to use Windows Single Sign On, users
    will have to connect without providing a user name and password. This will
    only work on Windows.

    Driver example:

        // No user name or password in URL or as parameters
        DriverManager.getConnection(
                "jdbc:jtds:sqlserver://localhost:1433/LionKing");

    DataSource example:

        ds = new JtdsDataSource();
        ds.setDescription("test");

        // MS SQL Server Host Name
        ds.setServerName("localhost");

        // Port
        ds.setPortNumber(1433);

        // Database Name
        ds.setDatabaseName("LionKing");

        // No domain name
        // No user name

        Connection conn = ds.getConnection();


Design
======

    The patch comprises the following components:

    1. ntlmauth.dll
        A CPP Program that uses SSPI Windows APIs to accquire credentials and
        NTLM messages from the Windows Operating System.

    2. SSPIJNIClient.java
        A Java Native Interface class that bridges jTDS JDBC driver and
        ntlmauth.dll.

    3. Modified Version jTDS source files.
        A set of modified jTDS java files that make use of the
        SSPIJNIClient.java when the driver is set to use Windows Single Sign On.


SSPIJNIClient.java
==================

    It loads the DLL (ntlmauth.dll) in a static block. The ntlmauth.dll must be
    available in the system path (defined by the system variable PATH). It
    exposes the following APIs:

    public static SSPIJNIClient getInstance() throws Exception;

        Retuns the singleton SSPIJNIClient object.

    private native void initialize();

        Initializes the SSPI Client.

    private native void unInitialize();

        Uninitializes the SSPI client.

    private native byte[] prepareSSORequest();

        Prepares NTLM TYPE-1 message and returns it as a byte[].

    private native byte[] prepareSSOSubmit(byte[] challengeBuf, long size);

        Prepares NTLM TYPE-3 message using current user's credentials. It needs
        the challenge BLOB and its size as input. The challenge BLOB is nothing
        but the TYPE-2 message that is received from the SQL Server.

    API Usage:
    ----------

            ntlmAuthSSO = (user == null || user.length() == 0);
            if (ntlmAuthSSO) {
                sspiJNIClient = SSPIJNIClient.getInstance();
                ntlm1 = sspiJNIClient.invokePrepareSSORequest();
            }

            // 1.ntlm1 contains Type-1 message now
            // 2.Send Type-1 Message to the server
            //
            // 3.MS SQL Server replies back with Type-2 message
            // 4.Read Type-2 Message in (say) ntlm2

               ntlm3 = sspiJNIClient.invokePrepareSSOSubmit(ntlm2);

            //1.now, ntlm3 contains Type-3 message
            //2.Send, Type-3 message to the Server.
            //3.Check the status - Success | Failure.


Modifications to jTDS Classes
=============================
        The TdsCode.java has been modified as follows

        1. Member boolean variable: ntlmAuthSSO
            A flag that is used to indicate if the client wants to do Windows
            Single Sign On. The variable is set in the logon(...) as below

            ntlmAuthSSO = (user == null || user.length() == 0);

            Note: The user must leave the user name (and password) unset or set
                  them to null or a blank string to instructthe driver to use
                  Windows Single Sign On.

        2. Member Variable: sspiJNIClient
            A reference to the single-ton object of SSPIJNIClient.class
            It gets initialzied in logon(..) if ntlmAuthSSO is true.

        3.  login(..)
            At the begining of the method check if Windows Single Sign On is
            requested (ntlmAuth == true)

            If so initialize the SSPI client and prepare NTLM TYPE-1 message

        4. send70Login(..)
            Modified to accept an additional byte[] parameter to pass the NTLM
            Type-1 message.

            Set the authLen = ntlmMessage.legnth() if ntlmAuthSSO is true

        5. sendNtlmChallengeResponse(...)

           If ntlmAuthSSO is true, then read the Type-2 message from
           authToken.getNTLMMessage()

           Prepare Type-3 message as below

           type3 = sspiJNIClient.invokePrepareSSOSubmit(type2)

           Then append it to the command buffer.

------------------------------------------------------------------------------------------------------
Magendran Sathaiah
mahi@aztec.soft.net

Version: $Id: README.SSO,v 1.1 2004-12-21 12:06:59 alin_sinpalean Exp $