Authentication strategies
SharePoint client
Samples
Sandbox
Permissions
Managing roles and objects permissions
Permissions management is an important part of business logic which can be met in worker processes and workflows.
Let's explore how Gosip Fluent API wraps up SharePoint securable object and permissions.
First of all, by securable objects mean any SharePoint artifacts which can be configured with unique permissions: webs, lists, libraries, items, etc.
Fluent API scopes role operations under
.Roles() method.Checking is an object has unique permissions
1
item := list.Items().GetByID(1)
2
hasUniqueAssignments, err := item.Roles().HasUniqueAssignments()
3
if err != nil {
4
log.Fatal(err)
5
}
6
7
fmt.Printf("Has unique permissions: %t\n", hasUniqueAssignments)
Copied!
Breaking role inheritance
To assign unique permissions to an object its role inheritence must be broken.
1
item := list.Items().GetByID(1)
2
if err := item.Roles().BreakInheritance(true, false); err != nil {
3
log.Fatal(err)
4
}
5
6
// where the first argument stands for `copyRoleAssigments`
7
// - if true the permissions are copied from the current parent scope
8
// second argument is `clearSubScopes`
9
// - true to make all child securable objects inherit role assignments
10
// from the current object
Copied!
Be aware that abusing breaking role inheritence and having too many unique permissions can have a detrimental effect on SharePoint performance. The architecture of a solution which involves many unique permissions has too be planned carefully. See some valuable recommendations.
Role definitions
Before assigning permissions it's important to know how to get role definitions.
A role definition is a collection of rights bound to a specific object. Role definitions (for example, Full Control, Read, Contribute, Design, or Limited Access) are scoped to the Web site and mean the same thing everywhere within the Web site, but their meanings can differ between sites within the same site collection. Role definitions can also be inherited from the parent Web site, just as permissions can be inherited.
Definitions are csoped as Web level in
.RoleDefinitions() quariable collection.1
def, err := sp.Web().RoleDefinitions().GetByType(api.RoleTypeKinds.Contributor)
2
if err != nil {
3
log.Fatal(err)
4
}
Copied!
Definitions can be gotten by Definition ID, Name or Type. We recommend using OOTB definitions and getting them by types. There is an enumerator-like helper for default types
api.RoleTypeKinds.Getting principals
Principal is site user or group, their IDs are used in roles assignments. Principal ID can be received by requesting UIL (User Information List), getting site user/group by name/email, etc.
1
roup, err := sp.Web().SiteGroups().GetByName("Process Users").Get()
2
if err != nil {
3
log.Fatal(err)
4
}
5
6
fmt.Printf("Principal ID: %d\n", group.Data().ID)
7
8
// or
9
10
user, err := sp.Web().SiteUsers().GetByEmail("[email protected]").Get()
11
if err != nil {
12
log.Fatal(err)
13
}
14
15
fmt.Printf("Principal ID: %d\n", user.Data().ID)
Copied!
It's in preference to operate on groups level and grant permissions to a specific users as little as possible.
Adding role assignments
The role assignment is the relationship among the role definition, the users and groups, and the scope (for example, one user may be a reader on list 1, while another user is a reader on list 2). The relationship expressed through the role assignment is the key to making SharePoint security management role-based.
At last, now we are ready for roles assigment. 😜 Who told permissions is simple?
1
if err := item.Roles().AddAssigment(group.Data().ID, def.ID); err != nil {
2
log.Fatal(err)
3
}
Copied!
Removing role assignments
Removing role assignments is just the same as adding but in opposite.
1
if err := item.Roles().RemoveAssigment(group.Data().ID, def.ID); err != nil {
2
log.Fatal(err)
3
}
Copied!
Reseting roles inheritance
To reset permissions inheritance:
1
item := list.Items().GetByID(1)
2
if err := item.Roles().ResetInheritance(); err != nil {
3
log.Fatal(err)
4
}
Copied!
After reseting object roles assigments its permissions are again inherited from the parent object.
Getting collection objects' permissions
When dealing with OData collection of objects with unique permissions OData items' role assigment can be requested using
RoleAssignments, also HasUniqueRoleAssignments can be used in moderation.Please be aware thatHasUniqueRoleAssignmentsis a heavy property that creates workload on a SharePoint server and better be used at minimal.
Try not abusing it by potential requests to large lists getting a bunch of items.
1
// Getting all lists with role assigments details
2
res, err := sp.Web().Lists().
3
Select(`
4
Title,
5
RoleAssignments/Member/*,
6
RoleAssignments/RoleDefinitionBindings/*
7
`).
8
Expand(`
9
RoleAssignments/Member,
10
RoleAssignments/RoleDefinitionBindings
11
`).
12
Get()
Copied!
RoleAssigments if any applied contains an array of objects.1
var lists []*struct {
2
Title string
3
RoleAssignments []*api.RoleAssigment
4
}
5
6
// .Normalized() method aligns responses between different OData modes
7
if err := json.Unmarshal(res.Normalized(), &lists); err != nil {
8
log.Fatalf("unable to parse the response: %v", err)
9
}
Copied!
Assigments is a Member and binded RoleDefinitions:
1
// RoleAssigment role asigments model
2
type RoleAssigment struct {
3
Member *struct {
4
LoginName string
5
PrincipalType int
6
}
7
RoleDefinitionBindings []*RoleDefInfo
8
}
Copied!
Base permissions
BasePermissions is permissions representation with Low and High pair. Don't panic if API returns only BasePermissions ({ "High": "2147483647", "Low": "4294705151" }), using HasPermissions helper it's simple to check if it includes required permissions kind:1
// User effective base permissions
2
effectiveBasePermissions := api.BasePermissions{
3
High: 432,
4
Low: 1011030767,
5
}
6
7
hasPerm := api.HasPermissions(
8
effectiveBasePermissions,
9
api.PermissionKind.EditListItems)
Copied!
Summary
Now we know how to treat SharePoint permissions using Gosip and Fluent API. Before wrapping up, we want to stress on importance of careful planning of permissions model, as less unique permissions is better.
Last modified 2yr ago