Role Based Access Control

Introduction

Role-Based Access Control (RBAC) in Grainite controls authorization to the Grainite cluster and Applications (Topics, Tables, Action Handlers, and Tasks) based on the Roles assigned to Principals within an organization. In Grainite, RBAC is based on Principals, Roles, and Privileges.

• Principals: Any user, external client, or Grainite application.

  • External Users and Clients (including GX) must present a valid digital certificate to be authenticated.

  • Grainite applications must be running within the same cluster/environment.

• Roles: Collection of Privileges that can be assigned to a Principal or other Roles.

• Privileges: A mechanism used to grant permissions to access the cluster, perform operations, and access resources.

When RBAC is enabled, the privileges take effect depending on the scope where it is applied. The following scopes are supported in Grainite

• Cluster Level: The Principals, Roles, and Privileges are specified within the global_policy.yaml and apply across the entire cluster

• Application Level: The Principals, Roles, and Privileges specified within an application.yaml (e.g. userflows.yaml) only applies to the specific application. The Principals, Roles, and Privileges specified here extend the privileges specified at the cluster and environment level in which the application is running. Grainite also provides the ability for one application to control access to another application’s resources within the same cluster/environment.

Enabling RBAC at a cluster level

RBAC can be enabled by using the scripts provided by Grainite as part of cluster creation. The usage of the command depends on the cloud where you are deploying your cluster.

GCP:

./grainite/scripts/bin/gcp-grainite access-control-enable

AWS:

./grainite/scripts/bin/aws-grainite access-control-enable

Azure:

./grainite/scripts/bin/azure-grainite access-control-enable

When you enable RBAC, it generates a CA certificate, client certificate, and client key for a default Principal (user) cluster_admin who has the built-in cluster_admin_role(all privileges). These files are created in the ~/.gxscerts/client folder. To add additional Principals, please follow the steps defined in the Enabling TLS section of Gitbook documentation.

In addition to the cluster_admin certificates, a default global policy configuration is also created in the ~/.gxscerts/ folder called global_policy.yaml.

global_policy.yaml

#add additional cluster administrators 

cluster_admin_role: user:<admin_user>

#add additional roles to the cluster. Assign principals and privileges (api_access) to the role.

roles:
  applications_admin:
    principals: user:<app_admin>
    api_access:
      - getApp
      - registerApp
      - registerSecurity
      - pauseApp
      - resumeApp
      - getRepository
      - registerRepository
      - removeRepository
  database_admin:
    principals: user:<db_admin>
    api_access:
      - backup
  security_admin:
    principals: user:<sec_admin>
    api_access:
      - registerSecurity

The global_policy.yaml file can be modified by the cluster_admin to enable additional principals to administer the cluster. The updated global_policy.yaml can be uploaded by the cluster_admin using the command below.

gx security load -H <cluster_ip> /path/to/global_policy.yaml

Enabling RBAC at the application level

RBAC can be configured for each application within the application's YAML configuration file. The configuration will extend the privileges assigned to Principals at the cluster level.

Note: If a cluster-level application administrator is not specified within the global_policy.yaml, then a Principal with cluster_admin_role must first load an application's YAML configuration file (e.g. userflows.yaml) and assign an administrator to that application. The format of this file is given below

app.yaml

#Specify application name
app_name: userflows
#specify package
package_id: org.samples
#create a new role and assign a principal and privileges to the role. 
roles:
  userflows_admin:
    principals: user:<user>
    api_access:
      - getApp
      - registerApp
      - registerSecurity

Once the application has been registered by the cluster administrator, the specified application administrator can then modify and upload the application's YAML configuration file. The configuration allows application administrators to:

• Add additional application administrators (Principals) to the application

• Create new roles, and assign API access privileges and Principals to the role

• Assign Read, Write, and Execute privileges to Topics, Tables, Action Handlers, and Tasks

• Specify Read, Write, and Execute privileges for other applications running within the cluster/environment to access the resources of this application.

Sample application YAML configuration file

app.yaml

#The application name and package_id cannot be changed once registered
app_name: userflows
package_id: org.samples

#location of jar file
jars:
 - target/userflows-jar-with-dependencies.jar

