33. Auxiliary Modules

The AMPS distribution provides several modules that extend AMPS with optional behavior. These modules are not loaded by default.

In this release, AMPS includes auxiliary modules that provide the following functionality:

• User-defined functions

  AMPS includes the libamps_udf_legacy_compatibility module that provides date and time handling functions similar to those provided by legacy messaging systems.

• SOW Key generation

  AMPS includes the libamps_id_chaining_generator module that provides chained SOW key generation.

• Authentication and Entitlement

  AMPS includes several modules to help you implement an authentication and entitlement system.

  • The libamps_http_entitlement module makes requests to an external web service to validate authentication credentials and retrieve the set of applicable entitlements. With this module, you can provide both authentication and entitlement infrastructure.
  • The libamps_multi_authentication module supports multi-mechanism authentication. In this release, the module supports both LDAP and Kerberos. This module does not provide an entitlements implementation.
  • The libamps_simple_access_entitlement module restricts access to specific resources. This module is most often used to provide limited access to the AMPS Admin console. This module does not provide an authentication implementation, and does not consider individual user entitlements – the restrictions applied by this module apply to all users.

• Authenticator

  AMPS includes a module, libamps_multi_authenticator, to provide credentials for outgoing replication connections. Notice that the default authenticator module, which is automatically loaded, can also be configured to provide credentials.

The auxiliary modules are described in more detail the following sections.

Legacy Messaging Compatibility Functions

The AMPS distribution includes a library of legacy messaging compatibility functions. These functions are intended to ease migration to AMPS from legacy messaging systems that provide similar functions.

In this release, the legacy messaging functions provide functions to make it easy to work with date and time.

These functions are not loaded into AMPS by default. To enable them, you must load the legacy messaging compatibility module by adding a directive to the AMPS configuration file to load these functions. Once the module is loaded, the functions become available. No further configuration is required.

For example, adding the indicated block to an AMPS configuration file loads the legacy messaging compatibility functions:

<AMPSConfig>
    ...

   <Modules>
        ...

        <Module>
            <Library>libamps_udf_legacy_compatibility.so</Library>
            <Name>compatibility-functions-module</Name>
        </Module>

    </Modules>
</AMPSConfig>

Function	Parameters	Description
TIMEZONEOFFSET		Returns a long that contains the current timezone offset from UTC, represented in seconds.
YEAR	timestamp	Returns the year for the provided timestamp. The year is calculated in the UTC timezone. For example, calling YEAR on a timestamp that represents January 25, 2010 at 10:04 AM in the UTC timezone returns 2010.
MONTH	timestamp	Returns the month for the provided timestamp. The month is calculated in the UTC timezone. For example, calling MONTH on a timestamp that represents January 25, 2010 at 10:04 AM in UTC returns 1.
DAY	timestamp	Returns the day for the provided timestamp. The day is calculated in the UTC timezone. For example, calling DAY on a timestamp that represents January 25, 2010 at 10:04 AM in UTC returns 25.
DATE_UTC	timestamp	Returns a timestamp for the beginning of the provided day (00:00:00) in UTC. The timestamp is represented in seconds.
DATE	timestamp	Returns the UNIX timestamp for the beginning of the provided day (00:00:00) in the local timezone. The timestamp is represented in seconds.
TODAY_UTC		Returns the UNIX timestamp for the beginning of the current day (00:00:00) in UTC – that is, the local timestamp that corresponds to the UTC time for the start of the current day. The timestamp is represented in seconds.
TODAY		Returns the UNIX timestamp for the beginning of the current day (00:00:00) in the local timezone. The timestamp is represented in seconds.

Table 33.1: AMPS Legacy Messaging Compatibility Functions

Key Generation for Chained Messages

The AMPS distribution includes a module that can generate a SOW key for a set of chained messages.

