Default Security Configuration

When a node is installed without realm configuration settings:

  • The node creates a default realm of type LocalAuthenticationRealm with realm name default-realm.

  • The default realm has two security roles defined: administrator and monitor (plus a deprecated role, switchadmin, which is a legacy name for the administrator role).

  • This realm always contains at least one user, which has the same name as the system user who installed the node.

  • That username is configured to belong to the administrator role so that it can execute all epadmin commands.

  • If no password is provided on the epadmin node install command line, the user's password is randomly generated. This random password is not known and is not knowable; it does not need to be known as long as administration commands are issued from a trusted host.

  • With a randomly generated password, the default username can only be used from a trusted host.

  • Localhost is always trusted, even in the absence of an explicit trusted host configuration.

The combination of the above set of defaults is what allows you to install and start nodes on a development machine with no security configuration files.

The following alternatives increase security, still without requiring configuration files:

  • Provide a specific username and password on the node install command line, and the node adds that user and password to the default realm.

  • Change the default random password with the epadmin change password command.

You can increase basic security of the default realm by providing the node with one or more of the following configuration files:

  • A TrustedHosts configuration allows you to specify a list of trusted machines or addresses from which to administer the node.

  • A security configuration with root object LocalAuthenticationRealm allows you to specify one or more initial usernames, giving them membership in the built-in role administrator.

  • To grant usernames membership in additional, non-default roles, you must include a security configuration with root object RoleToPrivilegeMappings that defines the privileges granted to additional roles.

If necessary, you can restore the initial security characteristics of a node with the following command:

epadmin reset authentication --installpath=path/to/node/directory

The operating system user running this command must have write privileges on the specified node directory.

If you do not specify a new password (the default), the command prompts for one.


Caution 1

All password-oriented realms other than the built-in realm named default-realm require passwords even if the client is from a trusted address. Be aware that if you use the default realm, you are thereby trusting all client software running on trusted addresses.

To require passwords on the default realm, you must load and activate a new configuration with the requirePassword property set to true.

Caution 2

It is possible to delete the default realm, but do so with caution. For example, you can use epadmin setadmin realm to switch to a different realm for node administration authentication (as long as no other engine listener is referencing the realm).

However, if you change the node admin authentication realm, and the new realm does not have a user with the same name as that of the system user who installed the node, then all epadmin commands thereafter must specify a user with administrator privileges along with a password. Further, if the new realm is (for example) an LDAP realm and its LDAP servers are for any reason not available, you will be unable to manage the node until one of the realm's LDAP servers are again available.

Caution 3

The default admin authentication realm does not require passwords for requests coming from trusted client addresses. If you were to leave this default password in place but then modify the default realm configuration so that a password is always required, you would be immediately locked out after the update.

This is because subsequent commands would require a password that, being randomly generated, you would not know. To prevent this problem, the default realm cannot be modified. Attempts to activate a new version of the default realm configuration fail with a validation error.