Local Authentication Realm

This topic discusses the Local Authentication security realm.

Overview

The local realm stores its user information in its node's transactional memory. A local realm configuration is specified in a LocalAuthenticationRealm root object and is part of the security configuration type.

Each user in the realm has a password, a set of roles, and an account lock status. The password has an optional expiration time in days, after which the password must be changed. The default is for passwords to never expire. If an account is locked by an administrator, access is always denied.

Passwords are one-way hashed in shared memory.

The realm configuration can specify a set of initial users. When the realm is first activated, these users are placed in the realm, allowing administrators to bulk-load users rather than creating them individually. These users can only be added in the initial version of the configuration; subsequent versions ignore the users because you can also manage the realm by command line and it is preferable to avoid colliding intentions between the initial user list and any management commands invoked earlier.

The configuration can enable secure communication client authentication, which means that if a request is transported over a secure communication connection such as TLS and that connection uses client (mutual) authentication, then no password is required. The server network listener provides the authenticated user, which is responsible for mapping the client X.509 certificate's subject DN to a user name. See Secure Transport with TLS for more information on TLS security.

The configuration can require a password even if the request originates from a trusted host, if the administrator desires extra security. This behavior effectively disables trusted hosts unless the realm is configured to require that all requests originate from a trusted host. In that case, the configuration becomes a white list with required passwords, for maximum security.

Configuration of Local Authentication Realm

The LocalAuthenticationRealm root configuration object defines the characteristics and initial principals in the local authentication realm for a node. Figure 1, “LocalAuthenticationRealm relationships” shows the relationships to other configuration objects.

Changing the failedLoginLockoutDurationMinutes or failedLoginLockoutThreshold configuration properties by activating a new version of this configuration causes this behavior:

  • increasing failedLoginLockoutThreshold: any users already locked for exceeding the old value remain locked until their durations expire or they are manually unlocked.

  • decreasing failedLoginLockoutThreshold: any users with login fail counts that did not exceed the old value remain unlocked until they fail again and then they are compared with the new value.

  • changing failedLoginLockoutThreshold from zero to non-zero (enabling lockout): behaves the same as decreasing the value.

  • changing failedLoginLockoutThreshold from non-zero to zero (disabling lockout): behaves the same as increasing the value.

  • increasing failedLoginLockoutDurationMinutes: the next login attempt will use the new duration and will unlock only when it is exceeded.

  • decreasing failedLoginLockoutDurationMinutes: the next login attempt will use the new duration and will unlock only when it is exceeded.

  • changing failedLoginLockoutDurationMinutes from non-zero to zero (disabling auto-unlock): users formerly on timed unlock will now remain locked until explicitly unlocked by an administrator.

  • changing failedLoginLockoutDurationMinutes from zero to non-zero (enabling auto-unlock): behaves the same increasing the value.

LocalAuthenticationRealm relationships

LocalAuthenticationRealm relationships

A detailed description of the configuration object properties is in LocalAuthenticationRealm object properties and a snippet for these properties is in Example 1, “LocalAuthenticationRealm object snippet”.

LocalAuthenticationRealm object properties

Name Type Description
allowSecureCommunicationClientAuthentication Boolean Automatically authenticate if user connecting over a secure communication channel. A value of true allows automatic authentication, a value of false disables automatic authentication. Optional. Default value is false.
failedLoginLockoutDurationMinutes Integer The number of minutes a user's account will remain locked after being locked for exceeding the lockout threshold. A value of 0 means the account remains locked until it is manually unlocked by an administrator (see epadmin-user(1)). Optional. Default value is 0.
failedLoginLockoutThreshold Integer The number of consecutive failed login attempts required before a user's account is locked. A value of 0 disables account locking for failed login attempts. Optional. Default value is 0.
initialPrincipals Principal [ ] Initial set of principals (see Principal) in this realm. The values in this field cannot change when this configuration is updated. If the values do change, configuration audit will fail. Optional. No default value.
name String Name of the authentication realm. This name must be unique across all authentication realms. Required.
requirePassword Boolean Require a password if user is connecting from a trusted host unless automatically authenticated because of a secure communication channel. A value of true requires a password when connecting from a trusted host, a value of false allows connection from a trusted host without a password. Optional. Default value is true.
requireTrustedHostMembership Boolean A value of true only allows users to connect from a trusted host, a value of false allows users to connect from any host. Optional. Default value is false.

Example 1. LocalAuthenticationRealm object snippet

name = "local-authentication-realm"
version = "1.0.0"
type = "com.tibco.ep.dtm.configuration.security"
configuration =
{
    LocalAuthenticationRealm =
    {
        name = "my-local-authentication-realm"
        requireTrustedHostMembership = true
        allowSecureCommunicationClientAuthentication = true
        requirePassword = false
        failedLoginLockoutDurationMinutes = 5
        failedLoginLockoutThreshold = 3
        initialPrincipals =
        [
            { ... }
            { ... }
        ]
    }
}


Account Lock Features

Local Authentication Realm user accounts can be locked and unlocked, whether or not a secure communications profile is configured for the same node. A separate realm such as LDAP or OIDC may have its own account lock and account login attempt timeout settings. The feature under discussion here applies only to Local Authentication Realms.

In a Local Authentication Realm, a user account might be locked:

  • If a node administrator has interactively locks the account.

  • If the node or the user's account was configured with password expiration, and the account is beyond the specified number of days.

  • If the node was configured to use the number of login attempts feature, and the number of attempts is exceeded.

