isnode-mod-identity v0.1.2

ISNode Identity Module

Introduction

This is just a module for the ISNode Framework. To learn how to use the framework, we strongly suggest obtaining a copy of the Hello World example.

The Identity module provides a complete Role-Based Access Control system for the applications that you build. This includes management (CRLDD - Create/Read/List/Details/Delete) for permissions, roles and users, as well as the ability to sign in, sign out, manage sessions, check token validity and associated permissions, change user password and more.

It is intended that it will operate in one of two modes - Local or Remote, however Local is the only mode that is supported in the current version. Local mode manages the business logic for all methods - locally within the application server. Whereas Remote mode relies on an Identity Server that many services may connect to. Therefore Remote mode supports logic like single sign-on between services.

Configuration and Instantiation

Before we look at the methods that are made available by the identity module, you should understand how to configure and instantiate it. Configuration is done on a service by service basis within the service definition file (service.json). An example of such configuration is as follows:

  "identity": {
    "enabled": true,
    "access": "local",
    "databaseConnections": [
      {
        "name": "identity",
        "driver": "mongodb",
        "host": "localhost",
        "database": "identity"
      }
    ]
  }

As can be seen in the above example, you must set "enable" to "true" to enable the identity module. Further - currently the only "access" method supported is a "local" database. This will be extended in the future to support a "remote" ISNode identity service, and possibly other identity services such as AWS "cognito", Microsoft's "active-directory" and more.

Once configured, you must instantiate the module. This should usually occur within the init() method of your root controller, so that the identity module is instantiated at application server startup:

;!function(undefined) {

	var ctrl = {};
	var isnode = null;
	var identity = null;
	var service = null;

	/**
	 * Initialises the controller
	 * @param {object} isnodeObj - The parent isnode object
	 */
	ctrl.init = function(isnodeObj){
		isnode = isnodeObj;
		identity = isnode.module("identity");
		if(service.cfg().identity && identity){
    		identity.instantiate("service", "example", function(err, res){
    			if(!err) { identity = res.instance; }
    		});
		}
	}
}();

Methods

instance(name)

Synchronous Function. Returns an existing instance of the Identity service. Must be called following instantiation within all other controllers that you wish to access that identity module instance from.

Input Parameters:

1. name - (String) Common Name of the identity service

Returns: (Object) An Identity Service object

ConfigObj example

	ctrl.identity = isnode.module("identity").instance("abcsports");

instantiate(type, service, cb)

Asynchronous Function. Creates a new instance of the Identity service and returns it in a callback function.

Input Parameters:

1. type - (String) "server" (shared amongst all services on the current application server) or "service" (specific to one service on the server)
2. service - (String) Only specified where type is "service". This is the name of the service to attach the Identity instance to.
3. cb - (Function) Callback function with two parameters - "error" and "response". If successfully instantiated, the Identity instance object will be available within the response object - "response.instance".

Returns: N/A

Use Example

	isnode.module("identity").instantiate("service", "abcsports", function(err, res){
		ctrl.identity = res.instance;
	});

instance.general

A collection of general methods related to Identity.

instance.general.checkPermission(permissions, userKey, cb)

Asynchronous Function. Checks if a user has one or more defined permissions.

Input Parameters:

1. permissions - (String/Array) The permission common name to check against user (or can be an array of permission names)
2. userKey - (String) The user primary key to check against
3. cb - (Function) Callback function with two parameters - "error" and "response".

Returns: N/A

Use Example

	ctrl.identity.general.checkPermission(["View_All_Users", "View_Own_User"], "4389h4389h249hg2", function(err, res){
		if(res && res.permissions.includes("View_All_Users")){
			console.log("Defined User Has View_All_Users Permission");
		} 
		if (res && res.permissions.includes("View_Own_User")) {
			console.log("Defined User Has View_Own_User Permission");
		} 
		if(!res || !res.permissions) {
			console.log("Defined User Has No Permissions Specified", err);
		}
	})

instance.general.checkToken(token, permissions, cb)

Asynchronous Function. Checks if token is for a valid signed in session. Can also check if session token is associated with a user that has one or more defined permissions at the same time. This is usually called as the first method on controller/page load. The above method (checkPermission) is not normally called directly.

Input Parameters:

1. token - (String) The session token
2. permissions - (String/Array) Can be a string if you're just checking one permission (eg; "View_All_Users") or an array if you're checking many permissions (eg; "View_All_Users", "View_Own_User").
3. cb - (Function) Callback function with two parameters - "error" and "response".

Returns: N/A

