Permissions API Data Structures and Operations

Owned by Chris Hyzer
Last updated: Mar 22, 2011Version comment
2 min read

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

PermissionResource {
  uri    id
  string uuid
  string displayName
  string description
}

PermissionResourceLookup {
  uri    id
  string uuid
}

PermissionAssignment {
  PermissionResourceLookup permissionResourceLookup
  String action
  Subject subject
}
  • id: Globally unique ID in URI format (Namespace TBD). Recommended to be constructed from a local prefix concatenated to the GMS permission name. Should not change, but if it does subject to renaming considerations, described below. Permitted characters as per RFC 2141. Max length 1024.
  • uuid: Globally unique ID in UUID format (regex is ^[a-f0-9]{32}$). Max length 32.
  • displayName: Human readable name. Should be unique within a GMS, but not required. May change. May include folder structure. Max length 1024. Permitted characters TBD.
  • description: Human readable description. Free form. Max length 1024. Permitted characters TBD.

Availability

Mandatory.

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.

Permission Operations

hasPermission()

boolean hasPermission(PermissionResourceLookup permissionResourceLookup, Subject subject, String action, enum immediacy=any)

Input

  • permissionResourceLookup: PermissionResourceLookup object
  • subject: Subject object
  • action: XXX ?
  • immediacy: Constraint on search for subject as an immediate, nonimmediate, or any type of assignment XXX?

Output

  • true if subject has the specified permission, false otherwise

Availability

Mandatory.

getMembers()

SubjectList getMembers(PermissionResourceLookup permissionResourceLookup, String action, enum immediacy=any)

Input

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

Output

Availability

Mandatory.

getPermissionsForMember()

PermissionAssignmentList getPermissionsForMember(Subject subject, String action, enum immediacy=any)

Input

  • 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 Permission Assignments

Availability

Mandatory.

assignPermission()

boolean assignPermission(PermissionResourceLookup permissionResourceLookup, String action, Subject subject, bool addOnly=false)

Input

  • permissionResourceLookup: 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 assignment is successfully added or if addOnly is false and subject is already assigned to permissionID and action, false otherwise.

Availability

Optional. Data store may be read-only.

unassignPermission()

boolean unassignPermission(PermissionResourceLookup permissionResourceLookup, String action, Subject subject, bool addOnly=false)

Input

  • permissionResourceLookup: PermissionResourceLookup object
  • action: qualifies the assignment
  • subject: Subject object
  • removeOnly: If true, unassignPermission() fails if subject is already not assigned to of permissionID for that action.

Output

  • true if assignment is successfully removed or if addOnly is false and subject is already assigned to permissionID and action, false otherwise.

Availability

Optional. Data store may be read-only.

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)