Message chains are most frequently used in FIX order processing systems to track a set of updates to an original order from a set of systems that use unique local identifiers for the order. As messages arrive, AMPS must update the record for the original order, regardless of whether the identifier on the current message is the original order, or is an order chained to the original order.

A message chain allows an application to treat any update to an identifier in the chain as an update to the original message in the chain. The libamps_id_chaining_key_generator module supports this by generating the same SOW key for any message in the chain. To use this module, messages must have a field that identifies the current message and a field that identifies the previous message in the message chain, if one exists.

Chained Message Example

For example, consider a message processing scheme that uses two fields to identify related messages. Each message a DocumentNumber field that indicates the current document. If the message updates or extends an existing document, the message contains a ParentDocument that, when present, refers to the DocumentNumber of the document that the message updates or extends.

With the default SOW key generator, each of the following messages would be a distinct message in the SOW topic:

delta_publish: {"DocumentNumber":1, "Status":"Started"}
delta_publish: {"DocumentNumber":2, "ParentDocument":1, "Order":"Antivenom"}
delta_publish: {"DocumentNumber":3, "ParentDocument":2, "Order":"Sandwich"}
delta_publish: {"DocumentNumber":4, "ParentDocument":1, "Status":"Pending"}

With the default SOW key generator, at the end of the publishing process, the SOW contains four distinct records:

{"DocumentNumber":1, "Status":"Started"}
{"DocumentNumber":2, "ParentDocument":1, "Order":"Antivenom"}
{"DocumentNumber":3, "ParentDocument":2, "Order":"Sandwich"}
{"DocumentNumber":4, "ParentDocument":1, "Status":"Pending"}

However, with the chaining key generator, AMPS is able to combine these messages into a single chain and produces the following single record:

{"DocumentNumber":4, "ParentDocument":1 , "Order":"Sandwich", "Status":"Pending"}

The sequence of events for producing this message is as follows:

• When the first message arrives with a /DocumentNumber of 1, the module begins a new chain (since there is no /ParentDocument present).
• When the second message arrives, the module knows that it is an update to the same message since the message contains a /ParentDocument value. In this case, because the value is 1, the update is to the first message received. The module also adds a /DocumentNumber of 2 to the chain, so that subsequent messages that refer to a /ParentDocument of 2 are a part of the chain and update the same message.
• The same process occurs for the third message: the module looks up the message that should be updated when the /ParentDocument is 2, and traces the chain back to the original underlying message. The module adds a /DocumentNumber of 3 to the chain, so that updates with a /ParentDocument of 3will update the same message.
• When the last message arrives, the module knows that a /ParentDocument of 1 is still an update to the same message, since this is the original value. The module adds the value 4 to the chain.

In each case, rather than simply using the fields in the message directly, the module creates a chain of linked identifiers: each identifier in the chain produces the same SOW key as the first identifier in the chain, so each update in the chain updates the same message.

It is an error for a publisher to publish a message that resolves to two different message chains. If the module receives such a message, the module will not generate a SOW key, and the message is not processed by AMPS.

Configuring the Chaining Key Generator

To load the module in AMPS, add the highlighted Module directive in the Modules section of the AMPS configuration file.

<AMPSConfig>
    ...

    <Modules>
         ...

        <Module>
            <Library>libamps_id_chaining_key_generator.so</Library>
            <Name>key-chaining</Name>
        </Module>
   </Modules>
</AMPSConfig>

You then use the module as the KeyGenerator for each topic in the SOW that will use chaining key generation.

The module accepts the following options:

