Chapter 4. User Management

4.1. User Creation

4.1.1. Add the User for the Management Interfaces

Overview

JBoss EAP 6's management instances are secured by default as there are no user accounts available initially, (unless you have installed the platform using the graphical installer.) This is a precautionary measure designed to prevent security breaches that can arise from simple configuration errors.

HTTP communication with JBoss EAP 6 is considered to be remote access, even if the traffic originates on the localhost. Therefore, you must create at least one user in order to be able to use the management console. If you attempt to access the management console before adding a user, you will receive an error because it does not deploy until a user is created.
Follow these steps to create the initial administrative user, which can use the web-based Management Console and remote instances of the Management CLI to configure and administer JBoss EAP 6 from remote systems.

Procedure 4.1. Create the Initial Administrative User for the Remote Management Interfaces

  1. Run the add-user.sh or add-user.bat script.

    Change to the EAP_HOME/bin/ directory. Invoke the appropriate script for your operating system.
    Red Hat Enterprise Linux
    [user@host bin]$ ./add-user.sh
    Microsoft Windows Server
    C:\bin>  add-user.bat
  2. Choose to add a Management user.

    Press ENTER to select the default option a to add a Management user.
    This user is added to the ManagementRealm and is authorized to perform management operations using the web-based Management Console or command-line based Management CLI. The other choice, b, adds a user to the ApplicationRealm, and provides no particular permissions. That realm is provided for use with applications.
  3. Enter the desired username and password.

    When prompted, enter the username and password. You will be prompted to confirm the password.
  4. Enter group information.

    Add the group or groups to which the user belongs. If the user belongs to multiple groups, enter a comma-separated list. Leave it blank if you do not want the user to belong to any groups.
  5. Review the information and confirm.

    You are prompted to confirm the information. If you are satisfied, type yes.
  6. Choose whether the user represents a remote JBoss EAP 6 server instance.

    Besides administrators, the other type of user which occasionally needs to be added to JBoss EAP 6 in the ManagementRealm is a user representing another instance of JBoss EAP 6, which must be able to authenticate to join a cluster as a member. The next prompt allows you to designate your added user for this purpose. If you select yes, you will be given a hashed secret value, representing the user's password, which would need to be added to a different configuration file. For the purposes of this task, answer no to this question.
  7. Enter additional users.

    You can enter additional users if desired, by repeating the procedure. You can also add them at any time on a running system. Instead of choosing the default security realm, you can add users to other realms to fine-tune their authorizations.
  8. Create users non-interactively.

    You can create users non-interactively, by passing in each parameter at the command line. This approach is not recommended on shared systems, because the passwords will be visible in log and history files. The syntax for the command, using the management realm, is:
    [user@host bin]$ ./add-user.sh username password
    To use the application realm, use the -a parameter.
    [user@host bin]$ ./add-user.sh -a username password
  9. You can suppress the normal output of the add-user script by passing the --silent parameter. This applies only if the minimum parameters username and password have been specified. Error messages will still be shown.
Result

Any users you add are activated within the security realms you have specified. Users active within the ManagementRealm realm are able to manage JBoss EAP 6 from remote systems.

4.1.2. Pass Arguments to the User Management add-user Script

You can run the add-user.sh or add-user.bat command interactively or you can pass the arguments on the command line. This section describes the options available when passing command line arguments to the add-user script.
For a comprehensive list of the command line arguments available for the add-user.sh or add-user.bat command. see Section 4.1.3, “Add-user Command Arguments” .
For information on how to specify an alternate properties file and location, see Section 4.1.4, “Specify Alternate Properties Files for User Management Information” .
For examples that demonstrate how to pass arguments on the add-user.sh or add-user.bat command, see Section 4.1.5, “Add-user Script Command Line Examples” .

4.1.3. Add-user Command Arguments

The following table describes the arguments available for the add-user.sh or add-user.bat command.

Table 4.1. Add-user Command Arguments

Command Line Argument Argument Value Description
-a
N/A
This argument specifies to create a user in the application realm. If omitted, the default is to create a user in the management realm.
-dc
DOMAIN_CONFIGURATION_DIRECTORY
This argument specifies the domain configuration directory that will contain the properties files. If it is omitted, the default directory is EAP_HOME/domain/configuration/.
-sc
SERVER_CONFIGURATION_DIRECTORY
This argument specifies an alternate standalone server configuration directory that will contain the properties files. If it is omitted, the default directory is EAP_HOME/standalone/configuration/.
-up
--user-properties
USER_PROPERTIES_FILE
This argument specifies the name of the alternate user properties file. It can be an absolute path or it can be a file name used in conjunction with the -sc or -dc argument that specifies the alternate configuration directory.
-g
--group
GROUP_LIST
A comma-separated list of groups to assign to this user.
-gp
--group-properties
GROUP_PROPERTIES_FILE
This argument specifies the name of the alternate group properties file. It can be an absolute path or it can be a file name used in conjunction with the -sc or -dc argument that specifies the alternate configuration directory.
-p
--password
PASSWORD
The password of the user. The password must satisfy the following requirements:
  • It must contain at least 8 characters.
  • It must contain at least one alphabetic character.
  • It must contain at least one digit.
  • It must contain at least one non-alphanumeric symbol
-u
--user
USER_NAME
The name of the user. Only alphanumeric characters and the following symbols are valid: ,./=@\.
-r
--realm
REALM_NAME
The name of the realm used to secure the management interfaces. If omitted, the default is ManagementRealm.
-s
--silent
N/A
Run the add-user script with no output to the console.
-h
--help
N/A
Display usage information for the add-user script.

4.1.4. Specify Alternate Properties Files for User Management Information

Overview

By default, user and role information created using the add-user.sh or add-user.bat script are stored in properties files located in the server configuration directory. The server configuration information is stored in the EAP_HOME/standalone/configuration/ directory and the domain configuration information is stored in the EAP_HOME/domain/configuration/ directory. This topic describes how to override the default file names and locations.

Procedure 4.2. Specify Alternate Properties Files

    • To specify an alternate directory for the server configuration, use the -sc argument. This argument specifies an alternate directory that will contain the server configuration properties files.
    • To specify an alternate directory for the domain configuration, use the -dc argument. This argument specifies an alternate directory that will contain the domain configuration properties files.
    • To specify an alternate user configuration properties file, use the -up or --user-properties argument. It can be an absolute path or it can be a file name used in conjunction with the -sc or -dc argument that specifies the alternate configuration directory.
    • To specify an alternate group configuration properties file, use the -gp or --group-properties argument. It can be an absolute path or it can be a file name used in conjunction with the -sc or -dc argument that specifies the alternate configuration directory.

Note

The add-user command is intended to operate on existing properties files. Any alternate properties files specified in command line arguments must exist or you will see the following error:
JBAS015234: No appusers.properties files found
For more information about command arguments, see Section 4.1.3, “Add-user Command Arguments” .
For examples of the add-user commands, see Section 4.1.5, “Add-user Script Command Line Examples” .

4.1.5. Add-user Script Command Line Examples

The following examples demonstrate how to pass arguments on the add-user.sh or add-user.bat command. Unless noted, these commands assume the configuration of a standalone server.

Example 4.1. Create a user belonging to a single group using the default properties files.

EAP_HOME/bin/add-user.sh -a -u 'appuser1' -p 'password1!' -g 'guest'
The above command produces the following results.
  • The user appuser1 is added to the following default properties files that store user information.
    EAP_HOME/standalone/configuration/application-users.properties
    EAP_HOME/domain/configuration/application-users.properties
  • The user appuser1 with group guest is added to the default properties files that store group information.
    EAP_HOME/standalone/configuration/application-roles.properties
    EAP_HOME/domain/configuration/application-roles.properties

Example 4.2. Create a user belonging to multiple groups using the default properties files.

EAP_HOME/bin/add-user.sh -a -u 'appuser1' -p 'password1!' -g 'guest,app1group,app2group'
The above command produces the following results.
  • The user appuser1 is added to the following default properties files that store user information.
    EAP_HOME/standalone/configuration/application-users.properties
    EAP_HOME/domain/configuration/application-users.properties
  • The user appuser1 with groups guest, app1group, and app2group is added to the default properties files that store group information.
    EAP_HOME/standalone/configuration/application-roles.properties
    EAP_HOME/domain/configuration/application-roles.properties

Example 4.3. Create a user with admin privileges in the default realm using the default properties files.

EAP_HOME/bin/add-user.sh -u 'adminuser1' -p 'password1!' -g 'admin'
The above command produces the following results.
  • The user adminuser1 is added to the following default properties files that store user information.
    EAP_HOME/standalone/configuration/mgmt-users.properties
    EAP_HOME/domain/configuration/mgmt-users.properties
  • The user adminuser1 with group admin is added to the default properties files that store group information.
    EAP_HOME/standalone/configuration/mgmt-groups.properties
    EAP_HOME/domain/configuration/mgmt-groups.properties

Example 4.4. Create a user belonging to single group using alternate properties files to store the information.

EAP_HOME/bin/add-user.sh -a -u appuser1 -p password1! -g app1group -sc /home/someusername/userconfigs/ -up appusers.properties -gp appgroups.properties 
The above command produces the following results.
  • The user appuser1 is added to the following properties file and that file is now the default file to store user information.
    /home/someusername/userconfigs/appusers.properties
  • The user appuser1 with group app1group is added to the following properties file and that file is now the default file to store group information.
    /home/someusername/userconfigs/appgroups.properties