Auth Module

Introducing the Auth Module

The Auth Module is a powerful DMSContainer built-in job provided in “the box”. The Auth Module allows to handle users and authentication in a centralized way.

Authentication

The Auth Module uses JWT to do users authentication and authorization. The login method return a token valid for the next 30 minutes. The token is just a string. After 30 minutes the token must be renewed issuing another login call. Any other method but login, requires a valid token as the first parameter. To renew a not expired token if available the refresh method which returns the same token passed in as parameter but with an extended validity.

Available roles

There are 4 roles available for users. A user can have 0 or any combination of roles.

ADMIN Can create users, can invoke all the monitoring methods even for monitoring other users, can send message impersonating other users. Can filter messages by RQL.

MONITOR Can invoke all the monitoring methods even for monitoring other users. Cannot filter messages by RQL. Cannot send messages.

SENDER Can send messages for itself and can monitor its own messages.

REPORT It can generate all kind of reports.

EVENT READER/WRITER: it can access or write event on Event Stream Module queues

A user can have any combination of these roles, even no roles is ok. If a user has no roles defined then cannot use the built-in modules but can still use the SSO facilities.

SSL_VERSION

The SSL version depends by the user’s SMTP provider and can be one of these: SSLv2, SSLv23, SSLv3, TLSv1, TLSv1_1, TLSv1_2

DMSAdminGUI

DMSAdminGUI is an handy tool provided with all editions of DMSContainer used to manage users, senders, context and SSO contexts (only in the professional version). It can run run on the same machine where DMSContainer is running or in a remote one, however must be able to communicates directly with the JSON-RPC interface of the job email.

The following users are already defined in the system:

Username Roles Password
user_admin admin pwd1
user_monitor monitor pwd1
user_sender sender pwd1

Change default passwords ASAP!

Auth Module APIs

The Auth Module provides a number of APIs to manage users and contexts.

Login

Allows to log in into the system. Returns a token that must be used in all the subsequent calls.

PARAMS
username: The username of the user that is trying to login to the system
password: The password of the user

RETURNS
token: The token that must be used for the subsequent requests

REQUIRED ROLES: 
none

Example

This example uses the DMVCFramework units.

var
  lReq: IJSONRPCRequest;
  lResp: IJSONRPCResponse;
begin
  lReq := TJSONRPCRequest.Create(1234, 'login');
  lReq.Params.Add('user_sender');
  lReq.Params.Add('pwd1');
  lResp := fRPCExecutor.ExecuteRequest(lReq);

  // Client must store the token and use in the subsequent requests
  Token := lResp.ResultAsJSONObject.S['token'];
end;

CreateUser

Creates a new user

PARAMS
username: The username of the new user (must match the following regex `^[a-zA-Z_0-9]{4,40}$`)
password: The password of the new user
roles: A comma separated values containing one or more of the following values: admin,monitor,sender

RETURNS
userid: The userid assigned to the new user

REQUIRED ROLES
admin

Example

var
  lReq: IJSONRPCRequest;
  lResp: IJSONRPCResponse;
  lJSON: TJsonObject;
begin
  lReq := TJSONRPCRequest.Create(1234, 'createuser');
  lReq.Params.Add(fToken);
  lJSON := TJsonObject.Create;
  lJSON.S['username'] := 'myuser';
  lJSON.S['pwd'] := 'mypwd';
  lJSON.S['roles'] := 'sender,monitor';
  lReq.Params.Add(lJSON);
  lResp := fExecutor.ExecuteRequest(lReq);
  ShowMessage('Created user ' + lJSON.S['username'] + ' with id ' + lResp.ResultAsJSONObject.I['userid'].ToString);
end;

UpdateUser

Updates an user

PARAMS
token: A valid token
userid: The userid of the user to modify
obj: A json object with al least one of the following properties: username, pwd, roles

RETURNS
none

REQUIRED ROLES
admin

Example

var
  lReq: IJSONRPCRequest;
  lResp: IJSONRPCResponse;
  lJSON: TJsonObject;
  lUserID: Integer;
begin
  lUserID := 99;
  lReq := TJSONRPCRequest.Create(1234, 'updateuser');
  lReq.Params.Add(fToken);
  lReq.Params.Add(lUserID);
  lJSON := TJsonObject.Create;
  lReq.Params.Add(lJSON);

  // only the field present in the json will be updated. You can also change only the pwd or the roles...
  lJSON.S['pwd'] := 'mynewpwd';
  lJSON.S['roles'] := 'admin,monitor';
  lResp := fExecutor.ExecuteRequest(lReq);
  ShowMessage('User updated, refresh list to check');
end;

DeleteUser

Delete a user

PARAMS

  • token: A valid token
  • userid: The userid of the user to delete

RETURNS

  • none

REQUIRED ROLES

  • admin

Example

var
  lUserID: Integer;
  lNotification: IJSONRPCNotification;
begin
  lUserID:= 99;
  lNotification := TJSONRPCNotification.Create('DeleteUser');
  lNotification.Params.Add(FToken);
  lNotification.Params.Add(lUserID, TJSONRPCParamDataType.pdtLongInteger);
  fRPCExecutor.ExecuteNotification(lNotification);  
  ShowMessage('User deleted');
end;

GetUsers

Return the users defines in the system

PARAMS
token: A valid token
obj: A json object with a property "rql" containing the RQL filter. If "rql" is empty, all the users will be returned (max record count = 100)

RETURNS
items: a json array of json object containing the users

REQUIRED ROLES
admin

Example

var
  lReq: IJSONRPCRequest;
  lResp: IJSONRPCResponse;
  lJSONParam: TJsonObject;
begin
  lReq := TJSONRPCRequest.Create(1234, 'getusers');
  lReq.Params.Add(fToken);
  lJSONParam := TJsonObject.Create;
  try
    lJSONParam.S['rql'] := ''; //empty returns all the users, max record count = 100
    lReq.Params.Add(lJSONParam);
  except
    lJSONParam.Free;
    raise;
  end;
  lResp := fExecutor.ExecuteRequest(lReq);
  ListOfUsersAsJSONArray := lResp.ResultAsJSONObject.A['items'];
end;

GetUsersCount

Return the number of the users defined in the system

PARAMS

  • token: A valid token
  • obj: A json object with a property “rql” containing the RQL filter. If “rql” is empty, will be returned the number of users defined in the system.

RETURNS

  • “users_count”: an integer users count

EXAMPLE

//Request
{
  "jsonrpc":"2.0",
  "id":1234,
  "method":"GetUsersCount",
  "params":["<token>", {"rql":"contains(username,\"user_\")"}]
}

//Response
{
    "jsonrpc": "2.0",
    "id": 1234,
    "result": {
        "users_count": 3
    }
}

REQUIRED ROLES

  • admin

GetUserContext

Returns a single User-Context base on UserContextID

PARAMS

  • token: A valid token
  • UserContextID: The id which identifies the relation betweeb context and user.

RETURNS

  • obj: The UserContext - raises exception if UserContext not found.

EXAMPLE

//Request
{
  "jsonrpc":"2.0",
  "id":1234,
  "method":"getusercontext",
  "params":["<token>",1]
}

//Response
{
    "jsonrpc": "2.0",
    "id": 1234,
    "result": {
        "contextname": "ctx1",
        "username": "user_admin",
        "contextdata": null,
        "id": 1,
        "iduser": 3,
        "idcontext": 1,
        "systemdata": {},
        "userdata": {}
    }
}

REQUIRED ROLES

  • admin