Permissions
There is a distinct division between permissions and scopes. Permissions control access to YOUnite resource (i.e endpoints) and scopes control access to the data behind the /domains
and /dr
endpoints.
When a zone is created, the zone users 1) Zone IT Admin (admin) and 2) Zone Data Steward (ZDS) are given appropriate permissions based on their respective roles. The admin can grant permissions to most of the resources in the zone. The remainder of the permissions, which are data related, are granted by the ZDS.
Resource permissions granted to zone users (users) are restrictive by default. Permissions can be granted to a resource by specifying:
- The "ALLOW" type of permission
- The URI location
- The URI can contain the
*
wildcard character.
- The URI can contain the
- The REST action. Possible actions mirror the REST verbs available at the resource and the special case ANY which is a shortcut for "all vebs":
- GET
- PUT
- POST
- DELETE
- ANY
Examples
To allow a user to view the groups in a zone:
{ "type": "ALLOW", "action": "GET", "resource": "/zones/18e1f27a-36b5-472f-a03c-6831fb78f97a/groups/*" }
For example:
GET /zones/18e1f27a-36b5-472f-a03c-6831fb78f97a/groups
Get the group with UUID 9e463a36-5dd7-4440-8a90-94ce32e06c13 :
GET /zones/18e1f27a-36b5-472f-a03c-6831fb78f97a/groups/9e463a36-5dd7-4440-8a90-94ce32e06c13
The wildcard character works recursively and allows the user access to the sub-resources as well:
GET /zones/18e1f27a-36b5-472f-a03c-6831fb78f97a/groups/9e463a36-5dd7-4440-8a90-94ce32e06c13/permissions
Special Cases
Typically, permissions end with the wildcard "*" e.g. /zones/zone-uuid/users/*. However, there are cases where permissions end with:
- The resource name e.g. e.g. /zones/zone-uuid/users
- Individual resource e.g. /zones/18e1f27a-36b5-472f-a03c-6831fb78f97a/adaptors/7c11c574-0e35-4c78-b572-222952156ac8
Individual resource access is needed at times when sub-resources contain sensitive information as described below in "Sensitive Sub Resource Access."
Access by Resource Name
This permission allow a user to view all of the adaptors in the zone identified by UUID 18e1f27a-36b5-472f-a03c-6831fb78f97a.
{ "type": "ALLOW", "action": "GET", "resource": "/zones/18e1f27a-36b5-472f-a03c-6831fb78f97a/adaptors" }
This request can now be made by the user:
GET /zones/18e1f27a-36b5-472f-a03c-6831fb78f97a/adaptors
However, this would not allow the user to view the individual adaptor resource details. For example, if the zone had an adaptor identified by the UUID 7c11c574-0e35-4c78-b572-222952156ac8, this request would be denied:
GET /zones/18e1f27a-36b5-472f-a03c-6831fb78f97a/adaptors/7c11c574-0e35-4c78-b572-222952156ac8
Access by Individual Resource
To allow the user access to an individual adaptor:
{ "type": "ALLOW", "action": "GET", "resource": "/zones/18e1f27a-36b5-472f-a03c-6831fb78f97a/adaptors/7c11c574-0e35-4c78-b572-222952156ac8" }
This is in contract to allowing the user detailed access to all adaptors in the zone, using the '*' wildcard:
{ "type": "ALLOW", "action": "GET", "resource": "/zones/18e1f27a-36b5-472f-a03c-6831fb78f97a/adaptors/*" }
Sensitive Sub Resource Access
NOTE: The examples demonstrate how to manage secure access with the adaptors resource but similar situations could apply with other resources.
Using wildcards at times may not be desirable since it would allow access resources that should be accessed by only the admin. For example:
{ "type": "ALLOW", "action": "GET", "resource": "/zones/18e1f27a-36b5-472f-a03c-6831fb78f97a/adaptors/*" }
Would allow a user to see all of the adaptor's registration information for a given zone:
GET /zones/18e1f27a-36b5-472f-a03c-6831fb78f97a/adaptors/7c11c574-0e35-4c78-b572-222952156ac8/registration
If the requirement is to grant a user detailed access to adaptors in a zone but not grant access to the adaptor's registration information, then permission to adaptors in the zone must be granted on an adaptor by adaptor basis. For example, assume the zone in our examples has three adaptors:
[ { .... "uuid": "7c11c574-0e35-4c78-b572-222952156aaa", .... }, { .... "uuid": "ae91d787-65c9-4f24-bff4-e3acbd616bbb", .... }, { .... "uuid": "ca445ebd-ffcb-4001-9d63-19e773a95ccc", .... } ]
And that a user has the following permissions:
{ "type": "ALLOW", "action": "GET", "resource": "/zones/18e1f27a-36b5-472f-a03c-6831fb78f97a/adaptors" }, { "type": "ALLOW", "action": "GET", "resource": "/zones/18e1f27a-36b5-472f-a03c-6831fb78f97a/adaptors/7c11c574-0e35-4c78-b572-222952156aaa" }, { "type": "ALLOW", "action": "GET", "resource": "/zones/18e1f27a-36b5-472f-a03c-6831fb78f97a/adaptors/ae91d787-65c9-4f24-bff4-e3acbd616bbb" }
The following request would return limited information on all three adaptors
GET /zones/18e1f27a-36b5-472f-a03c-6831fb78f97a/adaptors
And detailed access to either adaptor specified in the permissions (ending in aaa and bbb) would be allowed but the following request would be denied:
GET /zones/18e1f27a-36b5-472f-a03c-6831fb78f97a/adaptors/ca445ebd-ffcb-4001-9d63-19e773a95ccc
Since the user's permission setting for the adaptor ending in aaa has the wildcard permission, the user could see the registration details for this adaptor:
GET /zones/18e1f27a-36b5-472f-a03c-6831fb78f97a/adaptors/7c11c574-0e35-4c78-b572-222952156aaa/registration
But the user could not retrieve the registration details for the adaptor ending in bbb since the wildcard adaptor wasn't applied nor the adaptor aaa since specific permissions for it were not granted.
This allows information about the adaptors to be shared but limits the access to the sensitive registration information about the adaptor.