Use Example

	ctrl.identity.general.checkToken(token, ["View_All_Users", "View_Own_User"], function(err, res){
		if(res && res.permissions.includes("View_All_Users")){
			console.log("User Is Signed In And Has View_All_Users Permission");
		} 
		if (res && res.permissions.includes("View_Own_User")) {
			console.log("User Is Signed In And Has View_Own_User Permission");
		} 
		if(!res) {
			console.log("User is not signed in", err);
		}
	})

instance.general.signIn(email, password, cb)

Asynchronous Function. Sign a user in to the system using an email address and password.

Input Parameters:

1. email - (String) User's email address
2. password - (String) User's password
3. cb - (Function) Callback function with two parameters - "error" and "response".

Returns: N/A

Use Example

	ctrl.identity.general.signIn("john@gmail.com", "password", function(err, res){
		if(res){
			console.log("User Signed In Successfully. Token - " + res.token);
		} else {
			console.log("Error Signing User In", err);
		}
	})

instance.general.signOut(token, cb)

Asynchronous Function. Sign a user out of the system, given their session token.

Input Parameters:

1. token - (String) User's session token
2. cb - (Function) Callback function with two parameters - "error" and "response".

Returns: N/A

Use Example

	ctrl.identity.general.signOut("43h9gh4938gh492h", function(err, res){
		if(res){
			console.log("User Signed Out Successfully");
		} else {
			console.log("Error Signing User Out", err);
		}
	})

instance.permission

instance.permission.create(permObj, optionsObj, cb)

Asynchronous Function. Creates a new permission.

Input Parameters:

1. permObj - (Object/Array) Permissions Object. Defines the permission that is being created. Can also define an array of permissions objects.
2. optionsObj - (Object) Options Object
3. cb - (Function) Callback function with two parameters - "error" and "response".

Returns: N/A

Use Example

	var permObj = [
		{
			"label": "View_All_Users",
			"description": "Allows user to view all users"
		},
		{
			"label": "View_Own_User",
			"description": "Allows user to view own user"
		}
	];
	var optionsObj = {
		"appId": "1234-1234-1234-1234",
		"service": "abcsports"
	};
	ctrl.identity.permission.create(permObj, optionsObj, function(err, res){
		if(res){
			console.log("Permission Created Successfully");
		} else {
			console.log("Error Creating Permission", err);
		}
	})

instance.permission.delete(query, cb)

Asynchronous Function. Deletes an existing permission

Input Parameters:

1. query - (Object) Permission query (child string of "key" supported)
2. cb - (Function) Callback function with two parameters - "error" and "response".

Returns: N/A

Use Example

	var query = {"key": "g823g328g93r"};
	ctrl.identity.permission.delete(query, function(err, res){
		if(res){
			console.log("Permission Deleted Successfully");
		} else {
			console.log("Error Creating Permission", err);
		}
	})

instance.permission.details(query, cb)

Asynchronous Function. Returns details of a defined permission

Input Parameters:

1. query - (Object) Permission query (child string of "key" supported)
2. cb - (Function) Callback function with two parameters - "error" and "response".

Returns: N/A

Use Example

	var query = {"key": "g823g328g93r"};
	ctrl.identity.permission.details(query, function(err, res){
		if(res){
			console.log("Fetched Permission Details Successfully", res);
		} else {
			console.log("Error Creating Permission", err);
		}
	})

instance.permission.list(searchQuery, cb)

Asynchronous Function. Returns a list of permissions that meet defined search criteria

Input Parameters:

1. searchQuery - (Object) The search query object
2. cb - (Function) Callback function with two parameters - "error" and "response".

Returns: N/A

Use Example

	// Returns all permissions associated with defined role in the abcsports service:

	var query = {
		"service": "abcsports",
		"roleKey": "427gt8tg827gt"
	};
	ctrl.identity.permission.list(query, function(err, res){
		if(res){
			console.log("Fetched Permission List Successfully", res);
		} else {
			console.log("Error Creating Permission", err);
		}
	})

instance.permission.update(query, permissionObj, cb)

Asynchronous Function. Updates an existing permission. Not yet implemented.

Input Parameters:

1. query - (Object) The permission to update (child string of "key" supported)
2. permissionObj - (Object) The object containing fields to update within the permission
3. cb - (Function) Callback function with two parameters - "error" and "response".

Returns: N/A

Use Example

	var query = {"key": "782gt329gt392"}
	var permissionObj = {
		"label": "New_Permission_Label"
	};
	ctrl.identity.permission.update(query, permissionObj, function(err, res){
		if(res){
			console.log("Fetched Updated Successfully");
		} else {
			console.log("Error Creating Permission", err);
		}
	})

