Create a user, a role and assign the role to the user

Out of the box Cosmos framework comes with a set of RESTful APIs to manipulate objects. The GET, POST, PUT and DELETE http methods are used to manipulate objects. Those are treated as read, insert, update and delete respectively. The data, where applicable, is sent as JSON objects in the request body of the request. There are some predefined role and role group objects out of the box. Other than those the default APIs and sample front end project can be used to create/read/edit/delete any object in the system. Developers should be able to create javascript application to manipulate any object on the server without writing any server side code.

Create a user

The object name for default user store is cosmos.users. To create a user an administrator must have access to this object like any other object. User, like any other object, can be added using a POST request to the endpoint /service/cosmos.users/. Two fields must be present for any user to login: username and password. But a user will typically also have an email address and a list of roles assigned. Here is a sample object:

{
    "username":"scientist",
    "password":"secret",
    "email":"scientist@copotron.com",
    "roles":[]
}

When this object is posted the password field will be replaced by the cosmos.users preprocessor and convert it to hmac value of the password and add "hmac:" at the start before saving to database. If the password is already hashed and the value starts with "hmac:" it will not be converted again. But without the "hmac:" the value will be converted for both POST and PUT methods. When we get the user back using GET method it will be something like:

{
  "username": "admin",
  "email": "admin@cosmosframework.com",
  "roles": [
    "43425097-e630-41ea-88eb-17b339339706"
  ],
  "password": "hmac:1ddb4e6b0b810f59018babbb5dc0eed4",
  "createtime": "2014-06-28 19:07:16.127194",
  "_id": "53af74d48c66ab119e60c2d7",
}

The _id field is the string representation of the mongodb ObjectId identifier for this item in the object collection and we can use this value while using PUT method.

Create a role

The object name for default role store is cosmos.rbac.object.role. An administrator may POST following object to create a role:

{
    "name": "TestRole", 
    "role_items": [
        {
            "access": [
                "INSERT", 
                "READ", 
                "WRITE", 
                "DELETE"
            ], 
            "object_name": "testservice", 
            "property_name": "*", 
            "type": "object.RoleItem"
        }
    ], 
    "sid": "984fdf54-0096-4a95-adff-4c791ad240ed", 
    "type": "object.Role"
}

The role_items is an array of access role. role_items.access is an array of access type for this role item. The role_items.object_name creates access for the named object and role_items.property_name creates access for the property of the object. These two can be think of as table/field combination in database terms. Either of them can be set to * which will match all objects or property. You should be careful while assigning this to role_items.object_name. By default the builtin SYSTEM user has set both of the fields to wild card access. The sample role above gives access to all fields of testservice object to the user who is assigned this role.

Note here that you may assign a sid while creating the role object, but this is optional. The role object has a preprocessor which will assign this automatically if it is left empty.

Assign a role to a user

An administrator can create a user roles[] assigned using POST method or later can use PUT method to update the role. Here in our example since we have created the user first without any role we will use PUT method to update the roles of the user. The endpoint has for the user object will be /service/cosmos.users/53af74d48c66ab119e60c2d7/. The value 53af74d48c66ab119e60c2d7 is the same _id of the users mongodb ObjectId. And the body of the request will be:

{
  "roles": [
    "43425097-e630-41ea-88eb-17b339339706"
  ]
}

We use the sid value of the role (or rolegroup). When the roles for the user is updated the user can now perform operations given by the access on the object and property.

We will discuss about more advanced role access where you can allow permission using field name instead of widcard access and more advanced access like address.city in the next article.