Password Exit

The login data of an AE user contains values for the client, user name, department and password. During the authentication process AE compares the login information that is entered with the stored user data to grant or deny access. 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. For more information, see Granting Automation Engine Authorizations) must be available in the AE system.

Note: This integration capability, like all integrations of the Automic system, can support service orchestration workflows. Such workflows orchestrate automated processes that run across multiple platforms, domains, and applications to deliver a specific IT service.

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 - AE.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 AE.ApplicationInterface. Important! 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 - AE.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 AE.ApplicationInterface.

Important!

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 (Example: 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 you can modify according to the application development.
If both the password exit and LDAP are activated, the password exit has a higher priority. 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.

Open the Automic Web Interface and login to client 0 in the AE instance in which you want to enable password exits.
Open the variable UC_SYSTEM_SETTINGS for editing.
Enter the key PASSWORD_EXIT. If it does not yet exist, enter the name and path of the program library, which you previously created, in the value section.
If parameters should be assigned, enter the key PASSWORD_EXIT_PARAM.
Restart your AE instance to activate the password exit.

For information about managing password exits, see Exits.