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.
./grainite/scripts/bin/gcp-grainite access-control-enable
./grainite/scripts/bin/aws-grainite access-control-enable
./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
1
#add additional cluster administrators
2
3
cluster_admin_role: user:<admin_user>
4
5
#add additional roles to the cluster. Assign principals and privileges (api_access) to the role.
6
7
roles:
8
applications_admin:
9
principals: user:<app_admin>
10
api_access:
11
- getApp
12
- registerApp
13
- registerSecurity
14
- pauseApp
15
- resumeApp
16
- getRepository
17
- registerRepository
18
- removeRepository
19
database_admin:
20
principals: user:<db_admin>
21
api_access:
22
- backup
23
security_admin:
24
principals: user:<sec_admin>
25
api_access:
26
- 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
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 belowapp.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.
app.yaml
1
#The application name and package_id cannot be changed once registered
2
app_name: userflows
3
package_id: org.samples
4
5
#location of jar file
6
jars:
7
- target/userflows-jar-with-dependencies.jar
8
9
#Specify additional roles, assign Principals and Privileges
10
roles:
11
userflows_admin:
12
principals: user:<user>
13
api_access:
14
- GetApp
15
- RegisterApp
16
app_loader:
17
principals:
18
- user:<user>
19
- app:app_name
20
api_access:
21
- GetApp
22
- RegisterApp
23
- RegisterSecurity
24
- PauseApp
25
- ResumeApp
26
app_controller:
27
principals: user:<user>
28
api_access:
29
- PauseApp
30
- ResumeApp
31
32
#assign read privilege to <user> for all resources within the application
33
34
privileges:
35
read: user:<user>
36
37
#Assign privileges to tasks
38
tasks:
39
- task_name: basic_task
40
privileges:
41
read: user:<name>
42
execute: user:<name>
43
44
#Assign privileges to principals who can access the table
45
tables:
46
- table_name: user_table
47
privileges:
48
read: user:<user>
49
key_type: string
50
maps:
51
- id: 0
52
privileges:
53
Read: user:<user>
54
name: raw_events
55
key_type: string
56
value_type: string
57
action_handlers:
58
- name: UserHandler
59
type: java
60
class_name: org.samples.userflows.actions.UserGrainUpdatesHandler
61
actions:
62
- action_name: updateEvents
63
privileges:
64
execute: app:<myApp>
65
method_name: handleUpdateEvents
66
subscriptions:
67
- subscription_name: updates
68
topic_key: user_id
69
topic_name: updates_topic
70
71
#Assign privileges to principals who can access the topic
72
topics:
73
- topic_name: updates_topic
74
privileges:
75
write: user:<user>
76
key_name: user_id
77
key_type: string
78
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>
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.
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 |
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.
Last modified 2mo ago