User Names for Authentication, Authorization, and Member Ownership

When working with both user authentication and user authorization, you need to understand how user names are treated by each system.

User Names are Converted to Authorization Identifiers

User names in the GemFire XD system are known as authorization identifiers. The authorization identifier is a string that represents the name of the user, if one was provided in the connection request. For example, the built-in function CURRENT_USER returns the authorization identifier for the current user.

After the authorization identifier is passed to the GemFire XD system, it becomes an SQL92Identifier. A SQL92Identifier is a kind of identifier that represents a database object such as a table or column. A SQL92Identifier is case-insensitive (it is converted to all caps) unless it is delimited with double quotes. A SQL92Identifier is limited to 128 characters, and has other limitations.

All user names must be valid authorization identifiers even if user authentication is turned off, and even if all users are allowed access to all databases.

For more information about SQL92Identifiers, see Keywords and Identifiers.

Handling Case Sensitivity and Special Characters in User Names

If an external authentication system is used, GemFire XD does not convert a user's name to an authorization identifier until after authentication has occurred (but before the user is authorized). For example, with an example user named Fred:

  • Within the user authentication system, Fred might be known as FRed. If the external user authentication service is case-sensitive, Fred must always type his name that way:
    connect client 'localhost:1527;user=FRed;password=flintstone';
  • Within the GemFire XD user authorization system, Fred becomes a case-insensitive authorization identifier. Here, FRed is known as FRED.
  • When specifying those users that are authorized to access the system, you must list Fred's authorization identifier, FRED (which you can type as FRED, FREd, or fred, because the system automatically converts the authorization identifier to all-uppercase).
    gemfirexd.authz-full-access-users=sa,FRED,mary
    Note: You must define the access list property gemfirexd.authz-full-access-users as a Java system property at the command line when starting GemFire XD, rather than in the gemfirexd.properties file.

Also consider a second example, where Fred has a slightly different name within the user authentication system:

  • Within the user authentication system, Fred is known as Fred!. You must now put double quotes around the username, because it is not a valid SQL92Identifier. (GemFire XD knows to remove the double quotes when passing the name to the external authentication system.)
    connect client 'localhost:1527;user="Fred!";password=flintstone';
  • Within the GemFire XD user authorization system, Fred now becomes a case-sensitive authorization identifier. In this case, Fred is known as Fred!.
  • When specifying those users that are authorized to access the system, you must use Fred's authorization identifier, "Fred!", which must always be delimited with double quotation marks:
    gemfirexd.authz-full-access-users=sa,"Fred!",manager
    Note: You must define the access list property gemfirexd.authz-full-access-users as a Java system property at the command line when starting GemFire XD, rather than in the gemfirexd.properties file.

As shown in the first example, the external authentication system may be case-sensitive, whereas the authorization identifier within GemFire XD may not be. If your authentication system allows two distinct users whose names differ by case, delimit all user names within the connection request to make all user names case-sensitive within the GemFire XD system. In addition, you must also delimit user names that do not conform to SQL92Identifier rules with double quotes.

Understanding GemFire XD Member Ownership

The authenticated system user that starts up a GemFire XD member is the owner of that member JVM. The term JVM owner refers to the authorization identifier of the user who booted the member. The JVM owner owns any schemas and database objects that they create in the distributed system. The owner also owns any schemas and database objects in the JVM that were created by other JVM owners. In other words, GemFire XD treats all JVM owners interchangeably when a GemFire XD member is booted.

The JVM owner has automatic SQL level permissions when SQL authorization is enabled, and can grant access to any database objects using the GRANT command. See Configuring User Authorization for more information.

If you enable or plan to enable SQL authorization, then controlling the identity of the JVM owner becomes important. The owner of a GemFire XD member cannot be changed after the JVM is started. However, member ownership can be changed by stopping the member process and then restarting it using the credentials of another user.

Note: If a member is started without supplying a user (only possible if authentication is not enabled), then the JVM owner is set to the default authorization identifier, "APP", which is also the name of the default schema.
Attention: The JVM owner cannot be changed after the GemFire XD member starts. Instead, you must stop the member and then restart it using different user credentials. If you plan to run with SQL authorization enabled, start new GemFire XD members as the user that you want to be the JVM owner.