Password Exit

The login data of an AE user contains information about the client, user name, department and password. During the authentication process AE compares the login information that is entered with the stored user data. Depending on the result of this comparison, access is either granted or denied.

Also, the Automation Engine provides a password exit which can be used to verify or - where necessary - reject attempts to log on to the AE system via a custom-developed program library. The password exit is called for any type of AE user logon (Automic Web Interface, CallAPI).

When using the password exit for verifying user authentication, the AE-specific authentication information (users with the appropriate rights and privileges) must be available in the AE system. For more information, see Granting Automation Engine Authorizations.

This page includes the following:

Requirements

It is necessary to implement a program library which contains the following C functions:

Description	Data type of return code	C function
Is called in all work processes (WP) when the Server starts. The password exit is not active if this function ends on a return code unequal zero. No more calls are made.	long	XUC4PASS_Open(AE system, parameter, callback function) Data type of AE system: char* Data type of parameters: char* Data type of callback function: void* Use the callback function to print text outputs in the Automation Engine's log file. Define the callback function as shown below: typedef void (WINAPI UC4_LOGTEXT)(char pText);
It is called in all work processes (WP) when the Server has ended provided the exit could successfully be opened.	long	XUC4PASS_Close()
Is called in the current primary work process (PWP) with each AE login. This function must return a return code of the following table.	long	XUC4PASS_Execute(client, user name, department, password, language, computer name, login type, length of output area, output area) Data type of client: int Data type of user name: char* Data type of department: char* Data type of password: char* Data type of language: char (possible values: "D", "E" and "F") Data type of computer name: char* Data type of the login type: char (possible values: "D" - Dialog, "C" - CallAPI, "W" - WebInterface, "A" - ApplicationInterface, "U" - Utility) Data type of output area length: int Data type of output area: char* The output area is any text which is output in the message box after successful logon. Only login via the Automic Web Interface has the effect that this text is displayed. It can be read with the ApplicationInterface. Important! Note that the text must not exceed the length of the output area. The function XUC4PASS_Execute is synchronously called with each login. A long processing time in this function blocks the PWP for other tasks.

Description

Data type of return code

C function

Is called in all work processes (WP) when the Server starts. The password exit is not active if this function ends on a return code unequal zero. No more calls are made.

long

XUC4PASS_Open(AE system, parameter, callback function)

Data type of AE system: char*
Data type of parameters: char*
Data type of callback function: void*

Use the callback function to print text outputs in the Automation Engine's log file. Define the callback function as shown below:

typedef void (WINAPI *UC4_LOGTEXT)(char *pText);

It is called in all work processes (WP) when the Server has ended provided the exit could successfully be opened.

long

XUC4PASS_Close()

Is called in the current primary work process (PWP) with each AE login. This function must return a return code of the following table.

long

XUC4PASS_Execute(client, user name, department, password, language, computer name, login type, length of output area, output area)

Data type of client: int
Data type of user name: char*
Data type of department: char*
Data type of password: char*
Data type of language: char (possible values: "D", "E" and "F")
Data type of computer name: char*
Data type of the login type: char (possible values: "D" - Dialog, "C" - CallAPI, "W" - WebInterface, "A" - ApplicationInterface, "U" - Utility)
Data type of output area length: int
Data type of output area: char*

The output area is any text which is output in the message box after successful logon. Only login via the Automic Web Interface has the effect that this text is displayed. It can be read with the ApplicationInterface.

Important!

Note that the text must not exceed the length of the output area.
The function XUC4PASS_Execute is synchronously called with each login. A long processing time in this function blocks the PWP for other tasks.

Return codes of the function XUC4PASS_Execute:

Value	Constant	Description
0	XUC4PASS_EXECUTE_EXIT_OK XUC4PASS_EXECUTE_EXIT_AUTHENTICATED	User was successfully authenticated. The password will be saved afterward as user password in the database.
1	XUC4PASS_EXECUTE_EXIT_DENIED	User was not successfully authenticated (e.g. wrong password was used).
2	XUC4PASS_EXECUTE_EXIT_DENIED_LOCK	User is blocked.
3	XUC4PASS_EXECUTE_EXIT_INACTIVE	The password exit has not checked the user.
4	PEXIT_RETCODE_AUTHENT_NO_PASSWORD	The password is valid, but will not be saved in the database after authentication.

Notes:

A sample implementation is available in the delivery directory SystemExit\xuc4pass. It includes Makefiles that can be adjusted according to the application development.
The password exit has a higher priority than the LDAP connection if both are activated. If the states "authenticated" or "access denied" are returned, the LDAP connection is not called at all. It is only called if the password exit is inactive or has been deactivated. For more information, see LDAP Connection Setup.

Installation Procedure

Copy the generated program library to all computers on which WP Servers are started. The indicated path must always be the same as it is specified in the variable UC_SYSTEM_SETTINGS only once.

Notes:

Copy the generated library to the Server installation directory.

Use the Automic Web Interface to log on to client 0 in the AE system.
Open the variable "UC_SYSTEM_SETTINGS" for editing. Enter the key "PASSWORD_EXIT". If it does not yet exist, store the name and path of the previously created program library in the value section. Enter the key "PASSWORD_EXIT_PARAM" if parameters should be assigned.
Now restart your AE system in order to activate the password exit.
Information about the Password Exit is available in the Exits.