Apply folder authorization rules in bulk in SAS Viya
A number of new contributions to the pyviyatools repository have focused on performing typical administration tasks in bulk. In this post, we introduce some of these tools and see how they can be can be used by SAS administrators to automate the creation, application and maintenance of authorization rules to secure access to folders in Viya.
The authorization plugin to the sas-admin CLI
The sas-admin CLI's authorization plugin has an authorize/create-rule/grant option, which can be used to create individul authorization rules to grant privileges to an object for a specified principal (user, group or guest).
sas-admin authorization authorize --permissions Read --group groupA --object-uri /folders/folders/2414f911-d276-4357-8550-fcf03753c9e7
This works well, but what if we we wanted to create multiple authorisation rules at once rather than creating them in multiple passes? Thankfully, the authorization plugin also has a create-rules option, which takes in as an argument a path to a JSON file containing one or more rule definitions.
/opt/sas/viya/home/bin/sas-admin authorization create-rules --file newrules.json
Again, this works very effectively, but for my particular use case I wanted something that didn't require manually defining rules in the JSON structure required by the CLI plugin.
New pyviyatools
With assistance from our resident GEL expert on all things authorization, David Stern, I started to develop a new Python program that could read and parse a CSV file containing a list of folder authorization rules, automate the creation of the JSON file, and then automatically create all of those rules.
The script, applyfolderauthorization.py is the latest addition to the pyviyatools repository. The program requires that a path to the CSV file be passed in as an argument to the -f flag. The input CSV must be in the following format.
Column 1 is the full path to the folder
Column 2 is the principal type
Column 3 is the principal name
Column 4 is the access setting (grant or prohibit)
Column 5 is the permissions on the folder
Column 6 is the conveyed permissions on the folder's contents
For example, let's assume we want to create rules to define authorization for a set of folders for our organization's Marketing department:
/gelcontent/GELCorp/Marketing/Reports,group,Marketing,grant,"read,add,remove","read,update,delete,add,remove"
/gelcontent/GELCorp/Marketing/Reports,user,Douglas,grant,"read,update,add,remove,delete,secure","read,update,add,remove,delete,secure"
/gelcontent/GELCorp/Marketing/Analyses,group,Marketing,grant,"read,add,remove","read,update,delete,add,remove"
/gelcontent/GELCorp/Marketing/Work in Progress,group,Marketing,grant,"read,update,add,remove,delete,secure","read,update,add,remove,delete,secure"
Note the second set of permissions at the end of row, representing conveyed permissions. These permissions define access to the folder's contents, which may include subfolders.
applyfolderauthorization.py reads and parses the CSV file, and then constructs the JSON object containing the list of rule definitions. The JSON is written to a local file, bulk_rules_list.json, which looks something like:
[
{
"value": {
"description": "Created by applyfolderauthorizations.py",
"principalType": "group",
"objectUri": "/folders/folders/1ef7bce5-f1ac-4d2c-b4b8-0c5576177ebb",
"permissions": [
"read",
"add",
"remove"
],
"type": "grant",
"principal": "Marketing"
},
"op": "add"
},
{
"value": {
"description": "Created by applyfolderauthorizations.py",
"containerUri": "/folders/folders/1ef7bce5-f1ac-4d2c-b4b8-0c5576177ebb",
"principalType": "group",
"permissions": [
"read",
"update",
"delete",
"add",
"remove"
],
"type": "grant",
"principal": "Marketing"
},
"op": "add"
},
...
...
...
For each row in the CSV file, two JSON objects are created; one for permissions on the folders, and one for conveyed permissions (note the reference to the containerUri in the example above).
The program then constructs a CLI command, passing in bulk_rules_list.json as the value for create-rules option's --file flag in order to create the rules.
A single command triggers the entire process:
./applyfolderauthorization.py -f /tmp/PSGEL250-devops-applied-to-sas-viya-3.5/Administration/scripts/marketingauths.csv
Writing out bulk rule JSON file to bulk_rules_list.json
Executing command: /opt/sas/viya/home/bin/sas-admin authorization create-rules --file bulk_rules_list.json
8 rules were created.
Note that if a rule already exists, the default behaviour is to display the response returned by the CLI command, indicating the rule wasn't applied. Eventually, the program could be further improved to include more advanced error handling and include options to overwrite, delete or edit rules, to customize the name of the bulk_rules_list.json file, and so on.
We can use SAS Environment Manager to visualize the resulting permission pattern. For example, permissions on the Reports folder:
Select any image to see a larger version.
Mobile users: To view the images, select the "Full" version at the bottom of the page.
We can also view all rules from the Rules page of SAS Environment Manager. For instance, to see rules applied for Douglas (i.e. where he is the principal):
The pane on the left can be used to filter the list of rules by objectUri, containerUri, principal, and a number of other fields.
Alternatively, we can view rules using the sas-admin CLI (but note that there is currently no way to filter the output, and as such all rules will be displayed):
/opt/sas/viya/home/bin/sas-admin --output text authorization list-rules
Id ObjectUri Principal PrincipalType Type Permissions
...
46f80080-fbcf-4c3e-9cb2-e9b08f3b33ad /folders/folders/1ef7bce5-f1ac-4d2c-b4b8-0c5576177ebb Marketing group grant [add remove read]
94c338b1-3872-4083-9148-81449af7f89d Marketing group grant [update add delete remove read]
3079ef0b-47cc-4571-9f35-d845df4ca3d9 /folders/folders/1ef7bce5-f1ac-4d2c-b4b8-0c5576177ebb Douglas user grant [update secure add delete remove read]
a898d64a-e005-4d08-a2cd-3a71a2b4ccd2 Douglas user grant [update secure add delete remove read]
0b61b190-3eee-4163-82ee-7d06c1a18765 /folders/folders/661020d3-fb79-43d0-8edb-4767429a24c6 Marketing group grant [add remove read]
af31f7e1-4c7c-4d71-9458-f10dc03c0b1b Marketing group grant [update add delete remove read]
43bc37a8-9158-4113-ba1e-7ecc6f1b7db8 /folders/folders/8c569dbd-e70a-4065-bf07-c9edc8ec033f Marketing group grant [update secure add delete remove read]
872ca481-6764-44cd-9568-e6ef15eed909 Marketing group grant [update secure add delete remove read]
...
In both of the above examples, note that there are two entries for each row in our input CSV file. Rules with an objectUri represent permissions on an object. Those with a missing objectUri have a containerUri instead (not shown), and these represent conveyed permissions on the folder's contents.
Create groups and folders in bulk
Another recent addition to the pyiyatools by Gerry Nelson complements this tool well. createfolders.py was the inspiration for applyfolderauthorization.py, and both work in a similar way. createfolders.py reads a list of folder paths from a CSV file, and then makes REST calls to create those folders in batch. This provides a simple, effective method for not only creating an initial set of folders on a new deployment, but also for performing updates later in a change controlled manner.
A third tool, creategroups.py, takes a similar approach with creating custom group creation managing group membership. Groups and their members are first defined in a CSV file, which is then fed into the program to create the desired group membership with a single command.
Check out the examples to try these yourself.
The CSV files used as input for these programs could be stored centrally (e.g. commonly on Git, but also on regular storage if more appropriate) so that there is a single, up-to-date, easy-to-maintain, version-controlled file in a secure, accessible location. These files can then be used to provision new environments quickly and easily; consider a DevOps approach, where a like-for-like for environment must be stood up quickly for testing, for example. These pyviyatools can be utilized to quickly create groups and folder structures matching the source environment exactly. This approach to storing and managing the input CSV files can also be useful in cases where each environment (Development, Test, Prod) has its own groups, folders, and authorization rules.
Further Information
Refer to the SAS Developer site for a listing of the public REST & CAS APIs, which can be used to write your own code to perform other administrative tasks in a similar way.
Thank you for reading. I hope the information provided in this post has been helpful. Please leave a comment below to ask questions or share your own experiences.
