Command Execution Authenticator

Providing Replication Credentials with the AMPS Exec Authenticator Module

AMPS includes a module that can provide credentials for outgoing replication connections using the results of an external process. This is designed for cases where a site has an authentication system that requires short-lived tokens, and where the installation does not use Kerberos, so the multimechanism authentication module cannot be used.

In this release, the exec authenticator module is provided with AMPS, but is not loaded by default. This module is an optional extension to the AMPS product, and while it is included with the AMPS distribution, the module must be explicitly loaded, enabled, and configured.

This module runs an external application with the credentials of the AMPS server itself. Avoid using this module unless you fully trust the application, have verified that the command line provided is correct and cannot use another module (or a custom module) for authentication.

When to Use the Exec Authenticator Module

60East recommends using this module when a replication connection is authenticated, when a system other than Kerberos is in use, when the credentials to be used cannot be provided in the configuration file or stored in the filesystem and when an executable program or script is available that can produce the credentials to use for a replication connection.

• If the credentials can be provided in the configuration file or stored in a file in the file system, use the amps-default-authenticator-module.

• If Kerberos is in use, use the Multimethod Authenticator.

Configuring AMPS to use the Exec Authenticator Module

The exec authenticator module is included in the AMPS distribution but is not loaded in AMPS by default. To load the module, add the following configuration item to the Modules block in your AMPS configuration:

<Modules>
    ...

    <Module>
        <Name>exec-authenticator</Name>
        <Library>libamps_exec_authenticator.so</Library>
    </Module>

    ...
</Modules>

This module does not require any options as a part of the module configuration and ignores any options provided when the module is loaded.

This module supports the following options when used in an Authenticator block:

Option	Description
Command	Sets the command to run. This can be either an absolute path or a relative path based on the current working directory of the AMPS server process. The command supports the following expansions when the command runs: AMPS_USER_NAME The user name that the authenticator will provide to the remote server. For example, the following Command runs the script give_me_a_token.sh from the path /opt/site/gateways/, passing the user name as a parameter: <Command>/opt/site/gateways/give_me_a_token.sh "{{AMPS_USER_NAME}}"</Command> The authenticator will read the stdout of that command and provide the result as the authentication token for the connection. There is no default for this parameter.
MaxLength	Sets the maximum number of bytes to read from the command. Default: 1024
UserName	Sets the user name to provide on this connection. There is no default for this parameter.

The module must be configured with a Command and UserName. Otherwise, the module fails to initialize and AMPS will halt the startup process.

For example, the following configuration loads and configures the module to run the auth-widget program, in the current working directory of the AMPS process, in order to provide credentials. The UserName provided to AMPS, as well as on the command line for auth-widget, is sourced from the USER environment variable used during AMPS startup. The options provided on the auth-widget command line are needed for the program to generate the token and write it to standard output.

<AMPSConfig>

    <Modules>
        ...

        <Module>
            <Name>run-proc-authenticator</Name>
            <Library>libamps_exec_authenticator.so</Library>
        </Module>

        ...
    </Modules>

    ...

    <Replication>

        ...

        <Destination>
           <Transport>

              <Type>amps-replication</Type>
              <InetAddr>my-failover-partner:4000</InetAddr>

              <Authenticator>
                   <Module>run-proc-authenticator</Module>
                   <Options>
                         <UserName>${USER}</UserName>
                         <Command>./auth-widget --user "{{AMPS_USER_NAME}}" --output=stdout</Command>
                   </Options>
              </Authenticator>

            </Transport>
        </Destination>
     </Replication>

</AMPSConfig>