Parameter	Description
Key	A field to use in chaining. AMPS supports any number of Key fields. The first Key field specified in the configuration is the primary field to use in chaining. When the primary field is present on a message, and the value of the field is not in an existing chain of values, the module creates a new chain. When the message contains the primary field and there is no previous entry for the value of that field, this message is the head of the chain and is used to generate the SOW key. Key parameters specified after the first Key are secondary fields. When a secondary field is present on the message, the module generates a SOW key for this message as though the message contained a a primary field with this value. In addition, the module stores the value of the primary field in the current, if any, message as equivalent to this value, enabling subsequent messages to be chained to this message. There is no default for this parameter. The parameter requires an AMPS field identifier, such as /11 or /Order/ClOrdID. The module requires a primary field and at least one secondary field to be defined.
FileName	Sets the name of the file that the module uses to store chaining data. This module persists existing chains between restarts of the AMPS server. If a file with the given name exists when AMPS starts, the module reads chaining data from the file. Otherwise, the module creates a new file.
Primary	A synonym for Key that explicitly specifies that this field is the primary field. When this configuration element is present, AMPS uses the field specified in this element as the primary *primary field, and considers any field specified in a Key element to be a secondary field.
Secondary	A synonym for Key that explicitly specifies that this field is a secondary field.
Validation	Specifies whether the module validates that incoming messages are properly chained. When set to true or 1, the module records extra data to attempt to detect errors in the sequencing of the chain. The module will consider it an error when it detects that two or more distinct chains share identifiers and would been combined into a single chain had messages arrived in a different order: in some systems, this indicates an error in message processing. Default: This option defaults to false.

Table 33.2: Parameters for Chaining Key Generator

Example

The example configuration file below shows one way to use the chaining key generator module.

<Modules>
   ...

    <Module>
        <Library>libamps_id_chaining_key_generator.so</Library>
        <Name>key-chaining</Name>
    </Module>
</Modules>

<SOW>
    ...

    <Topic>
        <Name>Orders</Name>
        <MessageType>json</MessageType>
        <KeyGenerator>
            <Module>key-chaining</Module>
            <Options>
                <Primary>/DocumentNumber</Primary>
                <Key>/ParentDocument</Key>
                <Key>/RelatedDocument</Key>
                <FileName>./sow/Orders.chain</FileName>
            </Options>
        </KeyGenerator>
        <FileName>./sow/%n.sow</FileName>
    </Topic>

    <Topic>
        <Name>ExternalOrders</Name>
        <MessageType>fix</MessageType>
        <KeyGenerator>
            <Module>key-chaining</Module>
            <Options>
                <!-- /11 is the primary field -->
                <Key>/11</Key>
                <Key>/41</Key>
                <FileName>./sow/ExternalOrders.chain</FileName>
            </Options>
        </KeyGenerator>
    </Topic>
</SOW>

Notice that once the module is loaded, it can be used for any message type, and can accept different configuration values for each topic in the SOW that uses the generator.

Authentication and Entitlement using a Web Service

The AMPS distribution includes a module that provides authentication and entitlement via an external Web Service. For some installations, this module provides a convenient way to integrate with an existing authentication and entitlement infrastructure without creating an entitlement plugin.

In this release, the HTTP 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.

When using this module, AMPS requests permissions documents from an external service using http or https. The request to retrieve the permissions document includes the credentials provided with the client logon. If the request succeeds, the module considers the user to have successfully authenticated to AMPS. If the request to retrieve the permissions document fails, the module considers the user to have failed authentication. When authentication succeeds, the contents of the document returned specify the permissions that the module grants to the user.

When to Use the Web Service Module

The AMPS Web Service Authentication and Entitlement module can be a good option when:

• The site does not have an exisiting authentication and entitlements infrastructure for AMPS
• It is more feasible to develop and test a standalone web service than to develop a server plugin for AMPS
• Applications need to integrate with an existing authentication and entitlement system that offers limited Linux or C/C++ support, or
• An application that will use another authentication scheme in production needs an easy way to test changes to entitlements and entitlement scenarios that are difficult to replicate in the production system

Permissions Document Format

This section describes the format of the permissions documents used by the Web Service Authentication and Entitlement module.

All documents are in JSON format, and consist of a set of permissions. The document does not contain the user name: this is intentional, and allows systems to easily provide identical permissions for all users in a group without having to create unique documents.

The entitlement document expresses each permission as a field of a JSON document. The following is an example of a permissions document:

