Comment on page
Role Based Access Control
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.
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.
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.
#add additional cluster administrators
#add additional roles to the cluster. Assign principals and privileges (api_access) to the role.
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
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
#Specify application name
#create a new role and assign a principal and privileges to the role.
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.
#The application name and package_id cannot be changed once registered
#location of jar file
#Specify additional roles, assign Principals and Privileges
#assign read privilege to <user> for all resources within the application
#Assign privileges to tasks
- task_name: basic_task
#Assign privileges to principals who can access the table
- table_name: user_table
- id: 0
- name: UserHandler
- action_name: updateEvents
- subscription_name: updates
#Assign privileges to principals who can access the topic
- topic_name: updates_topic
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>
Roles can inherit privileges from other Roles within Grainite. A sample configuration that demonstrates this is given below.
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.
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.
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.