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.
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.
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.
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 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!
The Auth Module provides a number of APIs to manage users and contexts.
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
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;
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
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;
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
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;
Delete a user
PARAMS
RETURNS
REQUIRED ROLES
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;
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
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;
Return the number of the users defined in the system
PARAMS
RETURNS
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
Returns a single User-Context base on UserContextID
PARAMS
RETURNS
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