Skip to content

Commit fc91efd

Browse files
j616j616
committed
Enumerate endpoints, methods, and recommended roles for coarse-grain auth
1 parent 23edfde commit fc91efd

1 file changed

Lines changed: 67 additions & 15 deletions

File tree

‎docs/appnotes/0016-authorisation-in-tams-workflows.md‎

Lines changed: 67 additions & 15 deletions
Original file line numberDiff line numberDiff line change
@@ -24,26 +24,78 @@ This may be appropriate for example when working with a large number of third pa
2424
A simple approach is to define permissions that apply to an entire TAMS instance at a very coarse level, and use Role-based Access Control (RBAC) to grant access through those permissions.
2525
In RBAC, each action is restricted to users holding a certain role, and users are assigned the relevant roles they need.
2626

27-
The permissions (or "scopes" in OAuth 2.0), could be:
28-
29-
- `tams-api/read`: Allow GET and HEAD methods
30-
- `tams-api/write`: Allow PUT and POST methods
31-
- `tams-api/delete`: Allow DELETE methods
32-
33-
_Note that these example permissions are drawn from the [AWS TAMS implementation](https://github.com/awslabs/time-addressable-media-store/blob/v3.0/README.md#usage)._
34-
35-
Then roles could be created in the authorisation system which allow some combinations of those scopes, for example:
36-
37-
- `administrator`: Has all three scopes
27+
These are the recommended permissions (or "scopes" in OAuth 2.0):
28+
29+
| Endpoint | Method | `tams-api/admin` | `tams-api/read` | `tams-api/write` | `tams-api/delete` |
30+
| ------------------------------------ | --------------- | ---------------- | --------------- | ---------------- | ----------------- |
31+
| `/` | `HEAD`/`GET` ⚠️ | ✅ | ✅ | ✅ | ✅ |
32+
| `/service` | `HEAD`/`GET` ⚠️ | ✅ | ✅ | ✅ | ✅ |
33+
| | `POST` ⚠️ | ✅ | ❌ | ❌ | ❌ |
34+
| `/service/storage-backends` | `HEAD`/`GET` ⚠️ | ❌ | ✅ | ✅ | ❌ |
35+
| `/service/webhooks` | `HEAD`/`GET` ⚠️ | ✅ | ❌ | ❌ | ❌ |
36+
| | `POST` ⚠️ | ✅ | ❌ | ❌ | ❌ |
37+
| `/sources` | `HEAD`/`GET` | ❌ | ✅ | ❌ | ❌ |
38+
| `/sources/{sourceId}` | `HEAD`/`GET` | ❌ | ✅ | ❌ | ❌ |
39+
| `/sources/{sourceId}/tags` | `HEAD`/`GET` | ❌ | ✅ | ❌ | ❌ |
40+
| `/sources/{sourceId}/tags/{name}` | `HEAD`/`GET` | ❌ | ✅ | ❌ | ❌ |
41+
| | `PUT` | ❌ | ❌ | ✅ | ❌ |
42+
| | `DELETE` ⚠️ | ❌ | ❌ | ✅ | ❌ |
43+
| `/sources/{sourceId}/description` | `HEAD`/`GET` | ❌ | ✅ | ❌ | ❌ |
44+
| | `PUT` | ❌ | ❌ | ✅ | ❌ |
45+
| | `DELETE` ⚠️ | ❌ | ❌ | ✅ | ❌ |
46+
| `/sources/{sourceId}/label` | `HEAD`/`GET` | ❌ | ✅ | ❌ | ❌ |
47+
| | `PUT` | ❌ | ❌ | ✅ | ❌ |
48+
| | `DELETE` ⚠️ | ❌ | ❌ | ✅ | ❌ |
49+
| `/flows` | `HEAD`/`GET` | ❌ | ✅ | ❌ | ❌ |
50+
| `/flows/{flowId}` | `HEAD`/`GET` | ❌ | ✅ | ❌ | ❌ |
51+
| | `PUT` | ❌ | ❌ | ✅ | ❌ |
52+
| | `DELETE` | ❌ | ❌ | ❌ | ✅ |
53+
| `/flows/{flowId}/tags` | `HEAD`/`GET` | ❌ | ✅ | ❌ | ❌ |
54+
| `/flows/{flowId}/tags/{name}` | `HEAD`/`GET` | ❌ | ✅ | ❌ | ❌ |
55+
| | `PUT` | ❌ | ❌ | ✅ | ❌ |
56+
| | `DELETE` ⚠️ | ❌ | ❌ | ✅ | ❌ |
57+
| `/flows/{flowId}/description` | `HEAD`/`GET` | ❌ | ✅ | ❌ | ❌ |
58+
| | `PUT` | ❌ | ❌ | ✅ | ❌ |
59+
| | `DELETE` ⚠️ | ❌ | ❌ | ✅ | ❌ |
60+
| `/flows/{flowId}/label` | `HEAD`/`GET` | ❌ | ✅ | ❌ | ❌ |
61+
| | `PUT` | ❌ | ❌ | ✅ | ❌ |
62+
| | `DELETE` ⚠️ | ❌ | ❌ | ✅ | ❌ |
63+
| `/flows/{flowId}/read_only` | `HEAD`/`GET` | ❌ | ✅ | ❌ | ❌ |
64+
| | `PUT` | ❌ | ❌ | ✅ | ❌ |
65+
| `/flows/{flowId}/flow_collection` | `HEAD`/`GET` | ❌ | ✅ | ❌ | ❌ |
66+
| | `PUT` | ❌ | ❌ | ✅ | ❌ |
67+
| | `DELETE` ⚠️ | ❌ | ❌ | ✅ | ❌ |
68+
| `/flows/{flowId}/max_bit_rate` | `HEAD`/`GET` | ❌ | ✅ | ❌ | ❌ |
69+
| | `PUT` | ❌ | ❌ | ✅ | ❌ |
70+
| | `DELETE` ⚠️ | ❌ | ❌ | ✅ | ❌ |
71+
| `/flows/{flowId}/avg_bit_rate` | `HEAD`/`GET` | ❌ | ✅ | ❌ | ❌ |
72+
| | `PUT` | ❌ | ❌ | ✅ | ❌ |
73+
| | `DELETE` ⚠️ | ❌ | ❌ | ✅ | ❌ |
74+
| `/flows/{flowId}/segments` | `HEAD`/`GET` | ❌ | ✅ | ❌ | ❌ |
75+
| | `POST` | ❌ | ❌ | ✅ | ❌ |
76+
| | `DELETE` | ❌ | ❌ | ❌ | ✅ |
77+
| `/flows/{flowId}/storage` | `POST` | ❌ | ❌ | ✅ | ❌ |
78+
| `/objects/{objectId}` | `HEAD`/`GET` | ❌ | ✅ | ❌ | ❌ |
79+
| `/flow-delete-requests` | `HEAD`/`GET` ⚠️ | ✅ | ❌ | ❌ | ❌ |
80+
| `/flow-delete-requests/{request-id}` | `HEAD`/`GET` ⚠️ | ❌ | ❌ | ❌ | ✅ |
81+
82+
Key for the listing:
83+
84+
- ✅: Allow method with this OAuth scope
85+
- ❌: Do not allow method with this OAuth scope.
86+
Other claimed scopes may still allow this method
87+
- ⚠️: Method does not follow the basic mapping of `tams-api/read` to `HEAD`/`GET`, `tams-api/write` to `POST`/`PUT`, and `tams-api/delete` to `DELETE`
88+
89+
Users may be assigned combinations of these roles for different purposes, for example:
90+
91+
- `administrator`: Has all four scopes
3892
- `viewer`: Has `tams-api/read`
3993
- `editor`: Has `tams-api/read` and `tams-api/write`
4094
- `store-writer`: Has `tams-api/write`
4195
- `store-cleanup-system`: Has `tams-api/delete`
4296

43-
Users, or groups of users can then be assigned into those roles: for example a "News Journalists" group might be assigned `editor`, while other staff have `viewer`, but only the automated processes of a MAM have `store-cleanup-system`.
44-
Alternatively, the permissions can be used directly, assigning them to user groups without grouping them into roles.
45-
46-
To implement the authorisation, the authorisation server checks the requested scopes against the user's access when issuing a token, and rejects the request if a suitable access isn't assigned.
97+
To implement the authorisation, the authorisation server checks the requested scopes against the user's access when issuing a token.
98+
The TAMS server, or it's auth proxy, rejects the requests without appropriate scopes.
4799

48100
## Finer Grained Authorisation
49101

0 commit comments

Comments
 (0)