Password Exit

Instead of the default authentication process that takes place when users log on an Automation Engine system, administrators can install a password exit function that authenticates login attempts to the AE system. These can be from any source, whether over the Automic Web Interface (AWI) login page, from a command-line call, from a REST API call, or from any other connection method. Programming skills are required for this function.

Authentication is successful only when the login parameter values (for AE Client, User name, optional department, and password) match those of a User object in the AE system.

After successful authentication, access to function areas and objects is controlled by user privileges and authorities. For more information, see Granting Automation Engine Authorizations

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. For more information, see About Service Orchestration.

This page includes the following:

Requirements

You need a create a program library that includes specific C functions. Automic provides a sample implementation that you find in the delivery directory SystemExit\xuc4pass. It includes Makefiles for Windows and Unix that you can modify according to your requirements.

Important!

The password exit function overrules the LDAP function in case you have activated both. This means that when the system returns the states authenticated or access denied, the LDAP connection is not used. It will only be used if the password exit is inactive or has been deactivated. For more information, see LDAP Connection Setup.

The following C functions are required:

  • XUC4PASS_Open(AE system, parameter, callback function)

    This function is called in all work processes (WP) when the Automation Engine starts. The password exit is not active if this function ends with a return code other than 0. No additional calls are made in this case.

    Parameters

    • AE system
      Data type: char*

    • parameter
      Data type: char*

    • callback function
      Data type: void*

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

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

  • XUC4PASS_Close()

    This function is called in all work processes (WP) when the Automation Engine ends provided the exit was successfully opened.

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

    This function is called in the current primary work process (PWP) with each AE login attempt. This function returns one of the codes listed in this document.

    Parameters

    • client
      Data type: int

    • user name
      Data type: char*

    • department
      Data type: char*

    • password
      Data type: char*

    • language
      Data type: char
      Possible values: D, E and F

    • computer name
      Data type: char*

    • login type
      Data type: char
      Possible values: D - Dialog, C - CallAPI, W - WebInterface, A - ApplicationInterface, U - Utility

    • output area length
      Data type: int

    • output area
      Data type: char*user name

      The output area can be any text that is output in a message box after a successful login. It is only shown when you log on via the AWI and can be read with the Application Interface.

      Important!

      • The text must not exceed the length of the output area.

      • The XUC4PASS_Execute function is called with each login attempt. When processing this function takes long, this will block the PWP from other tasks.

Return Codes

  • 0
    User was successfully authenticated. The password will be saved afterward as user password in the database
    Constants:
    XUC4PASS_EXECUTE_EXIT_OK
    XUC4PASS_EXECUTE_EXIT_AUTHENTICATED

  • 1
    User was not successfully authenticated (Example: wrong password was used)
    Constant:
    XUC4PASS_EXECUTE_EXIT_DENIED

  • 2
    User is blocked
    Constant:
    XUC4PASS_EXECUTE_EXIT_DENIED_LOCK

  • 3
    The password exit has not checked the user
    Constant:
    XUC4PASS_EXECUTE_EXIT_INACTIVE

  • 4
    The password is valid, but will not be saved in the database after authentication
    Constant:
    PEXIT_RETCODE_AUTHENT_NO_PASSWORD

The data type of all return codes is long.

Installation Procedure

  1. Copy the created program library to all computers on which WPs are started. The path you define must be the same as is defined in the UC_SYSTEM_SETTINGS variable. It is highly recommended to copy it to the Automation Engine installation directory.

  2. Open the Automic Web Interface and log on to client 0 of the AE system where you want to enable the password exit function.

  3. Open the UC_SYSTEM_SETTINGS variable.

  4. Go to the PASSWORD_EXIT key. If it does not yet exist, add it. Enter the name and path of the program library you created in the value section.

  5. If you want to assign parameters, go to the PASSWORD_EXIT_PARAM key.

  6. Restart your AE system to activate the password exit.

The Administration Perspective shows password exit information. For details, see Exits.

See also: