Types of BUILTIN User Accounts

The BUILTIN provider supports two different types of user account:
  • System user accounts are visible to all members of the GemFire XD system, and have privileges to join members to the cluster and shut down cluster members. The list of valid system users is established using system properties when you boot a GemFire XD server or locator. You should use only a few system-level users in a GemFire XD deployment (for example, one system user for a standalone locator and one for GemFire XD servers).

    You create user names and passwords for system users by specifying them with the gemfirexd.user.<UserName>=<password> property in the gemfirexd.properties file. See Creating System Users and Starting GemFire XD Members.

  • Distributed system user accounts are used to establish connections to a GemFire XD cluster and to protect database resources using SQL authorization. You define distributed system user credentials by connecting to a running GemFire XD system and executing a built-in procedure. Privileges on individual database resources are then granted using SQL commands. See Creating Distributed System Users.
Note: The GemFire XD built-in authentication mechanism is suitable only for development and testing purposes. Production systems should use LDAP or a user-defined class for authentication. Production systems should also use SSL/TLS to protect network connections.

Creating System Users and Starting GemFire XD Members

System users are established at boot time, and have privileges to start GemFire XD servers and locators and join members to an existing distributed system.

Procedure
  1. Enable BUILTIN authentication and create the credentials of one or more GemFire XD system users at boot time using the gemfirexd.user.user-name system property. GemFire XD user names are SQL92 identifiers, and are case-sensitive for user authentication. Delimited identifiers are allowed. For example, the following property defines a username of "FRed" with the password "java":
    gemfirexd.auth-provider=BUILTIN
    mcast-port=0
    gemfirexd.user."FRed"=java
    As a best practice, include the property definitions for all system users in a single gemfirexd.properties file that can be used by each GemFire XD server, standalone locator, or peer client in the distributed system. For example, this listing shows a gemfirexd.properties file the defines a "locatoradmin" and "serveradmin" system user:
    gemfirexd.auth-provider=BUILTIN
    mcast-port=0
    gemfirexd.user.locatoradmin=locatorpassword
    gemfirexd.user.serveradmin=serverpassword

    If a GemFire XD member does not reference the shared gemfirexd.properties file, you must both define and specify the credentials required to join the distributed system on the command line when you start that member. See the remaining steps for an example.

    Note: The above examples use plain-text passwords. As a best practice, you should instead encrypt the password before storing it in gemfirexd.properties using the instructions in the next step.
  2. To avoid storing system user passwords in plain text in the gemfirexd.properties file, use the gfxd encrypt-password command to generate encrypted placeholder text for the password. For example:
    $ gfxd encrypt-password
    Enter User Name: locatoradmin
    Enter Password: locatorpassword
    Re-enter Password: locatorpassword
    Encrypted to v23b60584174091d1d7b3bad3728a55500915424516037
    
    Store the encrypted value in the gemfirexd.properties file in place of the plain text password for the specified user name:
    gemfirexd.user.locatoradmin=v23b60584174091d1d7b3bad3728a55500915424516037
  3. To boot a standalone locator, specify a configured system user name with the -user option. For example, to boot a locator using the example gemfirexd.properties file shown in the previous step, enter:
    $ gfxd locator start -dir=./locator -user=locatoradmin -password
    Enter Password: locatorpassword

    If you leave the -password option empty, GemFire XD prompts you for the password.

    The locator defines the built-in system users when it boots (in the above example, using the sample gemfirexd.properties file). Other GemFire XD members that join the system must specify one of the same system users that are defined for the locator. For example, a GemFire XD data store that uses the same gemfirexd.properties could join the system with the command:
    $ gfxd server start -dir=./server -client-port=1528 -user=serveradmin -password
    Enter Password: serverpassword

    If you need to change the password of a system user, you must stop all members of the distributed system, and then restart them (beginning with the locator), specifying the new username definition when you start.

  4. To boot a GemFire XD member that does not use the same gemfirexd.properties file, you must both define and specify credentials for a system user at startup. Again the BUILTIN user definition must match one of the system users that is defined for the locator. For example, to start a peer client and connect to the above distributed system you could enter:
    $ gfxd
    gfxd> connect peer 'locators=localhost[10334];host-data=false;auth-provider=BUILTIN;gemfirexd.user.serveradmin=serverpassword;user=serveradmin;password=serverpassword'
    > as peer1;
    gfxd(PEER1)>
    Note: In addition to defining the same system user with gemfirexd.user.user-name, you must also specify the credentials of the user with the user and password properties.
  5. To connect as a thin client to a distributed system using a system user account, you need only specify valid credentials with the user and password client connection properties:
    $ gfxd
    gfxd> connect client 'localhost:1527;user=serveradmin;password=serverpassword' as server1;
    gfxd(SERVER1)>
  6. To display the list of BUILTIN users that are configured in the current GemFire XD member, use the SYS.SHOW_USERS procedure. For example, if you execute the procedure from the accessor member that was started in the previous step, GemFire XD shows the single BUILTIN user that was defined in the connection string:
    gfxd(PEER1)> call sys.show_users();
    NAME                                                                   |TYPE
    ------------------------------------------------------------------------------
    SERVERADMIN                                                            |DBA
    
    1 row selected
    If you execute the procedure from the server that was started in the previous step, you would see that both BUILTIN users are defined:
    gfxd(SERVER1)> call sys.show_users();
    NAME                                                                   |TYPE
    ------------------------------------------------------------------------------
    SERVERADMIN                                                            |DBA
    LOCATORADMIN                                                           |USER
    
    2 rows selected

    The "DBA" type indicates that the user is the JVM owner for the current GemFire XD member. Both the accessor and the server were started using the SERVERADMIN credentials, so that user is the JVM owner for both members.

Note: Keep in mind that gemfirexd.user.username defines a user credential, and -user specifies the credential to use for booting a member or connecting to the distributed system. Both properties are required when you start a GemFire XD member, but as a best practice you should define all BUILTIN users in a common gemfirexd.properties file.

Changing a System User Password

Built-in system users are defined when you boot the GemFire XD locator. Other GemFire XD members that join the system must specify one of the same system users that are defined in the locator. If you need to change the password of a system user, you must stop all members of the distributed system, and then restart them (starting with the locator), specifying the new username definition when you start.

To change the password of an existing system user, either specify a new password when your start a GemFire XD member using the gemfirexd.user.UserName system property, or generate a new encrypted password using gfxd encrypt-password and place the new encrypted password in the gemfirexd.properties file.

See Creating System Users and Starting GemFire XD Members for details.

Note: Regardless of which method you use to define the new password, you must restart all GemFire XD members (including locators) using the new password. You cannot change a system password user on only a subset of the GemFire XD members. This limitation applies only to system users defined in the BUILTIN authentication schema. LDAP authentication occurs outside of the GemFire XD system, so passwords can be changed without affecting available GemFire XD members.

Creating Distributed System Users

Create user accounts to protect database resources.

To create a distributed system users, you must first connect to a GemFire XD system as a configured system user. You can then execute a system procedure to create a distributed system user account. For example:
$ gfxd
gfxd> connect peer 'locators=localhost[10334];mcast-port=0;user=serveradmin;auth-provider=BUILTIN;gemfirexd.user.serveradmin=serverpassword;password=serverpassword;
gfxd> call sys.create_user('gemfirexd.user.newuser', 'newpassword');
gfxd> disconnect;
After creating one or more distributed system user accounts, you can use those credentials, instead of a system user credential, to connect to the GemFire XD distributed system:
$ gfxd
gfxd> connect client 'localhost:1527;user=newuser;password=newpassword';

Use distributed system user accounts with the GRANT and REVOKE statements to manage access to database resources. See Configuring User Authorization.