Security Usage

The examples below use the Java API to manage users, roles, and permissions. There's two styles of Kinetica API calls featured: using the specific request object and the passing of values in the parameter list. All of our API functions support both styles.

Authenticating

Authenticating endpoint calls to Kinetica requires setting the username and password in the creation of the Kinetica instance. First, you will use the URL for the Kinetica proxy, e.g., http://<kinetica.server>:8082/gpudb-0. Then, you must create a GPUdbBase.Options instance, in which you will set the username and password. This gets passed to GPUdb constructor. All subsequent API calls will use the username and password set in the Kinetica instance.

Note

API authentication is only required if you've setup HTTPD for Kinetica.

GPUdbBase.Options options = new GPUdbBase.Options();
options.setUsername(USERNAME);
options.setPassword(PASSWORD);
this.gpudb = new GPUdb(GPUDB_PROXY_URL,options);

Creating Roles and Assigning Permissions

//Create a system admin role
gpudb.createRole("sample_system_admin_role",null);

//Assign permissions to role
GrantPermissionSystemRequest grantSystemRequest = new GrantPermissionSystemRequest();
grantSystemRequest.setName("sample_system_admin_role");
grantSystemRequest.setPermission(GrantPermissionSystemRequest.Permission.SYSTEM_ADMIN);
gpudb.grantPermissionSystem(grantSystemRequest);

Creating Users and Assigning Roles

//Create a new user and give it the new sample_system_admin_role
gpudb.createUserInternal("testadmin", "testadmin", null);

gpudb.grantRole("sample_system_admin_role", "testadmin",null);

Removing Users from Roles

//revoke testadmin's membership in sample_system_admin_role
gpudb.revokeRole("sample_system_admin_role", "testadmin", null);

Granting Users Permissions on Tables

//grant limiteduser read permission for securityTestTable
GrantPermissionTableRequest request = new GrantPermissionTableRequest();
request.setName("limiteduser");
request.setPermission(GrantPermissionTableRequest.Permission.TABLE_READ);
request.setTableName("securityTestTable");
gpudb.grantPermissionTable(request);

Note

If request.setTableName was not called, the user would be granted read permissions on all tables at the root level.

Revoking Users Permissions on Tables

gpudb.revokePermissionTable("limiteduser", RevokePermissionTableRequest.Permission.TABLE_READ, "securityTestTable", null);

Note

If the table name was not set when granting the permission, revoking permissions on a specific table will have no effect. This is because the user would have been granted permissions to all tables at the root level. Revoking access to an individual table still leaves the user with access to all tables. Revokation must be done on "" or using the request object and not setting the table name.

Retrieving User or Role Security Information

ShowSecurityResponse response = gpudb.showSecurity(Arrays.asList("sample_system_admin_role"),null);
System.out.printf("Show security for sample_system_admin_role: %s\n",response.toString());

Produces the output:

Show security for sample_system_admin_role: {"types": {"sample_system_admin_role": "role"}, "roles": {}, "permissions": {"sample_system_admin_role": [{"permission": "system_admin"}]}}

response = gpudb.showSecurity(Arrays.asList("limiteduser"),null);
System.out.printf("Show security for limitedUser: %s\n",response.toString());

Produces the output:

Show security for limitedUser: {"types": {"limiteduser": "internal_user"}, "roles": {"limiteduser": ["authenticated", "public"]}, "permissions": {"limiteduser": [{"table_name": "securityTestTable", "filter_expression": "", "permission": "table_read"}]}}

External (LDAP) Users

Differences between using an external user instead of an internal user:

• Rather than connect to Kinetica through its port (normally 9191), you will connect to the HTTPD proxy's port (8082 by default). When creating this connection, you will pass the LDAP user's username and password.
• Kinetica does not import users from LDAP. For each LDAP user you want to use in Kinetica, you must create a corresponding Kinetica user. The username in Kinetica must be the @ symbol followed by the LDAP username.
• You will first need to connect as an internal user with system administration permissions in order to create an external user. If you create an external user with system administration permissions, all future work can be done with LDAP users.

Note

Kinetica LDAP integration only uses the username, not LDAP groups. Therefore, all role management of users, regardless of internal or external, must be done within Kinetica.

Below is an example using the external jdoe account that gets added to LDAP by a LDAP initialization script.

try {
    //Create a system admin role
    gpudb.createRole("sample_system_admin_role",null);

    //Assign permissions to role
    GrantPermissionSystemRequest grantSystemRequest = new GrantPermissionSystemRequest();
    grantSystemRequest.setName("sample_system_admin_role");
    grantSystemRequest.setPermission(GrantPermissionSystemRequest.Permission.SYSTEM_ADMIN);
    gpudb.grantPermissionSystem(grantSystemRequest);

    //Create a new external user and give it the new sample_system_admin_role
    gpudb.createUserExternal("@jdoe",null);
    gpudb.grantRole("sample_system_admin_role", "@jdoe",null);

    //Connect as the external user and create a table
    GPUdb testGPUdb = new GPUdb(PROXY_URL,new GPUdbBase.Options().setUsername("jdoe").setPassword("jdoe"));
    try{
        System.out.printf("Creating table as @jdoe\n");
        String typeId = RecordObject.createType(WeatherRecord.class, testGPUdb);
        testGPUdb.addKnownType(typeId, WeatherRecord.class);
        testGPUdb.createTable(TABLE_NAME, typeId, null);
        System.out.printf("created table\n");
    }
    catch(GPUdbException ex){
        System.out.printf("failed to create table:%s\n", ex.getMessage());
    }
    System.out.println("Was the table created? " + tableExists(gpudb,TABLE_NAME));

} catch (GPUdbException ex) {
    Logger.getLogger(SecuritySamples.class.getName()).log(Level.SEVERE, null, ex);
}