Copyright © Cloud Software Group, Inc. All Rights Reserved
Copyright © Cloud Software Group, Inc. All Rights Reserved


Chapter 2 The TIBCO iProcess User Validation API : Developing a Replacement User Validation Package

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
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
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.
2.
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:
These interfaces can accept (and, in the case of uva_next_user_ex, return) an iProcess user name in either of the following formats:
name is the iProcess user name.
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
Copyright © Cloud Software Group, Inc. All Rights Reserved