Users are added to a node's local authentication realm using the Add Principal dialog shown in Figure 5.5, “Add user” accessed from the Add... button.

Figure 5.5. Add user

The fields in the Add Principal dialog are:

Clicking on the Submit button will add the new user to the node after validating that the password values match.

Users can also be added using:

epadmin --servicename=<node-service-name> add user \
   --username=admin --password=supersecret --roles=administrator

All principals defined in a local authentication realm on a node can be backed up using the Export Users dialog show in Figure 5.6, “Backup local authentication realm”. This dialog is accessed from the Export... button. The realm backup can be reloaded on a node using the restore realm administration command (see the section called “realm target”).

Figure 5.6. Backup local authentication realm

The fields in the Export Users dialog are:

When the Submit button is clicked, the realm is backed up to the specified file. No sensitive information, such as passwords is visible in the exported file.

Local authentication realms can also be backed up using this command:

epadmin --servicename=<node-service-name> backup realm --name=default-realm > default-realm.backup

Local authentication realms can be restored using this command:

epadmin --servicename=<node-service-name> restore realm --name=default-realm --file=/opt/backups/default-realm.backup

Passwords are changed in a local authentication realm using the Reset Password dialog shown in Figure 5.7, “Change password” accessed from the Reset... button.

Figure 5.7. Change password

The fields in the Reset Password dialog are:

When the Submit button is clicked the password has been changed.

Passwords can also be changed using this command:

epadmin --servicename=<node-service-name> change password --realm=default-realm --username=admin

Users defined in a local authentication realm are removed from a node by selecting a principal in the Principals table as shown in Figure 5.8, “Remove user” and clicking on the Remove button.

Figure 5.8. Remove user

When the Submit button is clicked the user has been removed.

Principals can also be removed using this command:

epadmin --servicename=<node-service-name> remove user --realm=default-realm --username=admin

User defined in a local authentication realm are updated using the Update Principal dialog shown in Figure 5.9, “Update user” accessed from the Update... button.

Figure 5.9. Update user

The fields in the Update Principal dialog are:

The fields contain the current values for the user when the dialog is initially displayed. When the Submit button is clicked any changed values are updated for the user.

Users can also be updated using this command:

epadmin --servicename=<node-service-name> update user \
    --username=admin --roles=administrator

The authentication realm associated with node administration is set by default to a local authentication realm when a node is installed (see the section called “Default security”). The default node administration authentication realm cannot be changed using configuration. For example the following fails:

//
//    New configuration using an
//    authentication realm name of default-realm
//    (the default authentication realm name)
//
name = "my-local-authentication-realm"
version = "1.0.0"
type = "com.tibco.ep.dtm.configuration.security"
configuration =
{
    LocalAuthenticationRealm =
    {
        name = "default-realm"
        requirePassword = false
        initialPrincipals =
        [
            {
                userName = "guest"
                password = ""
                roles =
                [
                      "administrator"
                ]
            }
        ]
    }
}

//
//    Load configuration 
//
epadmin --servicename=A.X load configuration --source=realm.conf 
[A.X] type = com.tibco.ep.dtm.configuration.security
[A.X] name = my-local-authentication-realm
[A.X] version = 1.0.0

//
//   Activation fails because default local authentication realm
//   cannot be changed
//
epadmin --servicename=A.X activate configuration \
    --type=com.tibco.ep.dtm.configuration.security \
    --name=my-local-authentication-realm --version=1.0.0

[A.X] Audit failed: TIBCO-EP-DTM-00277: configuration (my-local-authentication-realm, com.tibco.ep.dtm.configuration.security, 1.0.0)
contains an authentication realm with name "default-realm", which already exists in
(default-realm-config, com.tibco.ep.dtm.configuration.security, 1.0.0)

However, it is possible to change the authentication realm associated with node administration to either a different local authentication realm or an LDAP authentication realm. Here are the required steps to change the node administration realm:

This example defines a single administration user named admin in a new local authentication realm and then updates node administration to use this new realm.

name = "my-local-authentication-realm"
version = "1.0.0"
type = "com.tibco.ep.dtm.configuration.security"
configuration =
{
    LocalAuthenticationRealm =
    {
        name = "my-local-authentication-realm"
        requirePassword = false
        initialPrincipals =
        [
            {
                userName = "admin"
                password = "admin"
                roles =
                [
                      "administrator"
                ]
            }
        ]
    }
}

//
//    Display the current node administration realm
//    This command is using the operating system
//    user that installed the node so no
//    user name or password is required from a trusted host
//
epadmin --servicename=A.X getadmin realm
[A.X] Realm Name = default-realm

//
//    Load the realm configuration
//
epadmin --servicename=A.X load configuration --source=realm.conf 
[A.X] type = com.tibco.ep.dtm.configuration.security
[A.X] name = my-local-authentication-realm
[A.X] version = 1.0.0

//
//    Activate the new realm configuration
//
epadmin --servicename=A.X activate configuration --type=com.tibco.ep.dtm.configuration.security \
    --name=my-local-authentication-realm --version=1.0.0

//
//   Set node administration to use this realm
//
epadmin --servicename=A.X setadmin realm --name=my-local-authentication-realm \
    --newrealmuser=admin --newrealmpassword=admin

//
//    Display the updated node administration realm
//    The new administrator user name and password must be 
//    specified since admin is not the operating system user
//    that installed the node.
//
epadmin --servicename=A.X --username=admin --password=admin getadmin realm
[A.X] Realm Name = my-local-authentication-realm

When changing the node administration realm the new realm must have at least one user defined with the administrator role to ensure that the node can be managed in the new realm. This is verified by the setadmin realm command by requiring the username and password of an administration user in the new realm.

Attempting to remove the last administration user in a local authentication realm is also prevented to ensure that a node can always by administered.

epadmin --servicename=A.X --username=admin --password=admin remove user \
    --realm=my-local-authentication-realm --username=admin
[A.X] Error: TIBCO-EP-DTM-00481: "admin" is the last remaining user in the realm and cannot be removed.

	There is no audit preventing the last administration user from being removed when using an LDAP authentication realm. If the last administration user is removed from the LDAP server, the node can no longer be accessed for management and must be forcefully removed using operating system facilities.

There are cases where administrators can unintentionally lock out all node administration users. Examples are:

There are two choices at this point:

To reset node authentication, the reset authentication command is executed on the same machine on which the node is installed. Operating system write access privileges to the node installation directory must be available to the user executing the command.

epadmin reset authentication --installpath=A.X

See the section called “authentication target” for more details.

Every administrative command is recorded in an audit log (see the section called “Logging”). For each command executed the audit log reports on: