Product Documentation

Application Definition Extensions

May 11, 2015

Although Single Sign-on administrators can generally create application definitions using the Single Sign-on component to the Citrix AppCenter and the Application Definition Tool, some applications have special considerations or requirements that need an external process to determine if an application started or to submit user credentials using Single Sign-on Plug-in.

To support applications that have these types of requirements, third-party implementers that create processes to satisfy these external processing requirements can use Application Definition Extensions in the Single Sign-on component of the Citrix AppCenter and the Application Definition Tool to configure when and how these processes are initiated.

Single Sign-on Plug-in Software Operation

There are two different types of application definition extensions:

  • Identification Extensions

    Use external processes to determine if the target application is a form that requires user credential management actions. These external processes can be used instead of or in conjunction with other window detection algorithms defined in the form definition

  • Actions Extensions

    Use external processes to perform the required user credential management actions. These external processes can be used instead of or in conjunction with other window action algorithms defined in the form definition

A single form definition can be configured to use application definition extensions to perform either or both of these operations.

Identification Extensions

The Single Sign-on Plug-in uses listener hooks to detect events on the desktop such as application instantiation, URL loading, HTML page document complete notices, and other similar events.

As these events occur, the plug-in determines if the target application requires any user credential management action (such as ignore, logon, change password, and so on). The determination is made by comparing the characteristics exposed by application against the defined characteristics that uniquely identify a form. These characteristics include the Windows title and the executable file name (at a minimum) and, if required, other advanced matching characteristics that can include using an external process to identify the form (identification extension).

If an external identification process is required, the process or processes are identified in the form definition. The form definition includes information about the identification extension and any associated parameters. These are directly associated with a registry setting.

After the plug-in successfully processes the minimum matching and advanced matching algorithms, identification extensions that use an external process are evaluated.

When multiple identification extensions are defined to evaluate a form, the extensions are executed in the order that they appear in the identification extensions page (from top to bottom).

For each identification extension, the plug-in waits the specified amount of time (defined in the registry setting) for the external process to exit before it analyzes the process exit code.

If the minimum matching, advanced matching, and external matching processes complete with a zero return code, the target application is considered a match. If any matching process exits with any other value, the evaluation process stops and the application is considered not a match.

If a negative value is returned, an error is logged to the Windows Event Viewer. Positive values are written to a log file, if enabled.

The subsequent user credential management action can be performed by using any combination of standard Windows form actions, action sequences, or action extensions.

To define an identification extension

