You define realms in HOCON configuration files of type security.
Activate a realm configuration with the epadmin activate configuration command, which creates the realm. Deactivating the realm configuration with epadmin deactivate configuration removes the realm. You can change the current configuration by activating a new version.
Live update is supported; that is, you can activate a new version of a realm configuration and all authentication and authorization using that realm automatically begins using the new version without requiring an 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 security
Displays several types of security information. All types are deprecated except --type=hosts, which displays the current set of trusted hosts, and --type=accesscontrol, which displays the privileges associated with named roles.
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 prefer to not show the password on the command line, you can instead specify --promptforpassword=true.