Authenticate Method  
 

Authenticate the client and assign access rights for the session.

Syntax

object.Authenticate( ClientId, [AccessFlags], [Directory] )

Parameters

ClientId
An integer that identifies the client session.
AccessFlags
An optional integer value which specifies the access clients will be given when authenticated as this user. This value created from one or more bitflags. For a list of user access permissions, see User Access Constants. If this parameter is omitted, the client is authenticated using the default access permissions based on the server configuration.
Directory
An optional string which specifies the directory that will be the client's home directory. If the server was started in multi-user mode, this directory will be relative to the user directory created by the server, otherwise it will be relative to the server root directory. If the directory does not exist, it will be created. If this parameter is omitted or is an empty string, a default home directory will be created for the client.

Return Value

A value of zero is returned if the client session was authenticated. Otherwise, a non-zero error code is returned which indicates the cause of the failure.

Remarks

The Authenticate method authenticates a client session, typically in response to an OnAuthenticate event that indicates a client has requested authentication. It is recommended that most applications specify ftpAccessDefault as the AccessFlags parameter for a client session, since this allows the server automatically grant the appropriate access based on the server configuration options for normal and anonymous users. If the server is going to be publicly accessible or third-party FTP clients will be used to access the server, you should always grant the ftpAccessList permission to clients. Many client applications will not function correctly if they are unable to obtain a list of files in the user's home directory.

If the server was started with the MultiUser and Restricted properties set to a value of True, the client session will be effectively locked to its home directory and cannot navigate to the server root directory. By default, restricted client sessions are also limited to only downloading files and requesting directory listings. If a client session is not restricted, the client can access files outside of its home directory. Regardless of this option, a client cannot access files outside of the server root directory.

If the Restricted property is True or the ftpAccessAnonymous permission is specified, the client session will be authenticated in a restricted mode and the access rights for the session will persist until the client disconnects from the server. Unlike regular users, the access rights for a restricted client cannot be changed by the server at a later point. This restriction is designed to prevent the inadvertent granting of rights to an untrusted client that could compromise the security of the server.

If the Directory parameter is omitted or is an empty string and the server has been started in multi-user mode, each user is assigned their own home directory based on their username. If the server has not been started in multi-user mode, then the default home directory will be the server root directory and is shared by all users. The ClientHome property will return the full path to the home directory for an authenticated client.

If the ftpAccessExecute permission is granted to the client session, it can execute external programs using the SITE EXEC command. Because the program is executed in the context of the server process, it is recommended that you limit access to this functionality and ensure that the programs being executed do not introduce any security risks to the operating system. This permission is never granted by default, and the SITE EXEC command will return an error if the client session is anonymous, regardless of whether this permission is granted or not.

This method is should only be used for custom authentication schemes and is not necessary if you have used the AddUser method to create virtual users.

See Also

MultiUser Property, Restricted Property, AddUser Method, DeleteUser Method, OnAuthenticate Event