You define realms in HOCON configuration files of type com.tibco.ep.configuration.dtm.security.
When you install a node with epadmin install node, its configuration files are loaded and activated. You can also load and activate a realm configuration with the epadmin load configuration and activate configuration commands, which creates the realm. Deactivating the realm configuration with epadmin deactivate configuration removes the realm. You can change the current configuration by loading and activating a new version of the configuration.
StreamBase supports live update of realms; that is, you can load and activate a new version of a realm configuration file. When so activated, all authentication and authorization using that realm automatically begins using the new version without requiring an engine restart (except for encrypted data, which does require engine restart).
Each realm has a unique name. Attempts to activate a configuration of a different realm type but with the same name as an existing realm fails. By contrast, if you activate a configuration of the same realm type and same name as an existing one, you are updating that realm.
Realms are referenced by the StreamBase and LiveView API listener configurations that use them, and by the node administration engine. Attempts to deactivate the configuration of a realm that is referenced fail.
A node can have any number of active realm configurations, with the exception of Kerberos realms.
The epadmin command line tool provides several commands for general realm management:
- epadmin display realm
-
Displays one or more realms, their types, and the configurations that reference them.
- epadmin setadmin realm
-
Sets the realm to be used for node administration.
- epadmin getadmin realm
-
Retrieve the realm used for node administration.
- epadmin display realm, epadmin display user, epadmin display configuration, epadmin display trusted
-
Displays several types of security-related information.
Caution
The setadmin realm command is used to change the realm used to authenticate node administrators. If you change the admin realm to one where no user has admin privileges, or where the realm requires passwords even from trusted clients and you do not know that password, then you will be locked out.
To prevent this problem, the setadmin realm command authenticates a user in the new realm as well as the current one, and fails if the user does not exist, cannot be authenticated, or can be authenticated but lacks privileges to load and activate configurations and update users.
By default, the current system username is used to authenticate in the new realm without a password. If the new realm requires passwords even from trusted clients, then specify the --newrealmpassword parameter.
If you prefer to not show the password on the command line, you can instead specify --promptforpassword=true.