User Permissions

Stream Chat ships with a configurable permission system that allows high resolution control over what users, guests, admins, and anonymous users are permitted to do.

Before we dive into more detail on how permission policies are structured, let's explain how permission checking works in general. Every time a user performs an API request the following steps happen:

1. The policies for the channel type are loaded

2. The list of policies is iterated based on priority (highest first)

   1. If the policy matches the current request, then the request is either accepted or discarded

   2. If there is not match, continue iterating until one policy matches

Here's what a list of permissions look like:

1. Admin users can perform any action

2. Anonymous users are not allowed

3. Users can modify their own messages

4. Users can create channels

5. Members of a channel can read and send messages

6. Anything not matching the previous list should not be allowed

Let's now see how this would play out and introduce a couple of users: Tommaso and Thierry. Tommaso is an admin and Thierry a user. Thierry is also a member of the "Sailing" channel.

1. Thierry posts a message on channel "soccer"

2. Tommaso edits a message from Thierry

3. Thierry creates a channel called "founders"

4. An anonymous user opens the "Sailing" channel

Here's what the outcome of these requests would be:

1. 🙅‍♂️ Only the last policy matches and it denies this action

2. 👌 Tommaso is an admin, 1st policy is a match

3. 👌 Thierry is a user, 4th policy is a match

4. 🙅‍♂️ Anonymous users are discarded

Now that we have a better idea about how the permission system works, let's define more precisely the structure of a permission policy.

Let's now write the example from before into a list of real policies.

1
2
3
4
5
6
7
8
9
10
11
12
import { AnyResource, AnyRole, Allow, Deny} from 'stream-chat'; 
 
const permissions = [ 
  new Permission("Admin users can perform any action", 600, AnyResource, ["admin"], false, Allow), 
  new Permission("Anonymous users are not allowed", 500, AnyResource, ["anonymous"], false, Deny), 
  new Permission("Users can modify their own messages", 400, AnyResource, ["user"], true, Allow), 
  new Permission("Users can create channels", 300, AnyResource, ["user"], false, Allow), 
  new Permission("Channel Members", 200, ["ReadChannel", "CreateMessage"], ["channel_member"], false, Allow), 
  new Permission("Discard all", 100, AnyResource, AnyRole, false, Deny), 
]; 
 
await client.updateChannelType("messaging", {permissions});

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
[ 
  { 
    "action":"Allow", 
    "name":"Admin users can perform any action", 
    "resources":[ 
      "*" 
    ], 
    "roles":[ 
      "*" 
    ], 
    "owner":false, 
    "priority":600 
  }, 
  { 
    "action":"Deny", 
    "name":"Anonymous users are not allowed", 
    "resources":[ 
      "*" 
    ], 
    "roles":[ 
      "anonymous" 
    ], 
    "owner":false, 
    "priority":500 
  }, 
  { 
    "action":"Allow", 
    "name":"Users can modify their own messages", 
    "resources":[ 
      "*" 
    ], 
    "roles":[ 
      "user" 
    ], 
    "owner":true, 
    "priority":400 
  }, 
  { 
    "action":"Allow", 
    "name":"Users can create channels", 
    "resources":[ 
      "*" 
    ], 
    "roles":[ 
      "user" 
    ], 
    "owner":false, 
    "priority":300 
  }, 
  { 
    "action":"Allow", 
    "name":"Channel Members", 
    "resources":[ 
      "ReadChannel", 
      "CreateMessage" 
    ], 
    "roles":[ 
      "channel_member" 
    ], 
    "owner":false, 
    "priority":200 
  }, 
  { 
    "action":"Deny", 
    "name":"Discard all", 
    "resources":[ 
      "*" 
    ], 
    "roles":[ 
      "*" 
    ], 
    "owner":false, 
    "priority":100 
  } 
]