Scroll

User Identification

Exago does not have native user authentication. User logins must be handled in a security layer in the embedding application. After a user logs in, the application should pass identification parameters to the Exago API, which you can use to set permissions.

userId and companyId

Exago has two built-in parameters which are used to store identifying information: userId and companyId. These parameters are used in conjunction with the Schedule Manager and User Preferences, and they are automatically passed to any extensions which may need to access authentication. Folder Management, External Interface, Scheduler Queue, and any extension which can access sessionInfo (such as Assembly Data Sources or Server Events) can retrieve these parameters in relevant methods.

Often userId corresponds with a unique user or log-in, and companyId represents a group of users with shared characteristics. Either parameter can be used without the other.

Setting the current user

The Id parameters are not instantiated by default, and must be created before use. They can be created in the Admin console, config file, or in the API code. They must be created with the exact names of "userId" and "companyId" (which are case sensitive), with data type "string". Since the values are set in the API, if you create the parameters in the Admin Console or config, they should have blank default values.

Admin Console

As created in the Admin Console:

admin_console.png

Config File

As created in the config file:

<parameter>
<id>userId</id>
<data_type>string</data_type>
<value />
<hidden>True</hidden>
<prompt_text />
</parameter>
<parameter>
<id>companyId</id>
<data_type>string</data_type>
<value />
<hidden>True</hidden>
<prompt_text />
</parameter>

.NET API

As created in the .NET API:

NOTE. "DataType" defaults to DataType.String, so the call is omitted.
Parameter userId = api.Parameters.NewParameter();
userId.Id = "userId";
userId.Value = "user_224";

Parameter companyId = api.Parameters.NewParameter();
companyId.Id = "companyId";
companyId.Value = "company_17";

REST API

As created in the REST API:

NOTE. "DataType" defaults to "String", so the call is omitted.

POST /parameters

{
"Id": "userId",
"Value": "user_224"
...
}

POST /parameters

{
"Id": "companyId",
"Value": "company_17"
...
}

Basic sandboxing

Setting the userId and companyId parameters has several effects in the Exago interface.

Schedule Manager

By default, the schedule manager will show only schedules belonging to the current userId. This can be changed by modifying the following Admin Console setting:

( Scheduler Settings Scheduler Manager User View Level ) <schedulemanagerviewlevel>

  • Current User ('User'): Filters schedules by current userId parameter.
  • All Users in Current Company ('Company'): Filters schedules by current companyId parameter.
  • All Users in All Companies ('All'): No filtering.

This setting can also be overridden by a Role.

User Preferences

User preferences, including Startup Reports and User Reports (live report customization), are set by userId, and will only apply to that user.

Advanced permissions

userId and companyId can be used in many other application areas in order to handle security permissions.

Roles

Additional permissions are typically handled by Roles. A check can be made in the API which maps the current userId and/or companyId to the role which it belongs. This must be handled manually via a lookup table or a similar data structure. Then activate the role for the session.

.NET: api.Roles.GetRole("admin").Activate();

REST: PATCH /REST/Roles/admin?sid={sid} { "IsActive": true }

For more information, see Roles.

Tenanting

userId and companyId can be used as tenant parameters in your data objects.

If your data is set up such that each table, view and stored procedure has columns that indicate which user has access to each row, then you can use userId and/or companyId to match these columns and act as data row filters. (For this purpose, the parameters cannot be set to 'hidden').

For more information, see Multi-Tenant Environment Integration.

Accessing Ids in extensions

userId and companyId are passed to any custom extensions where relevant. For example, in an external interface assembly, you may wish to access the userId in order to log user executions. You could do so by implementing the ReportExecuteStart method, which passes the userId parameter.

public static void ReportExecuteStart(string companyId, string userId, string reportName)
{
string logText = string.Format("{0}: Report '{1}' executed by user '{2}'.", DateTime.Now, reportName, userId);

File.AppendAllText(logFile, logText + Environment.NewLine);
}

This would return the following text upon a report execution by userId "Alex":

2017-03-07 14:50:49: Report 'Test\Product Sales Report' executed by user 'Alex'.

Most extensions have methods which can access userId and companyId. In addition, the parameters are accessible through sessionInfo. So any extensions which can access sessionInfo can also access userId and companyId, even if methods do not explicitly implement them.

The following server event automatically adds the userId to the description text whenever a report is saved.

Global Event Type: OnReportSaveStart, References: WebReports.Api.Reports

Report report = sessionInfo.Report;
string userId = sessionInfo.UserId;
if (!report.Description.EndsWith(userId)) { report.Description += ("\n" + userId); }
return null;

Hidden Article Information

Article Author
Exago Development
created 2017-03-01 18:48:06 UTC
updated 2017-03-07 20:22:59 UTC

Labels
parameters, permissions, userId, companyId, user preferences, schedule manager,
Have more questions? Submit a request