Domain Group

Type domaingroup
Datastore Type domain
Supports authorities, permissions, transfer

Configuration

Domain Groups maintain a configuration that you can adjust or consult as you create, update and query for them.

The following table presents you the configuration properties.

Property Type Default Read-Only Description
name text The name (i.e. the user id or account name) for the principal. This can be any text that you like. However, it must be unique across all users in the domain. For example, you cannot have two users in the domain with the name "joe".
type text Read-Only The type of principal - either USER or GROUP. This value is auto-populated upon creation.
authorities array [] An array of text describing the authorities that this user should be granted. This is customizable for your own use and describes server-scoped authorities. Cloud CMS does not use this array for any of its internal authority calculations against objects or data stores.

Cloud CMS makes this available for use with such frameworks as Spring Security or Ruby on Rails where the list of authorities can be consulted to determine rights against specific controllers or services at invocation time.

Create a Domain Group

You create a Domain Group by passing in a configuration object that contains, at minimum, the name of the group being created. The name of the group must be unique across all principals in the domain. You cannot have two groups with the same name in the same domain. Similarly, you cannot have a user and a group with the same name in the same domain.

Here is how you create a Domain Group:

// assume we have a domain
var domain = ...;

// create a group
domain.createGroup({
    "name": "brewers"
});

// we can also create a group using a more generalized method
domain.createPrincipal({
    "name": "brewers",
    "type": "group"
});

You can provide additional properties and also custom properties at the point of creation. Here is an example of you'd do that:

// assume we have a domain
var domain = ...;

// create a group
domain.createGroup({
    "name": "brewers",
    "title": "The Milwaukee Brewers",
    "description": "American League Champions 1982",
    "league": "national"
});

Update a Domain Group

To update, all you have to do is make changes to your Domain Group and fire away.

// assume we have a domain group
var group = ...;

// update
group.set("league", "national");
group.update();

You can update any property you'd like from the domain group except for the type. You cannot switch a group into a user or vice-versa. While both Domain Groups and Domain Users are Domain Principals, they're not interchangeable.

Delete a Domain Group

You can delete a Domain Group at any time provided that the group does not have any members. An error will be raised if you attempt to delete a group that has members.

Here is an example of group deletion:

group.del();

Read a Domain Group

You can read a Domain Group by its _doc ID field.

// assume we have a domain
var domain = ...;

// assume we have a group Id
var groupId = "4b5b685c980c10f98beb";

domain.readPrincipal(groupId).then(function() {
    console.log("Found Domain Group with ID: " + this.getId());
});

List Domain Groups

You can retrieve a list of Domain Groups for your domain quite easily. The following code hands back the full list.

domain.listGroups();

You can then iterate over the list to pick at what you'd like.

domain.listGroups().each(function() {
    console.log("Domain User title: " + this.get("title"));
});

Retrieving the full list is potentially an expensive operation, depending how many items you have. The more your retrieve, the more data goes over the wire and so forth. Thus, you might wish to paginate your call and retrieve a subset of the total list at a time.

Here is an example that retrieves in pages of size 10. It starts on the second page (by skipping to starting index 20). It also sorts by the title field in a descending sequence.

domain.listGroups({
    "limit": 10,
    "skip": 20,
    "sort": { "title": -1 }
}).each(function() {
    console.log("Domain User title: " + this.get("title"));
});

You don't have to have all of the pagination parameters (limit, skip and sort). You might only want to include one or two. It's up to you.

Query Domain Groups

You can run custom queries against your Domain Groups to find exactly what you're looking for. Here is a query that looks for Domain Users which are disabled.

domain.queryGroups({
    "league": "national"
});

Here is that same query followed by an iteration over the result map.

domain.queryGroups({
    "league": "national"
}).each(function(id) {
    console.log("Found an Domain Group: " + id + " with title: " + this.get("title"));
});

Finally, you can mix queries with pagination to reduce data over the wire and speed up performance. Here is that same query with some pagination thrown in. We limit to pages of size 10 and sort by title.

domain.queryGroups({
    "league": "national"
},{
    "limit": 10,
    "skip": 20,
    "sort": {
        "title": -1
    }
}).each(function(id) {
    console.log("Found an Domain Group: " + id + " with title: " + this.get("title"));
});

List Members of a Group

You can retrieve a list of the members of a group:

// assume we have a group
var group = ...;

// retrieve a list of members
group.listMembers().then(function() {
    console.log("Found a member: " + this.getId());
});

You can also elect to filter to retrieve only the members of type USER or GROUP.

// assume we have a group
var group = ...;

// retrieve a list of users
group.listMembers("user").then(function() {
    console.log("Found a member: " + this.getId());
});

// retrieve a list of groups
group.listMembers("group").then(function() {
    console.log("Found a member: " + this.getId());
});

When you retrieve membership for a group, you can either retrieve direct membership (just those members who are direct first-level members of the group) or you can retrieve indirect membership. Indirect memberships include principals who belong to intermediary groups which may belong to your group, at any depth in the hierarchy.

// assume we have a group
var group = ...;

// all direct members
group.listMembers(false).then(function() {
    console.log("Found a member: " + this.getId());
});

// all indirect members
group.listMembers(true).then(function() {
    console.log("Found a member: " + this.getId());
});

// all indirect groups
group.listMembers("group", true).then(function() {
    console.log("Found a member: " + this.getId());
});

You can also take advantage of pagination on retrieval. This reduces the payload of the requests and amount of data over the wire. Pagination serves to make your applications more efficient.

// assume we have a group
var group = ...;

// pagination
var pagination = {
    "limit": 10,
    "skip": 20,
    "sort": { "title": -1 }
};

// all indirect groups
group.listMembers("group", true, pagination).then(function() {
    console.log("Found a member: " + this.getId());
});

You may wish to use the following convenience functions when working with users or groups.

// assume we have a group
var group = ...;

// list users
group.listUsers().then(function() {
    console.log("Found a member: " + this.getId());
});

// list groups
group.listUsers().then(function() {
    console.log("Found a member: " + this.getId());
});

// list all indirect groups
group.listGroups(true, pagination).then(function() {
    console.log("Found a member: " + this.getId());
});

You can also list membership from the domain directly:

// assume we have a domain
var domain = ...;

// the group
var groupId = "4b5b685c980c10f98bec";

// pagination
var pagination = {
    "limit": 10,
    "skip": 20,
    "sort": { "title": -1 }
};

// all indirect groups
domain.listMembers(groupId, "group", true, pagination).then(function() {
    console.log("Found a member: " + this.getId());
});

Add Member to Group

You can add a member to a group:

// assume we have a group
var group = ...;

// assume we have a user
var user = ...;

// add as a member
group.addMember(user);

You can also do this from the domain:

// assume we have a domain
var domain = ...;

// assume we know what user and group we're interested in
var groupId = "4b5b685c980c10f98bec";
var userId = "4b5b685c980c10f98beb";

domain.addMember(groupId, userId);

Remove Member from Group

Or you can remove a member from a group:

// assume we have a group
var group = ...;

// assume we have a user
var user = ...;

// add as a member
group.removeMember(user);

You can also do this from the domain:

// assume we have a domain
var domain = ...;

// assume we know what user and group we're interested in
var groupId = "4b5b685c980c10f98bec";
var userId = "4b5b685c980c10f98beb";

domain.removeMember(groupId, userId);