{
  "logon": true,
  "replication-logon" : false,
  "topic": [
            { "topic": "test",
              "read": "/priority = 1",
              "write": false },
            { "topic": ".*",
              "read": true,
              "write": true }
           ],
  "admin": [
            { "topic": "^/amps/instance/.*",
              "read": true,
              "write": false },
            { "topic": ".*",
              "read": false,
              "write": false }
             ]
}

The Web Authentication Module processes the entitlements in document order. Going through the document in order, this set of entitlements specifies the following permissions:

• This user has permission to log on to AMPS, as set by the logon field.
• This user does not have permission to make a replication connection to AMPS. A replication connection that uses these credentials will be refused.
• This user has read permissions to the topic test for messages that match the filter /priority = 1. This user does not have write permissions to the topic.
• The user has read and write permissions to every other topic in the instance without content restrictions.
• The user has read permissions to the administrative interface for information under the /amps/instance path.
• The user has no other permissions to the administrative interface.

The Web Service Authentication and Entitlement Module also allows fine-grained control of the topics that a given user is allowed to publish to via replication with the replicated-topics configuration element. The following permissions document shows sample permissions for a replication connection:

{
  "replication-logon": true,
  "logon": false,
  "replicated-topics":["^/orders/NYC/.*",
                       "/events/P1"]
}

This document specifies that the user can only log in to AMPS via replication connections. The user has permission to replicate messages to the topic /events/P1 (using an exact match) and topics that begin with /orders/NYC, as specified by the regular expression ^/orders/NYC/.*. The user has no other permissions. In particular, the user cannot log in from an AMPS client, and could not publish to or subscribe to any topics even if logon was changed to true without an explicit topic permission.

The structure of the permissions document is as follows:

Field	Value
logon	Specifies permission for an application to log on to AMPS. When this field is present, the value of the field must be a boolean true or false.
replication-logon	Controls permission for a replication connection to log on to AMPS. When this field is present, the value of this field must be a boolean true or false.
topic	Controls access to topics within AMPS. When this field is present, the value of the field must be a permission list, as described below.
admin	Controls access to the administrative interface. When this field is present, the value of the field must be a permission list, as described below.
replicated-topics	An array containing the topics that this user can replicate to. When this field is present, the value of the field must be an array of strings that specify topic names or regular expressions. For example, the following entry allows this user to replicate ONLY to topics that begin with /orders/NYC "replicated-topics":["^/orders/NYC/.*"]

Table 33.3: Web Authentication Module Top-Level Permissions

Permissions lists within this document are arrays of entries. Each entry in the array is a JSON object with the following format:

Field	Value
topic	The name of the topic this permission definition applies to. This name can be either a literal value, or a regular expression to use to match topic names. A name is interpreted as a regular expression if it contains any characters used in regular expression matching (for example, ^, $, *, ., and so on). Regular expression matching provides full support for PCRE regular expressions.
read	Defines the read permission for this topic. The value of this field can be either true, false, or an AMPS filter. When the value is true, the module grants read permission to the topic with no restrictions. When the value is false, the module denies read permission. When the value is a filter, the module grants read permission to this topic only for those messages that match the filter.
write	Defines the write permission for this topic. The value of this field can be either true, false, or an AMPS filter. When the value is true, the module grants write permission to the topic with no restrictions. When the value is false, the module denies write permission. When the value is a filter, the module grants write permission for this topic only for those messages that match the filter.

Table 33.4: Permissions list entries

Configuring AMPS to use Web Service Authentication and Entitlements

The web service authentication and entitlement 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>web-entitlements</Name>
        <Library>libamps_http_entitlement.so</Library>

        <!-- You may specify options here, or where the module is used.-->

    </Module>

    ...
</Modules>

Options for the module may be set when the module is loaded, when the module is used for Authentication or Entitlement, or in both places. Options set when the module is loaded are inherited as the default values for all uses of the module in the instance. Options specified in an authentication or entitlement block override options set when the module is loaded.

