Multimethod Authentication Module

AMPS includes a module that supports the commonly used infrastructure for enterprise authentication. In this release, the module includes support for LDAP or Kerberos authentication.

In this release, the multimechanism authentication 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 provides authentication, but does not provide an entitlement mechanism. When planning a strategy for securing AMPS using this module, you will also need to plan a strategy to manage entitlements.

When to Use the Multimechanism Authentication Module

60East recommends using this module when integrating AMPS authentication into an existing infrastructure. If your environment does not have an existing infrastructure that offers one of the authentication methods supported by this module, it is typically easier to use the HTTP authentication and entitlement module than it is to implement or deploy a new authentication system.

The AMPS Multimechanism authentication module can be a good option when:

• The site has an existing authentication infrastructure for users that need to be authenticated to AMPS, and that infrastructure supports authentication using:

  • Kerberos, or

  • LDAP

• The authentication infrastructure is relatively stable and well-supported, with support for adding AMPS to the set of applications that use this infrastructure.

Setting Authentication Mechanisms

To enable a particular authentication mechanism in the multimechanism authentication module, you simply provide configuration parameters for that mechanism.

For example, if you provide configuration parameters for an LDAP server, the module will enable LDAP. If you provide configuration parameters for Kerberos, the module will enable Kerberos.

When more than one authentication mechanism is enabled, the module will attempt to detect the authentication mechanism used for a given logon request based on the credentials provided. If the module cannot determine the mechanism to use for a given request, and there is more than one mechanism configured, the module defaults to the mechanism specified in the DefaultAuthenticationMechanism in the module options.

Notice, however, that the module does not allow a mechanism that accepts arbitrary passwords (in this release, LDAP) to be configured with a mechanism that accepts passwords of a specific format (in this release, Kerberos). In this release, the practical result is that a given module can be configured to use Kerberos or LDAP for authentication, but cannot be configured to use both.

Configuring AMPS to use the Multimechanism Authentication Module

The multimechanism authentication 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>multimech-authentication</Name>
        <Library>libamps_multi_authentication.so</Library>
    </Module>

    ...
</Modules>

This module does not require any options as 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 Authentication block:

Kerberos Options

Option	Description
Kerberos.Keytab	Sets a keytab file to use for Kerberos authentication. This option must be set to the path of the file, which can be either an absolute path or a relative path based on the current working directory of the AMPS server process. When this option is specified, the module will provide Kerberos authentication and a Kerberos.SPN must be specified. There is no default for this parameter.
Kerberos.SPN	Sets the Service Principal Name (SPN) to use for Kerberos authentication. When this option is specified, the module will provide Kerberos authentication and a Kerberos.Keytab must be specified. There is no default for this parameter.

LDAP Options

Option	Description
LDAP.Host	Sets the host name to use for LDAP authentication. When this option is specified, the module will provide LDAP authentication. This parameter is required if any other LDAP parameter is specified. There is no default for this parameter.
LDAP.Port	Sets the port number to use for LDAP authentication. When this option is specified, the module will provide LDAP authentication and an LDAP.Host must also be specified. Default: 389
LDAP.ProtocolVersion	Sets the version of the LDAP protocol to use. When this option is specified, the module will provide LDAP authentication and an LDAP.Host must also be specified. Default: 2
LDAP.BaseDN	Sets the base Distinguished Name (DN) to use for LDAP authentication. When this option is specified, the module will provide LDAP authentication and an LDAP.Host must also be specified. This parameter defaults to an empty string.
LDAP.ServiceAccountDN	Sets the Distinguished Name (DN) for the service account to use for LDAP authentication. When this option is specified, the module will provide LDAP authentication and an LDAP.Host must also be specified. This parameter defaults to an empty string.
LDAP.ServiceAccountPasswordFile	Sets a file from which to read the password for the service account to use for LDAP authentication. When this option is specified, the module will provide LDAP authentication and an LDAP.Host must also be specified. This parameter defaults to an empty string, which specifies that no password will be provided.

General Options

Option	Description
AllowAnonymous	When set to enabled, allows users to logon without providing a password. In this case, however, the authenticated username will be set to an empty string. Default: disabled
DefaultAuthenticationMechanism	When provided, sets the authentication mechanism to use if AMPS cannot identify the type of authentication token provided by the connection. In this release, the value for this parameter can be either Kerberos or LDAP. There is no default for this option. If no DefaultAuthenticationMechanism is configured and AMPS cannot identify the type of authentication token provided by a connection, AMPS reports an error for that logon.

The module must be configured with at least one authentication method. Otherwise, the module fails to initialize and AMPS will halt the startup process.

For example, the following configuration loads the module and configures the module to use LDAP authentication by contacting the server myenterprise-auth-server on port 9389. In this case, the LDAP server does not require authentication. Otherwise, the configuration would provide the service account DN and password for the server.

<AMPSConfig>

    <Modules>
        ...

        <Module>
            <Name>multi-auth</Name>
            <Library>libamps_multi_authentication.so</Library>
        </Module>

        ...
    </Modules>

    <Authentication>
        <Module>multi-auth</Module>
        <Options>
           <LDAP.Host>myenterprise-auth-server</LDAP.Host>
           <LDAP.Port>9389</LDAP.Port>
        </Options>
    </Authentication>


    <!-- The Admin module uses the LDAP server configured above for
         authentication. -->
    <Admin>
        <InetAddr>localhost:8085</InetAddr>
    </Admin>

    <!-- Both of these transports use the LDAP server configured above
         for authentication. -->
    <Transports>
        <Transport>
            <Name>json-tcp</Name>
            <Type>tcp</Type>
            <InetAddr>9007</InetAddr>
            <MessageType>json</MessageType>
            <Protocol>amps</Protocol>
        </Transport>
        <Transport>
            <Name>any-tcp</Name>
            <Type>tcp</Type>
            <InetAddr>9090</InetAddr>
            <Protocol>amps</Protocol>
        </Transport>
    </Transports>

 <!-- other configuration here -->

</AMPSConfig>

The configuration below loads the module and configures the module to use Kerberos for clients that provide a Kerberos token on logon. For Kerberos, AMPS will use the SPN AMPS/host.domain.com and the keytab file at /path/to/amps.keytab.

<AMPSConfig>

    <Modules>
        ...

        <Module>
            <Name>multi-auth</Name>
            <Library>libamps_multi_authentication.so</Library>
        </Module>

        ...
    </Modules>

    <Authentication>
        <Module>multi-auth</Module>
        <Options>
            <Kerberos.SPN>AMPS/host.domain.com</Kerberos.SPN>
            <Kerberos.Keytab>/path/to/amps.keytab</Kerberos.Keytab>
       </Options>
    </Authentication>


    <!-- The Admin module uses the Kerberos configuration
         above for authentication. -->
    <Admin>
        <InetAddr>localhost:8085</InetAddr>
    </Admin>

    <!-- Both of these transports use the Kerberos
         configuration above for authentication. -->
    <Transports>
        <Transport>
            <Name>json-tcp</Name>
            <Type>tcp</Type>
            <InetAddr>9007</InetAddr>
            <MessageType>json</MessageType>
            <Protocol>amps</Protocol>
        </Transport>
        <Transport>
            <Name>any-tcp</Name>
            <Type>tcp</Type>
            <InetAddr>9090</InetAddr>
            <Protocol>amps</Protocol>
        </Transport>
    </Transports>

 <!-- other configuration here -->

</AMPSConfig>