Improving docs about how to use permissions

Hi, I am trying to understand how the new permissions feature work, but I am not really understanding the documentation. I think these things should be improved:

• It is not clear enough how the special tables __Class, Permission, _Realm, _Role are related to each other. This would be usefull to check on realm studio if the code written to manage permission have created the proper data in the proper place. From what I understand there must exist a role, to this role I need to link the belonging member , and that role must then be linked to a permission(which holds the information about what is permitted)

Now it’s not very clear what needs to be done with that permission:

Realm level permission

I see this piece of code on the sample for Realm level permissions

 // Create the role
let readOnlyRole role = realm.createObject('__Role', { name: 'read-only' });
​
// Add the user to the role
let user = getUser();
readOnlyRole.members.push(user);
​
// Create a new permission object for the role and add it to the Realm
// permissions
let permission = realm.createObject('__Permission', { 'role': role, 'canRead': true, 'canQuery': true });

And then there is

let realmPermissions = realm.objects('__Realm');
realmPermissions.permissions.push(permission);

Now: the variable realmPermissions is used like an object, but shouldn’t it be an array? Do you mean that in order to add a realm level permission, I need to push a permission on the permissions field of a row of __Realm table?

Class level permission

On the Class level permission sample instead, after the code which creates the role and the permission, there is this code:

let realmPermissions = realm.objects('__Class');
realmPermissions.permissions.push(permission);

Again, the variable realmPermissions is used like an object, but shouldn’t it be an array?? Do you mean that in order to apply a class level permission to a class named MyClass I need to add a permission object to the permissions field of the row having in the name column the value MyClass

Object level permission

This is the most difficoult part to understand: first of all on the docs you say that in order to have object permissions, a __Permissions[] field must be created on the table whose objects you want to control with object level permissions, but this fields is not then used in the sample. In fact, after the code which create the role and the permission, there is this code:

 let objectPermissions = realm.objects('__Class').filtered(`class_name = 'Person'`)[0];
objectPermissions.permissions.push(permission);

Except for the fact that the objectPermissions variable is used like an object but it should be an array, why are you querying the __Class table to add object level permission? I thin the way to add object level permission, would be to add a permission object to the __Permissions field previously mentioned in the docs, isn’t it right?

The other question is:

• What the name column on the __Roles table is used for? Is it just used to allow querying this table? Or is it subject to some kind of naming convenction?

Goals

Clearly understand how permissions work

Actual Results

It is not very clear how to use permissions

[bmunkholm]

Thanks @apperside - thats gold! We will ensure to get that better explained shortly.

[jdevng]

Hi @cmelchior,

In the role section, the code

// Making changes to a Role requires a write transaction
let user = getUserId();
try! realm.write {
  role.users.append(user)
}

In Swift, xCode doesn’t recognize the function “getUserId()” and if I use SyncUser.current, I get the following error:

Cannot convert value of type ‘SyncUser?’ (aka ‘Optional<RLMSyncUser>’) to expected argument type ‘PermissionUser’

So if I go to the PermissionUser docs, which isn’t mentioned on that page, it indicates PermissionUser has an identity and a role. I’m assuming the ‘role’ is an attempt to obfuscate the identity, but not sure why they are together. If I use the following code, I get a segfault. It looks like it’s trying to create a User, but complains about the parameter not being a PermissionUser. The User exists from SyncUser. current, but is an unacceptable parameter.

    let someItem = SomeItem()
    someItem.name = name
    
    let permissionRole = PermissionRole()
    permissionRole.name = "<Unique Prefix>" + name

    
    let permissionUser = PermissionUser()
    permissionUser.identity = (SyncUser.current?.identity)!
    // is permissionUser.role set automatically?
    
    try! self.realm?.write {
        self.realm?.add(someItem)
        self.realm?.add(permissionRole)
        permissionRole.users.append(permissionUser) // segfault here
    }

Terminating app due to uncaught exception ‘RLMException’, reason: 'Attempting to create an object of type ‘__User’ with an existing primary key value

There is some connection between SyncUser.current, User, PermissionUser that really isn’t clear, and getUserId() doesn’t exist. I’d assume getUserId would return the identity.

Basically what I’m trying to do is create an object, a role for that object with a unique prefix, and then add the current user as the ‘first’ member of the role that has forthcoming permissions.