For Authentication, the module supports the following options:

Option	Description
ResourceURI	The URI to request when a user logs into AMPS using this module. This option is required. For this option, AMPS substitutes the placeholder {{USER_NAME}} with the name of the user being authenticated. For example, here are two possible values for the ResourceURI: http://cred-server:8080/{{USER_NAME}}.json http://cred-server:8080/admin/group_policy.json In the first case, AMPS requests a document with the current user name of the user logging on substituted for the {{USER_NAME}} component of the URI. In the second case, the document is requested with the credentials of the user connecting, but AMPS requests the same document for each user. There is no default for this parameter.
CredentialStore	Identifier for the entitlement store where the retrieved permission sets will be stored. When used for authentication, this is the name of the entitlement cache that the module stores parsed information into until AMPS requests the information. In most cases, there is no need to set this parameter. When multiple transports use different ResourceURI values, but those transports are expected to maintain the same information, specifying a CredentialStore value can speed the logon process and reduce the number of copies of the parsed permissions document in memory. Likewise, if a module must ensure that permission sets are kept separate (so that, for example, an internal user named 'johndoe' and a web user named 'johndoe' have separate credentials), explicitly setting a CredentialStore value can make it easier to verify that the permission sets are completely separate. Default: The literal value of the ResourceURI parameter.
ConnectionTimeout	The maximum amount of time to wait for a connection to the web server for each request, in milliseconds. If a connection is not made within the specified time, the module stops the connection attempt and the request fails. Default: 2000
RequestTimeout	The maximum amount of time to wait for the web server to return a permissions document on each request, in milliseconds. If the server does not return a permissions document within the specified time, the module closes the connection and the request fails. Default: 5000
RetryCount	Sets the number of times to retry the request if retrieving the authentication document fails for any reason. Default: 0 (only try once)
HTTPHeader	Sets a header to add to the HTTP request. The configuration can specify any number of HTTPHeader elements, and the module will provide each of the specified headers with the authentication request. There is no default for this option. If no HTTPHeader option is included, the module provides a standard set of headers. This option supports variable replacement during an authentication request, as follows: AMPS substitutes the placeholder {{USER_NAME}} with the name of the user being authenticated. AMPS substitutes the placeholder {{CORRELATION_ID}} with the CorrelationId provided on the logon command. If no CorrelationId is provided on the logon command, then {{CORRELATION_ID}} is simply removed from the header before sending it.

Table 33.5: Authentication block options for Web Service Authentication Module

For Entitlement blocks, the module requires one of the following two options. These options are used to specify the entitlements to use for the context.

Option	Description
ResourceURI	Identifier for the credential store to use for this entitlement context. This is a synonym for the CredentialStore parameter. The module accepts this synonym to make it easier to verify that the Entitlement context and the Authentication context use the same values. There is no default for this parameter. Either the ResourceURI or CredentialStore must be provided. If both are provided, the module uses the value of the CredentialStore.
CredentialStore	Identifier for the entitlement cache. When used for entitlement, this is the name of the entitlement cache that AMPS uses to look up the information. There is no default for this parameter. Either the ResourceURI or CredentialStore must be provided. If both are provided, the module uses the value of the CredentialStore. When both ResourceURI and CredentialStore are specified for an Entitlement, the module uses the value set in the CredentialStore.

Table 33.6: Entitlement block options for Web Service Authentication Module

For example, the following configuration loads the module and sets default values that are used for client transports. The module is also used for the admin interface, but that interface uses a separate credential store. Notice that, since the HTTPHeader options are set when the module is loaded, the custom headers are provided everywhere the module is used, regardless of the ResourceURI or CredentialStore values.

