Permissions
When you develop a chat app, you might want to set rules that let only selected users access specific channels and user metadata. You can set up a detailed permission schema for your application and decide who can do what with your data. This way, you secure and protect your application against unauthorized third-party access attempts.
For example, you can let only specific users modify public channel information or profiles of other chat users. You can also let only admins remove users from channels for offensive behavior.
Unreal Chat SDK, as a purely client-side library, doesn't do anything specific to handle such permissions internally, apart from imposing some limits through client-side errors:
- The allowed channel membership (direct, group, or public channel types).
- Availability of specific features in public chats (you'll get errors when implementing such Unreal Chat SDK features as typing indicator, invites, or read receipts).
Still, you can use the cryptographic, token-based permission administrator from PubNub called Access Manager to impose strict access rules for PubNub resources in your app.
We recommend that you use Unreal SDK's Access Manager for server-side operations although you any PubNub SDK that supports Access Manager will do.
Required configuration
Before you start using Access Manager, you must configure your app:
-
Enable Access Manager on your app's keyset in the Admin Portal.
-
Initialize the Unreal SDK:
- With the
Secret Key
on your servers to secure your PubNub instance.Secret Key
is a shared secret between your application's server and PubNub and it's used to administer Access Manager permissions for your client applications by signing and verifying the authenticity of messages and requests. Read Moderation for examples.
Secret key security
The Secret Key
should only be used within a secure server and never exposed to client devices. If the Secret Key
is ever compromised, it can be an extreme security risk to your application. If you suspect your Secret Key
has been compromised, you can generate a new Secret Key
for the existing PubNub keyset on the Admin Portal.
- Initialize the Unreal Chat SDK (
Init()
):
- With the
Auth Key
on your clients to authenticate users in your application and grant them access to PubNub resources (other users' metadata and channels). Read Moderation for examples.
Use Access Manager
To implement access rules in your app, refer to Access Manager API using these Unreal SDK methods:
-
GrantToken()
to generate a time-limited authorization token with an embedded access control list.Channel group limitation
Unreal Chat SDK doesn't support channel groups, so you can only set permissions for the channels and users.
-
RevokeToken()
to disable an existing token and revoke all permissions embedded within. -
ParseToken()
to decode an existing token and return the object containing permissions embedded in that token. -
SetToken()
to update the authentication token granted by the server.
Resource permissions
You can use Access Manager in the Unreal SDK to define what operations (like read
, write
, or get
) your chat app users can do with such PubNub resources as channels (channels
) and other users' metadata (uuids
):
Resource type | Permissions |
---|---|
channels | read , write , get , manage , update , join , delete |
uuids | get , update , delete |
Read the Moderation documentation to learn how you can mute and ban users in your chat app and secure these restrictions with Access Manager.
Check for permissions
You can use the AccessManager->CanI()
method to check if the current user has permissions for particular operations on a specific resource. For more information, refer to Token permissions.
Operations-to-permissions mapping
The type of access level you grant on a given resource type defines which operations users can perform in your app. For example, write
access given to a user for the channels
resource type (either specific channels or channel patterns
) lets them send messages to this channel/these channels (calling the PubNub Pub/Sub API underneath and the Unreal Chat SDK's SendText()
method).
The following tables show how specific permissions granted to PubNub resources translate to operations users can later perform in a chat app.
Pub/Sub
PubNub operation | Resource type(s) | Permission | Unreal Chat SDK method(s) |
---|---|---|---|
Publish on channels | channels | write | Send text messages (SendText() ) Send messages with referenced channels and user mentions ( Send() ) Forward messages ( Forward() , ForwardMessage() ) Create and send events ( EmitEvent() ) Report messages ( Report() ) |
Send signals to channels | channels | write | Typing indicator methods Create and send events ( EmitEvent() ) |
Subscribe to channels | channels | read | Typing indicator methods Receive events ( ListenForEvents() ) Receive messages ( Connect() ) Membership updates ( StreamUpdates() , StreamUpdatesOn() ) Channel updates ( Update() , UpdateChannel() ) Messages updates ( StreamUpdates() , StreamUpdatesOn() ) User updates ( StreamUpdates() , StreamUpdatesOn() ) |
Subscribe to presence channels | Presence channels (<channel-name>-pnpres ) | read | n/a |
Unsubscribe from channels | channels | None required | Stop receiving typing signals, events, messages, updates on membership, channels, messages, and users |
Presence
PubNub operation | Resource type(s) | Permission | Unreal Chat SDK method(s) |
---|---|---|---|
Here Now | channels | read | Channel presence (WhoIsPresent() ) |
Where Now | channels | None required | Channel presence (WherePresent() , IsPresentOn() , IsPresent() ) |
Message Persistence
PubNub operation | Resource type(s) | Permission | Unreal Chat SDK method(s) |
---|---|---|---|
Fetch historical messages | channels | read | GetHistory() |
Message counts | channels | read | Unread messages (GetUnreadMessagesCount() , GetUnreadMessagesCounts() ) |
Delete messages | channels | delete | Delete() |
App Context
PubNub operation | Resource type(s) | Permission | Unreal Chat SDK method(s) |
---|---|---|---|
Set user metadata | uuids | update | Create users (CreateUser() ) Update user metadata ( Update() , UpdateUser() ) |
Delete user metadata | uuids | delete | DeleteUser() , Delete() |
Get user metadata | uuids | get | Get user data (GetUser() ) Track mentions ( ListenForEvents() ) |
Get all user metadata | uuids | You don't need to specify permissions to enable it if you uncheck the Disallow Get All User Metadata option in the App Context configuration in the Admin Portal. | chat.GetUsers() |
Set channel metadata | channels When working with threads, also grant permissions to PUBNUB_INTERNAL_THREAD channels. | update , get | Create channels (CreateDirectConversation() , CreateGroupConversation() , CreatePublicConversation() ) Update channels ( Update() , UpdateChannel() ) Pin messages ( Pin() , PinMessage() ) Threads ( CreateThread() , PinMessage() , PinMessageToParentChannel() , PinToParentChannel() , UnpinMessage() , UnpinMessageFromParentChannel() , UnpinFromParentChannel() ) |
Delete channel metadata | channels | delete | Delete() , DeleteChannel() |
Get channel metadata | channels | get | Get channel details (GetChannel() ) Get pinned messages ( GetPinnedMessage() ) Get thread ( GetThread() ) |
Get all channel metadata | channels | You don't need to specify permissions to enable it if you uncheck the Disallow Get All Channel Metadata option in the App Context configuration in the Admin Portal. | chat.GetChannels() |
Set channel members | channels | manage | Invite multiple users to channels (InviteMultiple() ) Mute/Ban users ( SetRestrictions() ) |
Remove channel members | channels | manage | Unmute/Unban users (SetRestrictions() ) |
Get channel members | channels | get | Get members (GetMembers() ) Check restrictions ( GetUserRestrictions() , GetUsersRestrictions() , GetChannelsRestrictions() , GetChannelRestrictions() ) |
Set channel memberships | channels , uuids | join on channels update on uuids | Create channels (CreateDirectConversation() , CreateGroupConversation() ) Invite a user to a channel ( Invite() ) Join channels ( Join() ) Update membership ( Update() ) Unread messages ( SetLastReadMessage() , MarkAllMessagesAsRead() ) |
Remove channel memberships | channels , uuids | join on channels update on uuids | Leave channels (Leave() ) |
Get channel memberships | uuids | get | List channels (GetChannels() ), GetMemberships() |
Message Reactions
PubNub operation | Resource type(s) | Permission | Unreal Chat SDK method(s) |
---|---|---|---|
Add message reaction | channels | write | ToggleReaction() |
Remove message reaction | channels | delete | ToggleReaction() |
Get history with reactions | channels | read | GetHistory() |