Permissions
...
Users
Groups
Roles
Permissions
When talking about zone management and users, groups, roles, and permissions, it is useful to remember there is a distinct division between permissions and scopes. Permissions control access to a YOUnite resource (i.e endpoints) and scopes control access to the data behind the /domains
and /dr
endpoints.
When a zone is created, the automatically-created zone users of Zone IT Admin (admin) and the Zone Data Steward (ZDS) are given appropriate permissions based on their respective roles. The admin Zone Admin can grant permissions to most of the resources in the zone and the remainder. The remainder of the permissions, which are data related, are granted by the ZDS.
Permissions to resources are restricted 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 ALL, which is a shortcut for "all vebsverbs":
- GET
- PUT
- POST
- DELETE
- ANY
Examples
...
- ALL
Examples
To allow a user to view the groups in a zone:
Code Block | ||
---|---|---|
| ||
{
"type": "ALLOW",
"action": "GET",
"resource": "/zones/18e1f27a-36b5-472f-a03c-6831fb78f97a/groups/*"
} |
The user with the permissions to view zone groups can then get the list of groups in the zone:
Code Block | ||
---|---|---|
| ||
GET /zones/18e1f27a-36b5-472f-a03c-6831fb78f97a/groups |
Getting the group with UUID 9e463a36-5dd7-4440-8a90-94ce32e06c13 :
Code Block | ||
---|---|---|
| ||
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:
Code Block | ||
---|---|---|
| ||
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 allows a user to view all of the adaptors in the zone (identified by UUID 18e1f27a-36b5-472f-a03c-6831fb78f97a in the example below).
Code Block | ||
---|---|---|
| ||
{ "type": "ALLOW", "action": "GET", "resource": "/zones/18e1f27a-36b5-472f-a03c-6831fb78f97a/adaptors" } |
...
Note the absence of the wildcard character.
Setting access by resource name in the example above allows the user to request the following:
Code Block | ||
---|---|---|
| ||
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:
Code Block | ||
---|---|---|
| ||
GET /zones/18e1f27a-36b5-472f-a03c-6831fb78f97a/adaptors/7c11c574-0e35-4c78-b572-222952156ac8 |
...
73f26990-db53-47fe-a73f-734921ff323d
73f26990-db53-47fe-a73f-734921ff323d
73f26990-db53-47fe-a73f-734921ff323d
7373f26990-db53-47fe-a73f-734921ff323df26990-db53-47fe-a73f-734921ff323d
Permissions
So… one of our underlying philosophies is that, “sure you can give permissions to view all of a given sub-resources in a zone” e.g. /zones/uuid/users” …
[10:50]
or… “all of the sub-resources sub resources” e.g. /zones/uuid/users/*73f26990-db53-47fe-a73f-734921ff323d
73f26990-db53-47fe-a73f-734921ff323d73f26990-db53-47fe-a73f-734921ff323d
[10:51]
but if you want to limit which sub-resources can be accessed you need to turn them on/off individually
Robbie Gehbauer
[10:52 AM]
makes sense to me
Mark Fitzpatrick [10:52 AM]
and until we have something like templates, you’ll need to make the appropriate settings when POSTing new resources
[10:53]
and to continue being philosophical…
[10:54]
There are these cases that seem redundant and the behavior needs to be understood e.g.
[10:54]
If a zoneUser has the permissions {
[10:54]
GET /zones/uuid/users
[10:55]
GET /zones/uuid/users/user1-uuid
[10:55]
}
[10:55]
(and say there are three zoneUsers in the zone)
[10:56]
One might think that GET /zones/uuid/users would only return user-1
[10:56]
but it would return all three users
[10:56]
GET /zones/uuid/users/user2-uuid would get an “Access Denied”
[10:57]
...
Access by Individual Resource
This permission allows the user access to an individual adaptor, but not that adaptor's resource details.
Code Block | ||
---|---|---|
| ||
{
"type": "ALLOW",
"action": "GET",
"resource": "/zones/18e1f27a-36b5-472f-a03c-6831fb78f97a/adaptors/7c11c574-0e35-4c78-b572-222952156ac8"
} |
This is in contrast to allowing the user detailed access to all adaptors in the zone, using the * wildcard, which does allow the user access to that adaptor's resource details.
Code Block | ||
---|---|---|
| ||
{
"type": "ALLOW",
"action": "GET",
"resource": "/zones/18e1f27a-36b5-472f-a03c-6831fb78f97a/adaptors/*"
} |
Sensitive Sub Resource Access
...
NOTE: The examples below demonstrate how to manage secure access with the adaptors resource but similar situations could apply with other resources.
...
There are cases where using wildcards may not be desirable, since they allow access to resources that should be accessed by only the Zone Admin.
For example...
Code Block | ||
---|---|---|
| ||
{
"type": "ALLOW",
"action": "GET",
"resource": "/zones/18e1f27a-36b5-472f-a03c-6831fb78f97a/adaptors/*"
} |
...allows a user to see all of the adaptor's registration information for a given zone:
Code Block | ||
---|---|---|
| ||
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 that zone's adaptors must be granted on an adaptor-by-adaptor basis.
For example, assume the zone in our examples has three adaptors:
Code Block | ||
---|---|---|
| ||
[
{ ....
"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:
Code Block | ||
---|---|---|
| ||
{
"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...
Code Block | ||
---|---|---|
| ||
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:
Code Block | ||
---|---|---|
| ||
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:
Code Block | ||
---|---|---|
| ||
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.