Local Authentication Realm

This topic discusses the Local Authentication security realm.


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.

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 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" ]


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. TIBCO strongly recommends 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.