Contents
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:
administratorandmonitor(plus a deprecated role,switchadmin, which is a legacy name for theadministratorrole). -
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
administratorrole 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
--passwordwith 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.
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.
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
nameproperty set to any name other thandefault-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/configurationsfolder 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.
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.
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.