instance.role

instance.role.addPermissions(associationObj, optionsObj, cb)

Asynchronous Function. Adds one or more permissions to one or more roles.

Input Parameters:

1. associationObj - (Object/Array). One or more role-permission association objects
2. optionsObj - (Object) The options object
3. cb - (Function) Callback function with two parameters - "error" and "response".

Returns: N/A

Use Example

	var assocObjects = [
		{
			"role": "Administrator",
			"permissions": ["View_All_Users", "View_Own_User"]
		},
		{
			"role": "Member",
			"permissions": ["View_Own_User"]
		}
	];
	var options = {
		"appId": "1234-1234-1234-1234",
		"service": "abcsports"
	};
	ctrl.identity.role.addPermissions(assocObjects, options, function(err, res){
		if(res){
			console.log("Permissions Added Successfully");
		} else {
			console.log("Error Adding Permissions to Roles", err);
		}
	})

instance.role.connectToService(query, service, cb)

Asynchronous Function. Connects a floating role to a service. Not Yet Implemented.

Input Parameters:

1. query - (Object). The role query (child string of "key" supported)
2. service - (String) The service name
3. cb - (Function) Callback function with two parameters - "error" and "response".

Returns: N/A

Use Example

	var query = {"key": "24ut329th2392"}
	ctrl.identity.role.connectToService(query, "abcsports", function(err, res){
		if(res){
			console.log("Role Connected To Service Successfully");
		} else {
			console.log("Error Connecting Defined Role to Service", err);
		}
	})

instance.role.create(roleObjs, optionsObj, cb)

Asynchronous Function. Creates a new role

Input Parameters:

1. roleObjs - (Object/Array). A role definition object, or array of these objects
2. optionsObj - (Object) The options object
3. cb - (Function) Callback function with two parameters - "error" and "response".

Returns: N/A

Use Example

	var roles = [
		{
			"label": "Administrator",
			"description": "Admin Role"
		},
		{
			"label": "Member",
			"description": "Member Role"
		}
	];
	var options = {
		"appId": "1234-1234-1234-1234",
		"service": "abcsports"
	};
	ctrl.identity.role.create(roles, options, function(err, res){
		if(res){
			console.log("Roles Created Successfully");
		} else {
			console.log("Error Creating Roles", err);
		}
	})

instance.role.delete(query, cb)

Asynchronous Function. Deletes an Existing Role

Input Parameters:

1. query - (Object). The role query (containing child string of "key")
2. cb - (Function) Callback function with two parameters - "error" and "response".

Returns: N/A

Use Example

	var query = {"key": "24ut329th2392"}
	ctrl.identity.role.delete(query, function(err, res){
		if(res){
			console.log("Role Deleted Successfully");
		} else {
			console.log("Error Deleting Role", err);
		}
	})

instance.role.details(roleKey, cb)

Asynchronous Function. Fetches details for a defined role

Input Parameters:

1. query - (Object). The role query (containing child string of "key")
2. cb - (Function) Callback function with two parameters - "error" and "response".

Returns: N/A

Use Example

	var query = {"key": "24ut329th2392"}
	ctrl.identity.role.details(query, function(err, res){
		if(res){
			console.log("Role Details Fetched Successfully", res);
		} else {
			console.log("Error Fetching Role Details", err);
		}
	})

instance.role.disconnectFromService(roleKey, cb)

Asynchronous Function. Disconnects a role from a service. Not yet implemented.

Input Parameters:

1. query - (Object). The role query (containing child string of "key", "id" or "label")
2. service - (String). The name of the service the role is currently connected to
3. cb - (Function) Callback function with two parameters - "error" and "response".

Returns: N/A

Use Example

	var query = {"key": "24ut329th2392"}
	ctrl.identity.role.disconnectFromService(query, "abcsports", function(err, res){
		if(res){
			console.log("Role Disconnected From Service Successfully");
		} else {
			console.log("Error Disconnecting Role From Service", err);
		}
	})

instance.role.list(query, cb)

Asynchronous Function. Fetches a list of roles based on a search query.

Input Parameters:

1. query - (Object). The search query object
2. cb - (Function) Callback function with two parameters - "error" and "response".

Returns: N/A

Use Example

	var query = {
		"service": "abcsports",
		"roles": [
			"Administrator",
			"Member"
		]
	};
	ctrl.identity.role.list(query, function(err, res){
		if(res){
			console.log("Role List Returned Successfully", res);
		} else {
			console.log("Error Fetching List of Roles", err);
		}
	})

