Copyright © Cloud Software Group, Inc. All rights reserved.

Developing a Replacement User Validation Package

The following sections provide important guidelines for developers creating a new user validation package that uses the TIBCO iProcess User Validation API interfaces.

Thread Safety

IMPORTANT! You must ensure that any user validation package you create using the User Validation API is threadsafe - see page 14 for more information. To ensure that your user validation package is threadsafe, make sure that you adhere to the following guidelines: • Make sure that any modules in your user validation package that use User Validation API interfaces use threadsafe code. • Use mutual exclusion locks (mutexes) to prevent multiple threads from simultaneously executing any critical sections of code that are not threadsafe, but that access shared data. • When you build the user validation package, make sure that you use the appropriate flags (for your chosen operating system and compiler) to link the application using threadsafe libraries. Deploying a non-threadsafe user validation package can cause TIBCO iProcess Engine processes to fail.

Internal Function Names

When developing a new UVAPI package, you must provide internal functions that support the external interfaces detailed in this chapter. The internal function names are based on the external interfaces, but prefixed with “int_”. Therefore, the internal function to support the uva_initialise interface is called int_uva_initialise. The return and argument types are the same as the external interfaces. The only difference is that the external interfaces pass all strings in an encrypted form but the internal functions receive and return all strings as plain text.

The supplied iProcess encryption object provides all of the external interface functions, decrypts/encrypts string parameters and then calls the internal function supplied by you. System security is enhanced by only passing encrypted strings between iProcess and the UVAPI package.

Interface Support

If you do not want to support a particular interface (and the default iProcess action is appropriate) the internal function can return the value ER_NOTIMPLEMENTED. This causes iProcess to perform its default action using the internal functionality for that interface. If you do not want iProcess to perform the default action, you can return the value SW_OK (depending on the interface).

Password Validation on Windows Systems

The information in this section is only relevant to the Windows variant of the iProcess Engine.

If the iProcess Engine is running on a machine that is a member of a domain or a domain controller, it uses the search path provided by the Windows LookupAccountName function to find the location it should use to validate a user’s password when they try to log in.

However, there are two ways in which you can override this behavior and directly specify the location where password validation is to be performed, either on a per-user basis, or globally for an installation:

1.

the SW_DOMAIN user attribute specifies a single valid machine name or domain name that should be used to validate a particular user’s password when they attempt to log in to the iProcess Engine. See TIBCO iProcess Windows (Workspace) Manager’s Guide for more information about this attribute and how to set it.

2.

the LOGON_OS_LOCATION process attribute defines the default location where passwords should be validated when any user attempts to log in to the iProcess Engine. See the "Administering Process Attributes" chapter of the TIBCO iProcess Engine Administrator’s Guide for more information about this attribute and how to set it.

Note that: • If both attributes are set, the SW_DOMAIN value takes precedence over the LOGON_OS_LOCATION value. • If the iProcess Engine is running on a standalone machine, passwords are always validated against local machine accounts. The SW_DOMAIN and LOGON_OS_LOCATION attributes are ignored even if they are set.

If you use the SW_DOMAIN or LOGON_OS_LOCATION attributes, your UVAPI package must be able to receive and return the additional information about a user’s location, to ensure that their password is checked in that location.

To facilitate this, the UVAPI includes extended (_ex) versions of the following interfaces:

•	uva_next_user_ex

•	uva_user_info_ex

•	uva_change_password_ex

•	uva_check_password_ex

•	uva_set_user_identity_ex

These interfaces can accept (and, in the case of uva_next_user_ex, return) an iProcess user name in either of the following formats:

Format	Description
name	name is the iProcess user name. This format is also supported by the equivalent non-extended interfaces.
name@location	name is the iProcess user name. location is the value (machine or domain name) provided by either the user’s SW_DOMAIN user attribute (if defined), or the value of the LOGON_OS_LOCATION process attribute. This format is not supported by the equivalent non-extended interfaces.

If your UVAPI package supports these extended interfaces, they are called instead of the non-extended interfaces. If these interfaces do not exist or return ER_NOT_SUPPORTED (see Interface Support), the non-extended interfaces are called instead.

You should ensure that you use these extended interfaces if you use the SW_DOMAIN or LOGON_OS_LOCATION attributes.

Creating a Session Handle

The UVAPI package works on a session which is allocated by the uva_initialise function. This function must return a session identifier (handle). You need to be aware that several threads in a iProcess process can be using the UVAPI interfaces so you must make sure that the session allocation and management is performed in a thread-safe manner.

Design Issues

You should be aware that several different iProcess processes will call the UVAPI package while the TIBCO iProcess Engine is running. This can cause problems if the UVAPI package is not designed correctly. The example application provides a good example of this.

The user information is stored in the text file and each iProcess process that uses the UVAPI package loads the contents of the text file into a memory cache. However, these caches are specific to each session and to each iProcess process. Therefore, when an iProcess user causes its iProcess process to perform a change password action, that process updates the main text file and the processes’ cache.

This means that other iProcess processes (including the one that validates iProcess passwords) will still be using the original cached copy of the data in the text file. Therefore, the example UVAPI does not reflect a changed password until the iProcess system is shutdown and restarted. This is the only way that all the processes can re-cache the user information.

To avoid this problem, you need to design the UVAPI package as a set of interfaces that communicate with a single server process that maintains the user information, ensuring that any changes to the user information is made available to all the iProcess processes using the UVAPI package.

Copyright © Cloud Software Group, Inc. All rights reserved.