<AMPSConfig>
    <Modules>
        ...

        <Module>
            <Name>web-entitlements</Name>
            <Library>libamps_http_entitlement.so</Library>

            <!-- Sets defaults for all uses of the module -->
            <Options>
                <ResourceURI>http://permissions-server:8080/{{USER_NAME}}.json</ResourceURI>
                <HTTPHeader>x-tracking-id: {{CORRELATION_ID}}</HTTPHeader>
                <HTTPHeader>x-origin: AMPS</HTTPHeader>
            </Options>
        </Module>

        ...
    </Modules>

    <!-- Use the web-entitlements module with the default values for all authentication and entitlement
        unless a transport or the admin interface explicitly sets different values. -->
    <Authentication>
        <Module>web-entitlements</Module>
    </Authentication>
    <Entitlement>
        <Module>web-entitlements</Module>
    </Entitlement>

    <Admin>
        <InetAddr>localhost:8085</InetAddr>
        <!-- Use the web-entitlements module, but set a different URI and credential store for the admin
            interface. -->
        <Authentication>
            <Module>web-entitlements</Module>
            <Options>
                <CredentialStore>AdminCreds</CredentialStore>
                <ResourceURI>http://permissions-server:8080/admin/{{USER_NAME}}.json</ResourceURI>
            </Options>
        </Authentication>
        <Entitlement>
            <Module>web-entitlements</Module>
            <Options>
                <ResourceURI>http://permissions-server:8080/admin/{{USER_NAME}}.json</ResourceURI>
                <CredentialStore>AdminCreds</CredentialStore>
            </Options>
        </Entitlement>
    </Admin>

    <!-- All of these transports use the Authentication and Entitlement set at the instance level. -->
    <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>
</AMPSConfig>

Using HTTPS for Entitlement Requests

The Web Service Authentication and Entitlement Module optionally supports https entitlement requests. When the ResourceURI uses https as the scheme, the module will attempt to use https to connect to the web service.

By default, the module attempts to verify the identity of the remote web service, which requires a key file containing the key for the certificate authority that signed the certificate for the remote web service.

AMPS does not require that the certificate and key provided for outgoing https requests be the same certificates used for incoming SSL connections to AMPS. However, if you have configured AMPS to accept SSL connections from AMPS clients, the certificates you use for those connections are often suitable for outgoing web authentication module connections, and the same certificates can be provided in both sections of the configuration file.

Option	Description
Certificate	The certificate to use for the AMPS connection to the web service. When configured, this certificate can be provided to the web service if the web service requests client authentication for the connection. There is no default for this parameter.
Key	The key file to use for the AMPS connection to the web service. When configured, this key can be used for client authentication if the web service requests client authentication for the connection. There is no default for this parameter.
CAKey	The certificate authority key. When configured, this key can be used for the AMPS server to verify the identity of the web service. There is no default for this parameter. The CAKey must be provided when AllowUnverfiedPeer is set to false, the default.
AllowUnverifiedPeer	Specifies whether AMPS requires the web service to identify itself. When this is set to false, the default, AMPS requires that the web service provide a certificate that can be verified with the configured CAKey. Default: false
AllowSelfSigned	Specifies whether AMPS will accept self-signed certificates for https connections. Default: false

Table 33.7: HTTPS options for Authentication

The following configuration file shows a common way to configure the module for testing purposes when working with a server that accepts https connections. While the outgoing connection will use SSL, the module will not provide certificates to the server, or request that the server verify its identity.

<Module>
    <Name>web-entitlements</Name>
    <Library>libamps_http_entitlement.so</Library>
    <Options>
        <ResourceURI>https://permissions-server:443/{{AMPS_USER}}.json</ResourceURI>
        <AllowUnverifiedPeer>true</AllowUnverifiedPeer>
        <AllowSelfSigned>true</AllowSelfSigned>
    </Options>
</Module>

The following configuration file demonstrates how to configure the module to verify the identity of the remote server, provide verification of the AMPS server identity to that server, and require that all certificates be signed by a certificate authority.

