With SCIM, a user is member of a set of groups (may be empty). For each group that the user is member of, the membership is represented with the existence of an membership object. The membership object has no required properties, but a set of optional properties.

Groups are objects with a few required properties, and some optional. Groups are organized into group types. All groups are of one and only one specific type.

Each group type specifies a set of syntax and semantics for both the group and the membership objects. VOOT pre-defines a set of group types for use in research and educational, however anyone may extend VOOT with new custom group types.

Limiting the number of groups

With VOOT we aim at reducing the number of groups a user is member of, to a controllable and usable list that the user can interact with. We foresee users beeing member of tens of groups rather than hundres or thousands. To allow for that without loosing neccessary information, VOOT encourage smart use of the membership object. Properties within the membership object may also be used for access control, where more fine grained and complex access decissions are needed.

Data types

VOOT makes use of the SCIM Attribute Data Types.

In addition VOOT specifies these data types:

Translatable String
The content may be eigther an untranslated basic string, in an undefined language. Alternatively, the content is an object with the property keys being ISO 639-1 Language Codes. The values is the translated values into that language.

Groups

Groups may have a set of users as members, each member of the group is represented with a membership object. All properties on the group object are the same for all members, and can be cached across users.

Required properties

id
A unique string identifier representing this group. This identifier shuold not be used by humans, only systems.
Datatype: SCIM String
displayName
is a translatable string giving the group a human friendly name. The name is supposed to give a clear meaning for users setting up access control.
Datatype: Translatable String

The simplest example of a group containing only required parameters:

{
	"id": "8878ae43-965a-412a-87b5-38c398a76569",
	"displayName": "Project on group APIs"
}

Optional properties

description
is a textual description of the group (optional). It may be translated as well.
Datatype: SCIM String
type
a pointer to a group type (optional). Default group is voot:default.
Datatype: SCIM String
notBefore
the group did not exist before this date.
Datatype: SCIM DateTime
notAfter
the group is deleted or not valid after this date.
Datatype: SCIM DateTime
public
is a boolean flag indicating whether the existence of this group and the basic group information is publicly available. Users may search and use groups in setting access control, even if they are not member of a group.
Datatype: SCIM Boolean
active
may be set to false to indicate that the group is currently inactive. It will cause the group to not show up on compact group lists.
Datatype: SCIM Boolean
sourceID
is an identifier that refer to the authorative source defining this group. This is useful when the VOOT Provider is merging information from a lot of different systems and passes this information on to the clients.
Datatype: SCIM String
membership
if used in the context of a user's membership to this group, the property may contain the embedded membership object. See below for more details about the membership object.

See examples of more complex groups

Memberships

The simplest representation of a group membership is an empty object, which tells that the user is member of the group, but does not give any more details than that:

{}

An optional property basic is recommended to use to indicate the most basic level of roles. For each group type, it should be described how the more complex role model within that group types are projected into the basic.

There are three legal values of basic:

  • member is regular members. This is the default role if no explicit value is provided.
  • admin is an abstract role of super members, having some kind of additional permissions. In example, the admin may invite or add
  • other members, moderate content in a group or anything else.
  • owner is given a special meaning in the Ad-Hoc scenario, where groups are created by a person, which then is the owner of the group.

The following properties are optional.

basic
The basic membership role of the current user (optoinal). Default value is member.
Datatype: SCIM String
displayName
A human readable description of the memership role.
active
may be set to false to indicate that the user is a passive member of the group. See group and membership states.
Datatype: SCIM Boolean
notBefore
the group did not exist before this date.
Datatype: SCIM DateTime
notAfter
the group is deleted or not valid after this date.
Datatype: SCIM DateTime
may
An object of permissions that a user may or may not have related to the group. In example a user may be allowed to edit, manage, invite or delete a group.
userId
If the membership object is used stand alone, and there is no implicit relation to a given user, the user may be referred to by using this property.
Datatype: SCIM String
groupID
If the membership object is used stand alone, and there is no implicit relation to a given group, the group may be referred to by using this property.
Datatype: SCIM String

Specific group types may define additional properties on the membership object.

An example of a membership may look like this:

{
	"basic": "admin",
	"displayName": {
		"en": "Teacher",
		"nb": "Lærer"
	},
	"course_role": 	"teacher",
	"notBefore": 	"2014-01-01T12:00:00Z",
	"notAfter": 	"2014-08-01T12:00:00Z",
	"active": 	true,
	"userId": "andreas@university.edu",
	"groupId": "courses:university_edu:m201"
}

Active and inactive groups and memberships

In order for access control to allow for users accessing old content, information about group relations that are not active any longer is supported. VOOT supports some features to represent such relations, without cluttering the interface when listing groups for users to manage access control for.

When listing currently active groups of a current user, we include groups that are active with membership that is active, where neither the group or membership is expired (with the notBefore or notAfter properties).

Group types

Group types defines commonalities between types of groups. The group type resource type will represent the type itself, mapping group type identifiers to display names and schemas.

Associated with each group type, there should be a well specified set of attribute for groups and memberships.

Required properties

id
A unique string identifier group type. If you are defining your own group types, make sure you use a local prefix.
Datatype: SCIM String
displayName
is a translatable string giving the group a human friendly name. The name is supposed to give a clear meaning for users setting up access control.
Datatype: Translatable String

An example of a membership may look like this:

{
	"id": "feide:courses",
	"displayName": {
		"en": "Course",
		"nb": "Emne"
	}
}