Domain User

Type domainuser
Datastore Type domain
Supports authorities, permissions, transfer

Configuration

Domain Users 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.
email text The primary email address for the principal.
directoryId text The ID of the directory of the identity that holds this user's authentication credentials. The authentication credentials are not stored on the domain user object itself.
identityId text The ID of the identity that holds this user's authentication credentials. The authentication credentials are not stored on the domain user object itself.
invitedDomainId text If this user was invited from another domain, then this points back to the original user.
invitedPrincipalId text If this user was invited from another domain, then this points back to the original user.

Create a Domain User

You create a Domain User by passing in a configuration object that contains, at minimum, the name of the user being created. The name of the user must be unique across all principals in the domain. You cannot have two users 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 User:

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

// create a user
domain.createUser({
    "name": "ryount"
});

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

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 user
domain.createUser({
    "name": "ryount",
    "email": "ryount@brewers.com",
    "title": "Robin Yount",
    "description": "Center Fielder for the 1982 Milwaukee Brewers",
    "position": "cf"
});

Domain Users also support authentication. This means that they can authenticate to your cloud platform and your applications can provide safely store usernames and passwords while providing login services like password resets, email confirmations and the like.

It's easy to create a user with a password. Here's an example:

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

// create a user
domain.createUser({
    "name": "ryount",
    "email": "ryount@brewers.com",
    "password": "robin"
});

Update a Domain User

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

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

// update
user.set("title", "Legend of Rock");
user.update();

You can update any property you'd like from the domain user 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 User

You can delete a Domain User at any time. All memberships of the Domain User within Domain Groups will be cleaned up as well. If any Identities associated with a Domain User are no longer needed, they will also be cleaned up. Here is an example:

user.del();

Read a Domain User

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

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

// assume we have a user Id
var userId = "4b5b685c980c10f98beb";

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

List Domain Users

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

domain.listUsers();

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

domain.listUsers().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.listUsers({
    "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.

In addition, you can retrieve a full list of principals (both users and groups) by using a more generalized approach to list principals.

domain.listPrincipals({
    "limit": 10,
    "skip": 20,
    "sort": { "title": -1 }
}).each(function() {
    console.log("Domain Principal: " + this.getId() + " of type: " + this.get("type"));
});

Query Domain Users

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

domain.queryUsers({
    "position": "cf"
});

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

domain.queryUsers({
    "position": "cf"
}).each(function(id) {
    console.log("Found an Domain User: " + id + " with title: " + this.get("title"));
});

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.queryUsers({
    "position": "cf"
},{
    "limit": 10,
    "skip": 20,
    "sort": {
        "title": -1
    }
}).each(function(id) {
    console.log("Found an Domain User: " + id + " with title: " + this.get("title"));
});

In addition, you can query against the full set of principals (both users and groups) by using a more generalized approach to query principals.

domain.queryPrincipals({
    "position": "cf"
},{
    "limit": 10,
    "skip": 20,
    "sort": {
        "title": -1
    }
}).each(function(id) {
    console.log("Found an Domain Principal: " + id + " of type: " + this.get("type"));
});