Configure identification extensions using the Form Definition Wizard during the application definition development process.

  1. From AppCenter, expand the Single Sign-on node, select Application Definitions, and, from the Action menu, click Create application definition.
  2. In the Application Definitions Wizard, continue to the Manage forms page, and select Add Form to start the Form Definition Wizard.
  3. Advance through the definition process until the Identify form page appears.
  4. On the Identify form page, click Advanced Matching. The appears.
  5. In the Advanced Matching dialog box, click Identification Extensions.
  6. On the Identification Extensions page, click Add to open the Add Identification Extension dialog box. The Add Identification Extension dialog box is used to define the following:
    Extension ID The extension ID identifies the ExtensionName to look for in the registry settings.
    Description A user-defined description of the identification extension being defined.
    Parameters Any name/value pairs (parameter name/parameter value) that are used to pass implementer-defined parameters to the external process that is launched by this extension.

    The ExtensionName identifies a registry key name. This key name and its associated key values define the external identification process executable and its operating characteristics. The registry key name and its associated keys are located at:

    [HKEY_LOCAL_MACHINE\SOFTWARE\Citrix\MetaFrame Password Manager\Extension\{ExtensionName}]

    Where the ExtensionName value is identified using the Extension ID value in the Add Identification Extension dialog box.

    On 64-bit platforms the registry key name and its associated keys are located at:

    [HKEY_LOCAL_MACHINE\SOFTWARE\Wow6432Node\Citrix\MetaFrame Password Manager\Extension\{ExtensionName}]

    The following table defines the key value characteristics.

    Key Type Value
    Type REG_SZ Must be EXECUTABLE
    Timeout REG_DWORD 0 to wait forever for application to complete. Any other value is time to wait in milliseconds.
    TerminateProcess BOOL implemented as a REG_DWORD

    (optional) On time-out, terminate process.

    TRUE—(default) Terminate process.

    FALSE—(0) Do not terminate process.

    Executable REG_EXPAND_SZ The executable process and its fully qualified path.
    Arguments REG_SZ Parameters for the executable.

    The Executable value is the full path to the executable file. Environment variables are allowed. If the extension is implemented as a script, the script interpreter must be used for the Executable, and the script name as part of the Arguments. External processes can be developed using any editor/language or IDE of your choosing.

    The Arguments value supports parameters that the plug-in software can replace with run-time parameters or the parameter name/value pairs specified in the Add Identification Extension dialog box. Each parameter that needs substitution must be prefixed and suffixed with a dollar sign ($) delimiter. For example, the following command-line arguments:

     
    /h $_HANDLE$ /s $SAPSERVER$ /t $SAPTYPE$ 
    

    appear to the executable as:

     
    /h 1275366 /s “Houston, TX” /t 43 
    

    The Microsoft Windows handle associated with the application is a supported internal parameter defined as $_HANDLE$.

    All internal parameters use $_ as a preface to avoid naming conflicts. Implementer parameters are not allowed to use underscores in key names.

    Substitution precedence is defined to preserve parameter values after they are written. The precedence is defined as internal parameters (such as $_HANDLE$), followed by implementer parameters, followed by environmental variables.

    All implementer parameters are permitted to use lowercase and uppercase letters and numbers in key names. Key names are case-insensitive.

    If the extension identification executable requires parameters to be presented in a specific sequence, the Argument must support the required sequence. The parameter name/value pairs defined in the Add Identification Extension dialog box can be in any sequence.

Action Extensions

Action extensions use an external process to manage user credential management actions. The extension definition process has the ability to pass user credentials to the external application.

After a user credential management form is successfully identified (see Identification Extensions), the subsequent user credential management action can be performed using any combination of standard Windows form actions, action sequences, or action extensions.

The Single Sign-on Plug-in supports the same features described in Identification Extensions.

The plug-in executes the external process and waits the specified time for the process to exit (if WaitForCompletion is set to TRUE) and then analyzes its Process Exit Code. If the process exits with a zero return value, the extension executed successfully. Any non-zero return indicates an error.

If a negative value is returned, the error is logged to the Windows Event Viewer. Positive values are written to a log file, if enabled (see Enabling Logging for additional information).

To define an action extension

