MobiLink Synchronization Reference
  Synchronization Events

authenticate_user connection event

Function 

Implements a custom user authentication mechanism.

Parameters 

In the following table, the description provides the SQL data type. If you are writing your script in Java or .NET, you should use the appropriate corresponding data type. See SQL-Java data types and SQL-.NET data types.

Event parameters are optional only if no subsequent parameters are specified. For example, you must use parameter 1 if you want to use parameter 2.

Default action 

Use MobiLink built-in user authentication mechanism.

Description 

The MobiLink synchronization server executes this event upon starting each synchronization. It is executed in a transaction before the begin_synchronization transaction.

You can use this event to replace the built-in MobiLink authentication mechanism with a custom mechanism. You may want to call into the authentication mechanism of your DBMS, or you may wish to implement features not present in the MobiLink built-in mechanism, such as password expiry or a minimum password length.

The parameters used in an authenticate_user event are as follows:

1. auth_status    This required parameter is an INOUT parameter: a parameter that provides a value to the script, and could be given a new value by the script. The auth_status parameter indicates the overall success of the authentication, and can be set to one of the following values:

   Returned Value	Auth_status	Description
   V <= 1999	1000	Authentication succeeded.
   1999 < V <= 2999	2000	Authentication succeeded: password expiring soon.
   2999 < V <= 3999	3000	Authentication failed: password expired.
   3999 < V <= 4999	4000	Authentication failed.
   4999 < V <= 5999	5000	Authentication failed as user is already synchronizing.
   5999 < V	4000	If the returned value is greater than 5999, MobiLink interprets it as a returned value of 4000.

2. ml_username    This optional parameter is the name of the remote database.

3. user_password    This optional parameter indicates the password for authentication purposes. If the user does not supply a password, this is NULL.

4. user_new_password    This optional parameter indicates a new password. If the user does not change their password, this is NULL.

SQL scripts for the authenticate_user event must be implemented as stored procedures.

When the two authentication scripts are both defined, and both scripts return different auth_status codes, the higher value is used.

The authenticate_user script is executed immediately before, and in the same transaction as, the begin_synchronization script. The transaction is ended immediately after the begin_synchronization script.

See also 

Authenticating MobiLink Users

Custom user authentication

authenticate_user_hashed connection event

authenticate_parameters connection event

modify_user connection event

begin_synchronization connection event

SQL example 

A typical authenticate_user script is a call to a stored procedure. The order of the parameters in the call must match the order above. In an Adaptive Server Anywhere consolidated database, the script could be as follows.

call my_auth ( ?, ?, ?, ? )

The following Adaptive Server Anywhere stored procedure uses only the user name to authenticate—it has no password check. The procedure ensures only that the supplied user name is one of the employee IDs listed in the ULEmployee table.

CREATE PROCEDURE my_auth(in @user_name varchar(128))
begin
  if exists
  ( select * from ulemployee
    where emp_id = @user_name )
  then
    message 'OK' type info to client;
    return 1000;
    else
    message 'Not OK' type info to client;
    return 4000;
  end if
end

Java example 

The following stored procedure call registers a Java method called authenticateUser as the script for the authenticate_user event when synchronizing the script version ver1. This syntax is for Adaptive Server Anywhere consolidated databases.

call ml_add_java_connection_script(
   'ver1', 'authenticate_user',
   'ExamplePackage.ExampleClass.authenticateUser' )

Following is the sample Java method authenticateUser. It calls Java functions that check and, if needed, change the user's password.

public String authenticateUser
( ianywhere.ml.script.InOutInteger authStatus,
  String user, String pwd, String newPwd )
  throws java.sql.SQLException
{  // in a real authenticate_user handler, we would
   // handle more auth code states
   _curUser = user;
   if( checkPwd( user, pwd ) )
   {  // auth successful
      if( newPwd != null )
      {  // pwd is being changed
         if( changePwd( user, pwd, newPwd ) )
         {  // auth ok and pwd change ok. Use custom code
            authStatus.setValue( 1001 ); 
         }
         else {  // authorization ok but password
                 // change failed. Use custom code.
                 java.lang.System.err.println( "user: "
                 + user + " pwd change failed!" );
                 authStatus.setValue( 1002 ); } }
        else {  authStatus.setValue( 1000 ); } }
        else {  // auth failed
           authStatus.setValue( 4000 ); }
   return( null ); }

.NET example 

The following stored procedure call registers a .NET method called AuthUser as the script for the authenticate_user connection event when synchronizing the script version ver1. This syntax is for Adaptive Server Anywhere consolidated databases.

call ml_add_dnet_connection_script(
   'ver1', 'authenticate_user',
   'TestScripts.Test.AuthUser'
)

Following is the C# signature for the method AuthUser.

public void AuthUser( ref int authStatus, string user, string pwd, string newPwd )

For a more detailed example of an authenticate_user script written in C# in .NET, see .NET synchronization example.