Interactive Account Locking

To interactively lock or unlock the ability of a user to log in, an administrator can use the following commands:

epadmin --servicename=A.X update user --username=sbuser --locked=true
epadmin --servicename=A.X update user --username=sbuser --locked=false

An administrator can unlock and override an account locked automatically for password expiration or number of login attempts reasons.

Password Expiration

The default Local Authentication Realm does not enable the password expiration feature. To enable it for an alternate Local Authentication Realm, set the property passwordExpirationPeriodDays to a non-zero, positive value. For example:

passwordExpirationPeriodDays = 180

Remember that you cannot directly change any properties of the default realm, but must upload and activate its replacement, then set the new realm to be the primary authentication realm. This is described in Replacing the Default Realm.

Number of Login Attempts Feature

The number of login attempts lockout feature is disabled by default in the default Local Authentication Realm. To enable it for a an alternate Local Authentication Realm, use non-default values for the failedLoginLockoutThreshold and failedLoginLockoutDurationMinutes properties in a security configuration file with root object LocalAuthenticationRealm.

Remember that you cannot directly change any properties of the default realm, but must upload and activate its replacement, then set the new realm to be the primary authentication realm. This is described in Replacing the Default Realm.

For example, the following configuration file creates a new Local Authentication Realm named newlocalrealm that is configured to lock logins after the 5th attempt, and to force users to wait 15 minutes before attempting another login after lockout.

name = "newlocalrealm"
version = "1.0.0"
type = "com.tibco.ep.dtm.configuration.security"
configuration = {
  LocalAuthenticationRealm = {
    name = "newlocalrealm"
    allowSecureCommunicationClientAuthentication = true
    failedLoginLockoutThreshold = 5
    failedLoginLockoutDurationMinutes = 15
    requirePassword = false
    requireTrustedHostMembership = false
    initialPrincipals = [
      {
      userName = "sbuser"
      password = "sEcr3t1v3"
      passwordExpirationPeriodDays = 0
      locked = false
      roles = [ "administrator" ]
      }
    ]    
  }
}

Tip

For the setadmin realm command to succeed, you must re-specify the default user name in the initialPrincipals array of the alternate configuration. The make this practical, especially if your alternate configuration requires passwords, first change the password for the default user in the active default realm with epadmin change password. Then specify the same password in your alternate configuration file.

It is also wise to add at least one alternate user name with membership in the administrator role in the initialPrincipals array, so that you have an alternate way to issue commands if the primary user name is locked out.

Use the epadmin display user command to see the current state of a user's account. For example:

Realm Name = default-realm
User Name = sbuser
Password Expiration (Days) = 0
Account Locked = true
Lock Reason = 5 consecutive login attempts
Time Remaining Before Auto-Unlock (minutes) = 7
Failed Login Lockout Threshold = 5
Failed Login Lockout Duration (minutes) = 15
Roles = administrator, switchadmin
Authentication via Secure Communication Allowed = true
Password Always Required = false
Trusted Host Membership Required of Client = false

User Management

The epadmin user target supports user management in any local authentication realm. Provide the realm name as a command line argument; it defaults to the default realm named default-realm if not specified. See the epadmin user reference page for detailed instructions.

epadmin add user

Creates a new user. If the password is not supplied on the command line, epadmin prompts for it.

epadmin remove user

Removes an existing user.

epadmin update user

Changes the user account lock status, role set, and password expiration period.

epadmin display user

Displays users in one or more realms.

epadmin change password

Changes the user password. If the new password is not supplied on the command line, epadmin prompts for it.

Realm Management

See the epadmin realm reference page for detailed instructions on realm management. The following commands are especially important.

epadmin backup realm

Backs up the specified local realm to a local file whose path and name you provide. It is a best practice making local realm backups so that command line changes to the realm are not lost if the node is removed or corrupted.

epadmin restore realm

Restores from a backup file made with the above backup realm command. This command replaces the entire configuration of the specified realm with the contents of the backup.

epadmin getadmin realm

Retrieves the name of the local authentication currently used to administer the specified node.

epadmin setadmin realm

For a node with more than one local authentication realm activated, sets which realm is to be the primary administration realm going forward.

Principal Configuration

The Principal configuration object defines a principal managed by the local authentication realm. Figure 2, “Principal relationships” shows the relationships to other configuration objects.

Principal relationships

Principal relationships

A detailed description of the configuration object properties is in Principal object properties and a snippet for these properties is in Example 2, “Principal object snippet”.

Principal object properties

Name Type Description
locked Boolean Control whether the user account is locked. If true the user account is locked and cannot be accessed, if false the account is enabled and can be accessed. Optional. Default value is false.
password String Opaque credential. Opaque text credentials are generated using the epadmin secret target. See epadmin-secret(1). Required.
passwordExpirationPeriodDays Integer An optional expiration time for the password in days. Default value is 0 (no expiration).
roles String [ ] An array of role names. Optional. No default.
userName String Principal name. Required.

Example 2. Principal object snippet

name = "local-authentication-realm"
version = "1.0.0"
type = "com.tibco.ep.dtm.configuration.security"
configuration =
{
    LocalAuthenticationRealm =
    {
        initialPrincipals =
        [
            {
                userName = "FredTheAdministrator"
                password = "LKJALISJDOIQUWEOIAJSLKDJALSJDL"
                roles =
                [
                      "administrator"
                ]
                passwordExpirationPeriodDays = 12
                locked = true
            }
        ]
    }
}