Default Security Configuration

< Previous		Next >

Default Local Realm Settings

When a node is installed, it has the following default security settings:

The node uses 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 install node 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.

Note

Use the global parameter --password with install node. There is no command parameter of that name.
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.

Adding Security to the Default Realm

The following alternatives increase security of the default realm without requiring a replacement configuration file:

Change the default random password of the default user with the epadmin change password command.
Provide a specific username and password on the install node command line, using global parameters for those entries. The node adds that user and password to the default realm in addition to the default username.

You can increase basic security of the default realm by adding one or more of the following configuration files to the default settings:

A TrustedHosts configuration allows you to specify a list of trusted machines or addresses from which to administer the node.
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.
Prepare to replace the default configuration by adding an alternate security configuration with root object LocalAuthenticationRealm, which allows you to specify a number of initial usernames, giving them membership in the built-in role administrator. Replacing the default realm is described next.

Replacing the Default Realm

To protect the integrity of the default realm, you:

Cannot install a node with a LocalAuthenticationRealm configuration named default-realm.
Cannot use epadmin activate configuration to activate an uploaded LocalAuthenticationRealm configuration named default-realm.

To use a Local Authentication Realm with different characteristics, you must upload and activate a LocalAuthenticationRealm configuration for an alternate realm, then set that alternate as the primary administrative realm. Follow these steps:

Create a configuration file of type security with the LocalAuthenticationRealm root object, and the name property set to any name other than default-realm. See an example configuration in Number of Login Attempts Feature. See caution 3 below when designing your alternate configuration.
For nodes not yet running, include this alternate configuration file in the src/main/configurations folder of your Studio project. In this case, it is uploaded and activated at install node time.
For an already running node, use epadmin upload configuration followed by epadmin activate configuration for your alternate LocalAuthenticationRealm configuration file.
With the node running, use epadmin setadmin realm to switch to using the alternate configuration as the node's primary local authentication realm.

Tip

For the setadmin realm command to succeed, you must re-specify the default username 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. Use encryption to prevent this password from disclosure in an export configuration command.

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

Restoring the Default Realm

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

epadmin reset authentication --installpath=path/to/node/directory \
        --password=new-password

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.

Cautions

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. See Replacing the Default Realm.

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 local authentication realm does not require passwords for requests coming from trusted client addresses. If you activate your own alternate local authentication realm configuration (where the default for requirePasswords is true), but you leave this default password in place, you would be immediately locked out after the update.

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

Be sure to change the default-assigned password with epadmin change password before activating a new LocalAuthReam configuration, as described in Replacing the Default Realm.