<Module>
    <Name>web-entitlements</Name>
    <Library>libamps_http_entitlement.so</Library>
    <Options>
        <ResourceURI>https://permissions-server:443/{{AMPS_USER}}.json</ResourceURI>
        <Certificate>/etc/security/amps-cert.pem</Certificate>
        <Key>/etc/security/amps-key.pem</Key>
        <CAKey>/etc/security/ca.pem</CAKey>
    </Options>
</Module>

Permissions Management and Request Flow

This section describes the request flow for the Web Service Authentication and Entitlement Module.

Notice that authentication and entitlement are two separate steps. The module obtains the set of permissions during the authentication step, and then provides responses to AMPS entitlement requests during the entitlement step. What this means is that a user must have authenticated using the module for an entitlement request to be allowed.

authentication Step

1. Logon request received from client.
2. Module requests an entitlement document (via GET) from a specified Web Service. The credentials in the logon request are provided as the credentials for the GET. The module supports both Basic and Digest authentication to the Web Service, as described in RFC 7616 (HTTP digest access authentication) and RFC 7617 (The ‘Basic’ HTTP authentication scheme).
3. If AMPS cannot retrieve the entitlement document using the provided credentials, AMPS returns a failure for the logon request.
4. If the Web Service Authentication and Entitlement module already has a parsed entitlement document for this user in the CredentialStore for this request, the module simply returns success for the authentication request.
5. Otherwise, the module parses the entitlement document and stores the entitlements in the CredentialStore. If the module can’t successfully parse the document, it returns failure for the authentication request.

Entitlement Step

1. The module looks up the user name in the CredentialStore for the request. If the module has no stored entitlements for the user, the module denies the request.
2. The module looks for a matching entitlement. Entitlements for a user are searched in exactly the same order in which they appear in the document. The module uses the first entitlement that matches the request. If no entitlements match, the module denies the request.
3. The module checks the entitlement to see if the entitlement grants access to the user or disallows access to the user. If the entitlement disallows access, the module denies the request.
4. The module allows the request and applies any filter specified in the matching entitlement.

Entitlement Reset

The module caches the set of entitlements for a user while that user is connected. As described in the previous section, the module only parses the returned permissions document if the module does not have an existing set of entitlements for that user.

In addition to the typical methods for resetting the AMPS entitlement cache, the module also provides “reset cache on disconnect” entitlement behavior. The module resets both the AMPS entitlement cache and the information on the parsed permissions document for a given user when all of the connections for that user are closed. In practical terms, this means that changing the entitlement document returned by the web service has no immediate effect on the permission set that AMPS enforces. AMPS will continue to use the permissions in the document returned from the first logon request for that user until all connections for that user have been closed.

To change the entitlements enforced for a user when the entitlements document changes, that user must completely log out of AMPS (by closing all connections for that user) and then reconnect to AMPS.

Authentication With the AMPS Multimechanism 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 mechansm 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 configuratoin 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 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 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.

Table 33.8: Kerberos options for Multimechanism Authentication

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.

Table 33.9: LDAP options for Multimechanism Authentication

General Options

Option	Description
AllowAnonymous	When set to enabled, allows users to logon without providing a password. In this case, however, the authenticated user name 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.

Table 33.10: General policy options for Multimechanism Authentication

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>

Entitlement with the Simple Access Module

The AMPS distribution includes a module that provides access to a resources that meet specific patterns. In this release, the simple access entitlement 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.

When using this module, AMPS grants and denies permissions to resources based on the name of the resource. The name of the user is not considered by this module, so when this module is used every user has the same set of permissions for the transport.

When to Use the Simple Access Module

The AMPS Simple Access module can be a good option when:

• There are specific topics for a transport that are allowed or denied, but no other restrictions on the transport.
• There is no other entitlement system in use for the installation.

Most often, the simple access module is used to allow access to the parts of the Admin console that do not modify the state of an AMPS instance, while refusing access to the parts of the Admin console that affect the instance state.