#Specify additional roles, assign Principals and Privileges
roles:
 userflows_admin:
   principals: user:<user>
   api_access:
     - GetApp
     - RegisterApp     
 app_loader:
   principals:
     - user:<user>
     - app:app_name
   api_access:
     - GetApp
     - RegisterApp
     - RegisterSecurity
     - PauseApp
     - ResumeApp
 app_controller:
   principals: user:<user>
   api_access:
     - PauseApp
     - ResumeApp

#assign read privilege to <user> for all resources within the application

privileges:
 read: user:<user>

#Assign privileges to tasks
tasks:
    - task_name: basic_task
      privileges:
        read: user:<name>
        execute: user:<name>

#Assign privileges to principals who can access the table
tables:
 - table_name: user_table
   privileges:
     read: user:<user>
   key_type: string
   maps:
     - id: 0
       privileges:
         Read: user:<user>
       name: raw_events
       key_type: string
       value_type: string
   action_handlers:
     - name: UserHandler
       type: java
       class_name: org.samples.userflows.actions.UserGrainUpdatesHandler
       actions:
         - action_name: updateEvents
           privileges:
             execute: app:<myApp> 
           method_name: handleUpdateEvents
           subscriptions:
             - subscription_name: updates
               topic_key: user_id
               topic_name: updates_topic

#Assign privileges to principals who can access the topic
topics:
 - topic_name: updates_topic
   privileges:
     write: user:<user>
   key_name: user_id
   key_type: string
   value_type: json

Note: In this example, the application admin grants (another application running within the cluster/environment execute privilege for the updateEvents action handler using execute: app:<myApp>

Role Inheritance:

Roles can inherit privileges from other Roles within Grainite. A sample configuration that demonstrates this is given below.

...
roles:
 userflows_admin:
   Principals: user:<user>
   api_access:
     - getApp
     - registerApp
     - registerSecurity

 app_controller:
   Principals: userflow_admin
   api_access:
     - pauseApp
     - resumeApp
...

In this example, userflow_admin (role) will not only have getApp, registerApp, and registerSecurity privileges directly assigned to it but will also inherit app_controllers (role) set of privileges pauseApp, and resumeApp.

API Access Privileges:

Cluster activities performed by external users and clients (Principals) are managed via access APIs within Grainite. Access to application resources is controlled via Read, Write, and Execute privileges at the application level as explained above.

GX CLI, used to administer the cluster, is also an external client and is governed by RBAC Principals, roles, and privileges.

The following table lists the GX command along with the required API privileges to allow Principals to administer the cluster using these commands. Depending on your requirements, appropriate privileges must be assigned.

GX Command	Description	API privileges
Load	Load or reload an application in Grainite	Load: * getRepository * registerRepository * getApp * registerApp * registerSecurity
Mon	Monitor basic application metrics for applications on the Grainite cluster.	In development. Open to any Principal.
Log	Prints the last 1000 lines of the application log file	In development. Open to any Principal.
App	Perform application-related actions.	App Info: * getApp App ls: * listApp App pause: * pauseApp * getApp App remove: * removeApp * getApp App resume: * resumeApp * getApp
Security	Configure global security policies in Grainite	Security Load: * registerSecurity
Repo	Perform repository-related actions	Repo info: * getRepository Repo list: * listRepositories Repo remove: * removeRepository Repo add: * registerRepository
Node	Perform node related commands	Node info: * getNodeInfo
Cluster	Perform Grainite cluster related commands	Cluster stats storage: * getStorageStats Cluster backup: * Backup Cluster restore: * In development Cluster version: * getServerVersion
Secret	Interface to get/put secrets	* getSecret * putSecret * deleteSecret
Task	Perform task-related actions	Handled within the application level privileges
Topic	Topic related actions	Handled within the application level privileges
Table	Table related actions	Handled within the application level privileges

Application Resource privileges:

The application YAML configuration defines access to an application's resources. These resources are Topics, Tables, Tasks, and Action Handlers. The privileges applicable to these resources are Read, Write, and Execute. The application YAML configuration allows for controlling access to am app's resources from a Principal or other Applications (running within the same environment). As a best practice, application resource privileges should only be assigned at the application level and not within the global or environment yaml file.