instance.role.removePermissions(roleQuery, permissionQuery, cb)

Asynchronous Function. Removes a permission from a role. Not yet implemented.

Input Parameters:

1. roleQuery - (Object). The role query object (contains child strings of "key", "id" or "label")
2. permissionQuery - (Object/Array). The permission query object or array of such objects (contains child strings of "key", "id" or "label")
3. cb - (Function) Callback function with two parameters - "error" and "response".

Returns: N/A

Use Example

	var roleQuery = {"key": "34ttg4g43g3"};
	var permissionQuery = {"key": "244g244t23t32"};
	ctrl.identity.role.removePermissions(roleQuery, permissionQuery, function(err, res){
		if(res){
			console.log("Permission removed from role successfully");
		} else {
			console.log("Error removing permission from role", err);
		}
	})

instance.role.update(query, role, cb)

Asynchronous Function. Updates a role. Not yet implemented.

Input Parameters:

1. query - (Object). The key of the role
2. role - (Object). The role object
3. cb - (Function) Callback function with two parameters - "error" and "response".

Returns: N/A

Use Example

	var query = {
		"key": "34ttg4g43g3"
	};
	var role = {
		"label": "New_Role_Label",
		"description": "We are updating the label and description of this role"
	}
	ctrl.identity.role.update(query, role, function(err, res){
		if(res){
			console.log("Role Updated Successfully");
		} else {
			console.log("Error Updating Role", err);
		}
	})

instance.user

instance.user.addRoles(user, roles, options, cb)

Asynchronous Function. Associates one or more roles with a user.

Input Parameters:

1. user - (Object). The user object (containing a reference of user.key or user.id)
2. roles - (String/Array). The role name as a string, or an array of role names to associate with the user
3. options - (Object). The options object
4. cb - (Function) Callback function with two parameters - "error" and "response".

Returns: N/A

Use Example

	var roles = ["Member", "Contributor"];
	var user = {"key": "24t89ht248ht2"};
	var options = {
		"service": "abcsports",
		"appId": "1234-1234-1234-1234"
	};
	ctrl.identity.user.addRoles(user, roles, options, function(err, res){
		if(res){
			console.log("Roles Added to User Successfully");
		} else {
			console.log("Error Adding Roles to User", err);
		}
	})

instance.user.changePassword(changeObj, cb)

Asynchronous Function. Changes a user's password.

Input Parameters:

1. changeObj - (Object). The change object (see examples below)
2. cb - (Function) Callback function with two parameters - "error" and "response".

Returns: N/A

Use Example

	var changeObjExampleOne = {
		"userKey": "h8249th2389ht2",
		"oldPassword": "oldpassword"
		"newpassword": "newpassword"
	};
	var changeObjExampleTwo = {
		"token": "f2f398hf3298h92a",
		"newpassword": "newpassword"
	};
	ctrl.identity.user.changePassword(changeObjExampleOne, function(err, res){
		if(res){
			console.log("Password Changed Successfully");
		} else {
			console.log("Error Changing Password", err);
		}
	})

instance.user.connectToService(query, service, cb)

Asynchronous Function. Associates a user with a service.

Input Parameters:

1. query - (Object). The user query object (child strings of "id", "key" or "email")
2. service - (String). The name of the service
3. cb - (Function) Callback function with two parameters - "error" and "response".

Returns: N/A

Use Example

	ctrl.identity.user.connectToService("7238gt8327gt832", "abcsports", function(err, res){
		if(res){
			console.log("User Associated With Service Successfully");
		} else {
			console.log("Error Associating User With Service", err);
		}
	})

instance.user.create(user, cb)

Asynchronous Function. Creates a new user.

Input Parameters:

1. user - (Object). A new user definition object
2. cb - (Function) Callback function with two parameters - "error" and "response".

Returns: N/A

Use Example

	var user = {
		"firstName": "John",
		"lastName": "Smith",
		"companyName": "ABC Sports",
		"emailAddress": "john@gmail.com",
		"password": "password",
		"service": "abcsports":
		"appId": "1234-1234-1234-1234"
	};
	ctrl.identity.user.create(user, function(err, res){
		if(res){
			console.log("New User Created Successfully");
		} else {
			console.log("Error Creating New User", err);
		}
	})

instance.user.delete(query, cb)

Asynchronous Function. Deletes an Existing User.

Input Parameters:

1. query - (Object). The User Query Object. Contains child strings of "key", "id" or "email"
2. cb - (Function) Callback function with two parameters - "error" and "response".