Configuring AMPS to use the Simple Access Module

The simple access entitlement 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>simple-access</Name>
        <Library>libamps_simple_access_entitlement.so</Library>

        <!-- This module does not require options when loaded. -->
    </Module>

    ...
</Modules>

Options for the module are set when module is used for Entitlement. When used in an Entitlement blocks, the module requires one or both of the following two options.

Option	Description
AllowedTopics	A regular expression that matches the topics that the module will allow access to. The module will grant access only to topics that match this regular expression that do not also match the DeniedTopics regular expression. Defaults to .*, matching all topics in the instance.
DeniedTopics	A regular expression that matches the topics that the module will deny access to. The module will grant access only to topics that do not match this regular expression. There is no default for this parameter. If not provided, the module does not consider any topics to be explicitly denied, and will grant access to any topic that matches the AllowedTopics parameter.

Table 33.11: Entitlement block options for Simple Access Entitlement Module

For example, the following configuration loads the module, uses the module for entitlements on the administrative console, and explicitly refuses access to paths beneath /amps/administrator – the paths that might modify the state of the instance. Since AllowedTopics defaults to .*, all other topics are allowed.

<AMPSConfig>
    <Modules>
        ...

        <Module>
            <Name>simple-access</Name>
            <Library>libamps_simple_access_entitlement.so</Library>
        </Module>

        ...
    </Modules>


    <Admin>
        <InetAddr>localhost:8085</InetAddr>
        <!-- Use the simple-access module to deny access to topics under
            /amps/administrator. -->
        <Entitlement>
            <Module>simple-access</Module>
            <Options>
                <!-- Deny all topics under /amps/administrator -->
                    <DeniedTopics>^/amps/administrator</DeniedTopics>

                <!-- Allowed topics defaults to .* , so no need
                    to set that explicitly. -->
            </Options>
        </Entitlement>
    </Admin>
</AMPSConfig>

Providing Replication Credentials With the AMPS Multimechanism Authenticator Module

AMPS includes a module that can provide credentials for outgoing replication connections, designed for use when the multimechanism authenticator module is in use for the destination AMPS instance.

In this release, this module can provide credentials for both LDAP and Kerberos authentication mechanisms. This module is provided with AMPS, but it 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.

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.

When to Use the Multimechanism Authenticator Module

60East recommends using this module when a replication connection is authenticated and uses the AMPS multimechanism module with Kerberos configured. This module can also be useful when LDAP is configured, however, in many environments the password capabilities of the amps-default-authenticator module can be sufficient for LDAP authentication.

Setting Authentication Mechanisms

To enable a particular authentication mechansm in the the multimechanism authenticator 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.

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 configuratoin item to the Modules block in your AMPS configuration:

<Modules>
    ...

    <Module>
        <Name>multimech-authenticator</Name>
        <Library>libamps_multi_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:

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.

Table 33.12: Kerberos options for the Multimechanism Authenticator

LDAP Options

Option	Description
LDAP.Username	Sets the user name to provide when authenticating to a destination that uses LDAP authentication. When this option is specified, the module will provide LDAP authentication. This parameter is required if the LDAP.PasswordFile parameter is specified. There is no default for this parameter.
LDAP.PasswordFile	Specifies the file name from which to read the password to provide when authenticating to a destination that uses LDAP authentication. When this option is specified, the module will provide LDAP authentication and an LDAP.Username must also be specified. Default: 389

Table 33.13: LDAP options for the Multimechanism Authenticator

The module must be configured with at least one method for providing credentials. 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 provide Kerberos tokens to the destination at my-failover-partner:4000.

<AMPSConfig>
    <Modules>
        ...

        <Module>
            <Name>multi-authenticator</Name>
            <Library>libamps_multi_authenticator.so</Library>
        </Module>

        ...
    </Modules>

    ...

    <Replication>

        ...

        <Destination>
           <Transport>

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

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

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

</AMPSConfig>