Auth module configuration

The following configuration items set up and manage Liberator’s auth modules that are used to authenticate Liberator users and permission them.

For background information, see the Liberator Features and Concepts page about User authentication and permissioning.

auth-checkwrite-timeout

auth-checkwrite-timeout is a timeout in seconds that applies to the checking of permissions when a user (client) contributes (publishes) data to Liberator.

The auth module checks each contribution request to ensure that the attempt to create an object, or write to it, is permitted. If the auth module has to obtain this authorization from a remote service (for example a database or a remote server), it may not be able to respond to the authorization request immediately, so the module returns an AuthenticationResult.DELAYED status to the Liberator that called it. When the Liberator receives this status, it waits auth-checkwrite-timeout seconds for the final authorization supplied in a callback from the auth module. If the result isn’t received within this time, Liberator abandons the contribution and sends a failure code back to the requesting client.

Syntax: auth-checkwrite-timeout <timeout-in-seconds>

Type: float

Default value: 30.0 seconds

For more about how to implement permission checking of contributions in a custom auth module, see the checkWrite() method of the Authenticator interface in the Liberator Authentication Java API.

auth-eject-users

auth-eject-users determines Liberator’s behaviour when a user login limit is exceeded.

Liberator imposes limits on the number of users who can be logged in at any one time. This may be through the setting of max-user-limit, or the limits are more likely determined by the Liberator licence (for more about this, see the document Caplin Platform: Guide to User Licensing). auth-eject-users determines Liberator’s behaviour when a user login limit is exceeded:

  • When auth-eject-users is FALSE, Liberator rejects any further attempts to log in.

  • When auth-eject-users is TRUE, Liberator allows a new user to log in by first ejecting the oldest existing user session that matches the username and application-id of the new user. If there’s no match on username and application-id, Liberator attempts a match on username alone. If the Liberator’s in a cluster, it looks at all the Liberators in the cluster for a matching session to eject.

Also see auth-node-eject-timeout

Syntax: auth-eject-users <boolean>

Type: boolean

Default value: FALSE

auth-login-timeout

auth-login-timeout specifies the period in seconds that Liberator waits for the auth module to authenticate a user’s login attempt. If the timeout is reached, the login is denied.

  • If you implement your own auth module using the Liberator Authentication C SDK, this the period for which Liberator waits for the authentication result when the auth_new_user() function has returned the status AUTH_DELAYED.

  • If you implement your own auth module using the Liberator Authentication Java SDK, this is the period for which Liberator waits for your implementation of DelayedResultReceiver to return the authentication result when the initial return value from an authentication check was AuthenticationResult.DELAYED.

Syntax: auth-login-timeout <timeout-in-seconds>

Type: integer

Default value: 30 seconds

auth-map-timeout

auth-map-timeout specifies the period in seconds for which Liberator waits for the auth module to map an object.

  • If you implement your own auth module using the Liberator Authentication C SDK, this the period for which Liberator waits for the authentication result when the auth_map_object() function has returned the status AUTH_DELAYED.

  • If you implement your own auth module using the Liberator Authentication Java SDK, this is the period for which Liberator waits for the your implementation of DelayedResultReceiver to return the authentication result when the return value from a call to Authenticator.mapObject()was AuthenticationResult.DELAYED.

Syntax: auth-map-timeout <timeout-in-seconds>

Type: integer

Default value: 30 seconds

auth-moddir

auth-moddir specifies the directory (as an absolute or relative path) from where Liberator’s auth modules are loaded. The directory path can contain the parameters %r and %a At run time, %r is replaced by the root directory (application-root) under which Liberator runs, and %a is replaced by Liberator’s application-name.

Syntax: auth-moddir <auth-module-directory-path>

Type: string

Default value: %r/lib which, by default, translates to <Liberators-current-working-directory>/lib

Also see auth-module.

auth-module

auth-module specifies the name of the auth module to be loaded into Liberator at startup.

Syntax: auth-module <auth-module-name>

Type: string

Default value: xmlauth

Also see auth-moddir.

auth-node-eject-timeout

auth-node-eject-timeout specifies the number of seconds a Liberator waits for a response to a user session ejection request within a Liberator cluster.

When auth-eject-users is TRUE and a new login would exceed the licensed maximum number of logins within a Liberator cluster, the Liberator handling the new login request sends an eject-session request to one of the other Liberators and waits for a "user ejected" response before allowing the new login.

If no response is received within the number of seconds specified by auth-node-eject-timeout, the Liberator repeats the request. This behaviour continues until a "user ejected" response is received, or the auth-login-timeout is exceeded.

Syntax: auth-node-eject-timeout <timeout-in-seconds>

Type: float

Default value: 10.0 seconds

max-user-limit

max-user-limit specifies the maximum number of users who can log in to the Liberator.

The Liberator licence may impose stricter limits on the number of user logins allowed on the Liberator than those defined by max-user-limit. For more information, see the document Caplin Platform: Guide to User Licensing. For information about the particular user login limits set by your licence, please contact Caplin Support. You can use max-user-limit to set a limit on the number of user logins that’s less than the licence allows if desired.

The configuration item auth-eject-users determines Liberator’s behaviour when a user login limit is exceeded.

Syntax: max-user-limit <number-of-users>

Type: integer

Default value: 0 (no limit on the number of logged-in users)

max-user-ok

max-user-ok specifies the number of users at which a message is written to the event log confirming that the number of logged-in users has dropped to an acceptable level. A message is only logged if a warning about the number of users has previously been logged (see max-user-warn).

Syntax: max-user-ok <number-of-users>

Type: integer

Default value:

max-user-warn

max-user-warn specifies the number of users at which a warning is written to the event log about the number of logged-in users approaching the maximum allowed (set by max-user-limit). Once a warning has been logged, the number of users must drop below the level set by max-user-ok before a warning can be logged again.

Syntax: max-user-warn <number-of-users>

Type: integer

Default value: 0 (no warning is logged)

write-users-period

write-users-period specifies the interval in seconds at which statistics about the currently logged in users are written to the in-memory UUPP licence usage database. The statistics are first written at write-users-time, and then every write-users-period thereafter.

Syntax: write-users-period <seconds>

Type: integer

Default value: 3600 seconds (= 1 hour)

Also see the Licensing configuration item uupp-sync-time, which governs how often the in-memory UUPP licence usage database is synchronised (written) to disk.

write-users-time

write-users-time specifies the time in minutes from midnight at which statistics about the currently logged in users are first written to the in-memory UUPP licence usage database. Subsequent writes are at write-users-period intervals.

If write-users-time is greater than 1440 (24 hours), the first statistics write time is taken from the start of the week (midnight on Sunday night). For example, a value of 1460 sets the first write time to 00:20 hrs on Monday.

Syntax: write-users-time <minutes-after-midnight>

Type: integer

Default value: -1 seconds (which means write the statistics as soon as the Liberator has started up, and every write-users-period seconds thereafter)

Also see the Licensing configuration item uupp-sync-time, which governs how often the in-memory UUPP licence usage database is synchronised (written) to disk.

See also: