Page Comparison

Permissions Data Structures

Introduction

A permission is an assignment to a subject of a resource and action.  e.g. the subject is John Smith, the action is READ, and the resource is org1234.

Permission objects

PermissionPermissionResource {
  uri    id
  string uuid
  string displayName
  string description
}

PermissionLookupPermissionResourceLookup {
  uri    id
  string uuid
}

PermissionAssignment {
 PermissionLookup PermissionResourceLookup permissionLookuppermissionResourceLookup
  String action
  Subject subject
}

...

Renaming Considerations

When a permission resource is renamed, future retrievals of the old name (id) may result in an indication that the permission resource has moved and the id of the new name. To access a new group at the old name, the request must be qualified.

...

boolean hasPermission(PermissionLookupPermissionResourceLookup permissionLookuppermissionResourceLookup, Subject subject, String action, enum immediacy=any)

Input

• permissionLookuppermissionResourceLookup: PermissionLookup PermissionResourceLookup object
• subject: Subject objectpermissionLookup
• action: PermissionLookup objectXXX ?
• immediacy: Constraint on search for subject as an immediate, nonimmediate, or any member type of groupassignment XXX?

Output

• true if subject is an immediate or nonimmediate member (as specified) of group has the specified permission, false otherwise

Availability

...

SubjectList getMembers(PermissionLookupPermissionResourceLookup permissionpermissionResourceLookup, String action, enum immediacy=any)

Input

• permissionLookuppermissionResourceLookup: PermissionLookup PermissionResourceLookup object
• action: Action qualifier
• immediacy: Constraint on search for subject as an immediate, nonimmediate, or any member of group

...

• subject: Subject object
• action: (optional) qualifies the permission
• immediacy: Constraint on search for subject as an immediate, nonimmediate, or any member of the relevant groups

Output

• List of Group objectsPermission Assignments

Availability

Mandatory.

...

assignPermission()

PermissionAssignmentListboolean getGroupsForPermissionassignPermission(SubjectPermissionResourceLookup subjectpermissionResourceLookup, String action, enum privilege)

Input

...

Subject

...

Output

• List of Group objects for which subject has privilege

Availability

Mandatory.

addMember()

boolean addMember(GroupLookup group, Subject subject, bool addOnly=false)

Input

• grouppermissionResourceLookup: GroupLookup PermissionResourceLookup object
• action: qualifies the assignment
• subject: Subject object
• addOnly: If true, addMember() fails if subject is already a member of groupID.

Output

• true if subject assignment is successfully added or if addOnly is false and subject is already a member of groupIDassigned to permissionID and action, false otherwise.

Availability

Optional. Data store may be read-only.

...

unassignPermission()

boolean addPrivilegeunassignPermission(GroupLookupPermissionResourceLookup grouppermissionResourceLookup, SubjectString subjectaction, enumSubject privilegesubject, bool addOnly=false)

Input

• grouppermissionResourceLookup: GroupLookup PermissionResourceLookup object
• subject: Subject object
• privilege: Type of privilege to be added (privileges TBD)
• addOnly: If true, addPrivilege() fails if subject alreody has privilege for groupID.

Output

• true if privilege is successfully added or if addOnly is false and subject alreody has privilege for groupID, false otherwise.

Availability

Optional. Data store may be read-only.

removeMember()

boolean removeMember(GroupLookup group, Subject subject, boolean removeOnly=false)

Input

• group: GroupLookup object
• subjectaction: qualifies the assignment
• subject: Subject object
• removeOnly: If true, removeMemberunassignPermission() fails if subject is already not a member of groupIDassigned to of permissionID for that action.

Output

• true if subject assignment is successfully removed or if removeOnly addOnly is false and subject is not a member of groupIDalready assigned to permissionID and action, false otherwise.

Availability

Optional. Data store may be read-only.

removePrivilege()

boolean removePrivilege(GroupLookup group, Subject subject, enum privilege, boolean removeOnly=false)

Input

• group: GroupLookup object
• subject: Subject object
• privilege: Type of privilege to be added (privileges TBD)
• removeOnly: If true, removePrivilege() fails if subject does not have privilege for groupID.

Output

• true if privilege is successfully removed or if removeOnly is false and subject does not have privilege for groupID, false otherwise.

Availability

Optional. Data store may be read-only.

saveGroup()

Group saveGroup(Group group)

Input

• group: Group object. If group:id and group:uuid are blank, a new group is being requested.

Output

• Group object holding group id/uuid (possibly newly assigned).

Availability

Optional. Data store may be read-only.

deleteGroup()

urn deleteGroup(GroupLookup group, boolean deleteOnly=false)

Input

• group: GroupLookup object
• deleteOnly: If true, deleteGroup() fails if group does not exist.

Output

• true if group is successfully deleted or if deleteOnly is false and group does not exist, false otherwise.

Availability

Optional. Data store may be read-only.

findGroups()

List<Group> findGroups(List<GroupLookup> groupLookups, urn folder, enum folderDepth=one|sub,
                       List<enum> fieldNames=urn|displayName|description, String fieldSearchString,
                       String wildcard, boolean splitStringOnWhitespace, boolean caseSensitive)

Input

• groupLookups: list of group lookups to find.  max 100.
• folder: (optional): if results should be constrained in a certain folder
• folderDepth: (required if folder set): "one" for results directly in the folder, "sub" for results in the folder or subfolders
• fieldNames: (optional): if searching by a substring of a field, can be urn|displayName|description.  Note, if multiple are set, then the search string could be in any of the fields.
• fieldSearchString: (required if fieldName set): this is the search string to find groups.  Can contain caller-specified wildcards.
• wildcard: (optional, can only be set if fieldName is set): if not set, there is no wildcard in the search.  If set, can be one or more chars, and this found in the fieldSearchString will be treated as a wildcard.  Note there is no way to escape this wildcard, so client should pick something not otherwise being searched
• splitStringOnWhitespace: (required if fieldName set): if true, then any whitespace in the fieldSearchString will cause the search to be split on whitespace, and and'ed together.  
• caseSensitive: (required if fieldName set): if true then the search string should be checked as is, if false then should be case-sensitive

Note, either or multiple of the groupLookups or folder or fieldNames needs to be set

For example, if the folder URN is: urn:group:school/apps/confluence
and the folderDepth is: sub
and the search string is: *english* *dept*
and the wildcard is: *
and the fieldNames are: urn and displayName
and caseSensitive is: false
and splitStringOnWhitespace is: true

Then the query run will get all groups the caller is allowed to see in the school/apps/confluence folder or subfolders, that have "english" and "dept" somewhere in the urn or displayName case insensitive.

Output

• List of Group objects

Availability

Mandatory

Questions

TODO

...

• Identifier mapping: uuid, eppn, eptid, uid/username, openid
• Standard attributes from eduperson
• Need to reconcile how application ID's fit with "person's"

...

Example of using permissions API for Group privileges

Part of the namespace would be reserved for fifer.  e.g. to see if someone can see the membership of a group:

hasPermission("permission:edu:permission:fifer:groupPrivileges:groups:some:group", "12345678", "READ", "any")

There would be some specified actions and what they mean, e.g. READ means can see permission assignments (and implies VIEW), VIEW means can see the permission exists, ADMIN means can rename / delete / edit the privilege (and implies READ, VIEW, and UPDATE), UPDATE means can assign/unassign the permissions (and implies VIEW)