Returns: N/A

Use Example

	var query = {"id": "1234"}
	ctrl.identity.user.delete(query, function(err, res){
		if(res){
			console.log("User Deleted Successfully");
		} else {
			console.log("Error Deleting User", err);
		}
	})

instance.user.deleteChangePasswordToken(query, cb)

Asynchronous Function. Deletes a change password token from the system. Not Implemented.

Input Parameters:

1. query - (Object). The change query object. Can contain child string of "token" (eg; "changeObj.token = 4278g28g2932f9h2")
2. cb - (Function) Callback function with two parameters - "error" and "response".

Returns: N/A

Use Example

	var changeObj = {"token": "4278g28g2932f9h2"};
	ctrl.identity.user.deleteChangePasswordToken(query, function(err, res){
		if(res){
			console.log("Change Password Token Deleted Successfully");
		} else {
			console.log("Error Deleting Change Password Token", err);
		}
	})

instance.user.details(query, cb)

Asynchronous Function. Returns details of a specified user.

Input Parameters:

1. query - (Object). The user query object (child string of "id", "key" or "email")
2. cb - (Function) Callback function with two parameters - "error" and "response".

Returns: N/A

Use Example

	var query = {"email": "john@gmail.com"};
	ctrl.identity.user.details(query, function(err, res){
		if(res){
			console.log("User Details Returned Successfully", res);
		} else {
			console.log("Error Fetching User Details", err);
		}
	})

instance.user.disconnectFromService(query, service, cb)

Asynchronous Function. Disassociates a user from a service.

Input Parameters:

1. query - (Object). The user query object (child string of "id", "key" or "email")
2. service - (String). The name of the service to disassociate the user from
3. cb - (Function) Callback function with two parameters - "error" and "response"

Returns: N/A

Use Example

	var userObj = {"email": "john@gmail.com"};
	ctrl.identity.user.disconnectFromService(query, "abcsports", function(err, res){
		if(res){
			console.log("User Disassociated From Service Successfully", res);
		} else {
			console.log("Error Disassociating User From Service", err);
		}
	})

instance.user.generateChangePasswordToken(changeObj, cb)

Asynchronous Function. Generates a Change Password Token.

Input Parameters:

1. changeObj - (Object). The change object (child strings of "userKey", "service", "appId")
2. cb - (Function) Callback function with two parameters - "error" and "response"

Returns: N/A

Use Example

	var changeObj = {
		"userKey": "h4289th298ht2",
		"service": "abcsports",
		"appId": "1234-1234-1234-1234"
	};
	ctrl.identity.user.generateChangePasswordToken(changeObj, function(err, res){
		if(res){
			console.log("Change Password Token Generated Successfully - " + res.token);
		} else {
			console.log("Error Generating Change Password Token", err);
		}
	})

instance.user.list(query, cb)

Asynchronous Function. Returns a list of users within the callback function, based on a search query.

Input Parameters:

1. query - (Object). The search query object
2. cb - (Function) Callback function with two parameters - "error" and "response"

Returns: N/A

Use Example

	var query = { "service": "abcsports" };
	ctrl.identity.user.list(query, function(err, res){
		if(res){
			console.log("User List Returned Successfully", res);
		} else {
			console.log("Error Returning User List", err);
		}
	})

instance.user.removeRoles(query, roles, cb)

Asynchronous Function. Removes one or more roles from a user. Not Yet Implemented.

Input Parameters:

1. query - (Object). The user query object (child strings of "key", "id" or "email")
2. cb - (Function) Callback function with two parameters - "error" and "response"

Returns: N/A

Use Example

	var query = { "email": "john@gmail.com" };
	var roles = [
		{"label": "Member"},
		{"label": "Contributor"}
	]
	ctrl.identity.user.removeRoles(query, roles, function(err, res){
		if(res){
			console.log("Roles Removed From User Successfully", res);
		} else {
			console.log("Error Removing Roles from User", err);
		}
	})

instance.user.update(query, user, cb)

Asynchronous Function. Updates an Existing User.

Input Parameters:

1. query - (Object). The user query object (child strings of "key", "id" or "email")
2. user - (Object). The user field definition object
3. cb - (Function) Callback function with two parameters - "error" and "response"

Returns: N/A

Use Example

	var query = { "email": "john@gmail.com" };
	var user = {
		"emailAddress": "john@myowndomain.com"
	};
	ctrl.identity.user.update(query, user, function(err, res){
		if(res){
			console.log("User Updated Successfully", res);
		} else {
			console.log("Error Updating User", err);
		}
	})