Configure action extensions using the Form Definition Wizard during the application definition development process.

  1. From the Citrix AppCenter, expand the Single Sign-on node, select Application Definitions, and, from the Action menu, click Create application definition.
  2. In the Application Definitions Wizard, continue to the Manage forms page, and select Add Form to start the Form Definition Wizard.
  3. Advance through the definition process until the Define form actions page appears.
  4. On the Define form actions page, click Action Editor.
  5. From the Action Editor dialog box, select Launch action extension. The Configuration Actions panel appears. This panel is used to view, edit, or add Launch action extension entries to the action sequence.
  6. To add an action extension to the action sequence, provide the following information and click Insert:
    ID The ID identifies the ExtensionName to look for in the registry settings.
    Description A user-defined description of the action extension being defined.
    Parameters Any name/value pairs (parameter name/parameter value) that are used to pass implementer-defined parameters to the external process that is launched by this extension.

    As with the identification extensions, the ExtensionName identifies a registry key name. This key name and its associated key values define the action processing executable and its operating characteristics. The registry key name and its associated keys are located at:

    [HKEY_LOCAL_MACHINE\SOFTWARE\Citrix\MetaFrame Password Manager\Extension\{ExtensionName}]

    Where the ExtensionName value is identified using the ID value in Action configuration panel.

    On 64-bit platforms the registry key name and its associated keys are located at:

    [HKEY_LOCAL_MACHINE\SOFTWARE\Wow6432Node\Citrix\MetaFrame Password Manager\Extension\{ExtensionName}]

    The following table defines the key value characteristics.

    Key Type Value
    Type REG_SZ Must be EXECUTABLE
    Timeout REG_DWORD 0 to wait forever for application to complete. Any other value is time to wait in milliseconds.
    TerminateProcess BOOL implemented as a REG_DWORD

    (optional) On time-out, terminate process.

    TRUE—(default) Terminate process.

    FALSE—(0) Do not terminate process.

    WaitForCompletion BOOL implemented as a REG_DWORD

    (optional) Plug-in waits for process to exit.

    TRUE—(default) Wait.

    FALSE—(0) Do not wait.

    Executable REG_EXPAND_SZ The executable process and its fully qualified path.
    Arguments REG_SZ Parameters for the executable.

    The Executable value follows the same conventions as the identification extensions.

    The Arguments value supports parameters that the plug-in can replace with run-time parameters or the parameter name/value pairs specified in the Launch action extension view of the Action Editor. Each parameter that needs substitution must be prefixed and suffixed with a dollar sign ($) delimiter. For example, the following command-line arguments:

     
    /h $_HANDLE$ /s $SAPSERVER$ /t $SAPTYPE$ 
    

    appear to the executable as:

     
    /h 1275366 /s “Houston, TX” /t 43 
    

    The Microsoft Windows handle associated with the application is a supported internal parameter defined as $_HANDLE$.

    All internal parameters use $_ as a preface to avoid naming conflicts. Implementer parameters are not allowed to use underscores in key names.

    In addition to the Windows handle, the following internal parameters are supported to manage user credentials:
    • Username ($_USERNAME$)
    • Password ($_PASSWORD$)
    • Custom1 ($_CUSTOM1$)
    • Custom2 ($_CUSTOM2$)
    • Old Password ($_OLDPASSWORD$)

    Substitution precedence is defined to preserve parameter values after they are written. The precedence is defined as internal parameters, followed by implementer parameters, followed by environmental variables.

    All implementer parameters are permitted to use lowercase and uppercase letters and numbers in key names. Key names are case-insensitive.

    If the extension identification executable requires parameters to be presented in a specific sequence, the Argument must support the required sequence. The parameter name/value pairs defined in the Action configuration panel can be in any sequence.

Implementer Requirements

The external process that performs advanced matching or credential management actions is defined as any process or application that can be initiated using a command-line interface. Any required or optional arguments for identification extensions or action extensions must also be able to be specified in-line using a command-line interface.

For action extensions, the implementer must support the same features as previously described for the Windows detection implementation. The Username, Password, Custom1, Custom2, and Old Password credentials can be passed to the executable.

For identification extensions and action extensions, the implementer is responsible for:
  • Deploying all executable, support modules and files to support the extension on the Single Sign-on Plug-in.
  • Maintaining all deployed modules.
  • Adding all the specified registry entries on the plug-in.
  • Maintaining extension name uniqueness in their domains.

The recommended extension naming schema is a reverse domain naming schema (that is, com.citrix.cpm.ext4).

Enabling Logging

To activate debug tracing for the Single Sign-on Plug-in, a registry modification must be made.

The registry key name and its associated keys are located at:

[HKEY_LOCAL_MACHINE\SOFTWARE\Citrix\MetaFrame Password Manager\Log]

The following table defines the key value characteristics.

Key Type Value
Enabled REG_DWORD

Default value is 0.

0—disabled.

1—enabled.

Filter REG_DWORD

Bitmask that dictates what is to be logged.

0x00000001—Windows application flag used to log identification extension errors.

0x00000004—Windows password filling used to log action extension errors.

MaxSizeInBytes REG_DWORD Maximum size of the log file in bytes. Maximum theoretical value can be 4GB (2^32). Default—819200

Log file data is recorded in an sso_<username>.log file in:

 
%LocalAppData%\Citrix\MetaFrame Password Manager