Security for Audit Activities
Activities on a ThingWorx Platform take place in the context of a user, in particular the security context of a user. A user can be a person invoking a service on a Thing or it can be a ThingWorx Connection Server accessing the platform to deliver inbound messages from edge devices. Both of these users operate in a defined security context that consists of permissions assigned to the user. There are permissions for design time and run time.
* 
For information on auditing a switch in security context, refer to Auditing the Switching of Security Context .
ThingWorx Permissions
Security for entities in ThingWorx involves setting the following permissions:
Design Time permissions — Control which User Groups and Users can create, read, update, and delete entities.
Runtime permissions — Control which User Groups and Users can access data, execute services, and trigger events on a Thing, including Data Tables, Streams, and Users. You can set runtime permissions at a Thing, Thing Template, or entities collection level. The abstract entities, Thing Shapes, Data Shapes, and User Groups in the model, do not have runtime permissions.
Visibility permissions — Define which Organization and organization units have access to view an entity. If the members of an Organization or organizational units do not have visibility access, they cannot view the entity in the entity list or search results. They also cannot be assigned read, write, subscribe, and other permissions within visibility rights.
Use Cases and Permissions Required
The use cases, what users need to see, and the permissions they require include the following:
Users who are meant to see all audit entries, in the same way as an Administrator can, should be added to the user group created by following the steps outlined in the section below, Required Permissions for a Non-Admin to Run Audit Services.
Users who are meant to see all audit entries associated with a particular Thing should be added to the Auditors user group and given runtime permissions to the QueryAuditHistory service on the Thing as well as visibility and runtime permissions on the Thing.
Users who are meant to see only audit entries within their user context should be given runtime permissions to the QueryAuditHistory service on the Thing as well as runtime permissions and visibility to the Thing.
For the v.9.0.0 of the ThingWorx Platform, a user group called "Auditors" has been added to assign permissions to non-administrative users. For more information, refer to the next section..
Permissions for Administrators and Auditors User Groups
By default, users in the Administrators group have full permissions to everything in ThingWorx, including the audit subsystem, its services, and data. By default, users in the Auditors group can see the audit entries created by other users when running the QueryAuditHistiory service on a Thing. For non-administrator users and user groups, administrators need to grant the ability to invoke the services provided by the audit subsystem, using service overrides. For details on how to use service overrides. refer to Service Overrides.
By default, users in the Administrators group have permissions to the following entities related to the audit subsystem:
Audit subsystem, which is a system object that exposes the following services in both implementations:
Service Execute — QueryAuditHistory run against the audit subsystem
Service Execute — ArchiveAuditHistory
Service Execute — ExportAuditData
Service Execute — CleanupOfflineAudit
Service Execute — GetAuditEntryCount
Service Execute — PurgeAuditData
Service Execute — ExportOnlineAuditData
Service Execute — ArchiveAuditHistoryDirectPersistence
Service Execute — QueryAuditHistoryWithQueryCriteria
Service Execute — QueryAuditHistoryrun against a Thing
AuditArchiveFileRepository, which is the file repository of the audit subsystem that is used for the audit archives. Created on startup of the subsystem, the repository has a directory for the currently active implementation. If you switch from one implementation to the other, the audit data from the previously active implementation is preserved and a new directory for the currently active implementation is created. The structure of the repository looks similar to the following in an installation where both implementations have been active:
Depending on the active implementation, one of two schedulers for archiving audit data:
AuditArchiveScheduler, which is a Scheduler Thing that controls the automated archiving of audit entries for the Data Table implementation.
AuditArchiveSchedulerDirectPersistence, which is a Scheduler Thing that controls the automated archiving of audit entries for the Direct Persistence implementation.
AuditPurgeScheduler, which is a Scheduler thing that controls the automated purging of online audit entries.
AuditArchiveCleanupScheduler, which schedules the clean-up of offline, archived audit data files.
AuditArchiveCleanupNotificationScheduler, which sends reminder notifications of the clean-up.
Required Permissions for Non-Admin Users
The table below shows the permissions that may be granted to non-administrator users in a user group so that they may access these audit subsystem entities.
* 
Be sure not to give non-admin users permission to edit objects at design time. For administrators, do not edit system objects at design time. If you edit them at design time, you risk losing any changes made during an upgrade.
Required Permissions to Audit Entities for a Non-Admin User Group
Entity
Permissions for a Non-Admin User Group
Audit Subsystem
To allow non-admin users and user groups to invoke the QueryAuditHistory, QueryAuditHistoryWithQueryCriteria, ArchiveAuditHistory, ExportAuditData, ExportOnlineAuditData,CleanupOfflineAudit, PurgeAuditData, GetAuditEntryCount, and ArchiveAuditHistoryDirectPersistence services:
Audit Subsystem — Design Time > Read.
Audit Subsystem — Run Time > Property, Service, or Event Overrides. Define a service override for each service that you want users in the group to be able to invoke and add a Service Execute for each service.
AuditArchiveFileRepository
Permissions for the AuditArchiveFileRepository of the audit subsystem, should NOT be granted to non-admin users or user groups.
AuditArchiveScheduler (Data Table implementation)
Users in the Administrators group should have access to this scheduler Thing. The scheduler Thing has a property, called lastArchivedTime, that is updated after every successful run of an archive operation. While it is possible, this property should NEVER be updated by a user, admin or non-admin. For this reason (and others that your organization may have), it is recommended that non-admin users NOT be granted access to the scheduler.
AuditArchiveSchedulerDirectPersistence
Users in the Administrators group should have access to this scheduler Thing. The scheduler Thing has a property, called lastArchivedTimeDirectPersistence, that is updated after every successful run of an archive operation. While it is possible, this property should NEVER be updated by a user, admin or non-admin. For this reason (and others that your organization may have), it is recommended that non-admin users NOT be granted access to the scheduler.
AuditPurgeScheduler
Only users in the Administrators group should have access to this scheduler Thing. It is recommended that non-admin users NOT be granted access to this scheduler.
AuditArchiveCleanupScheduler
Only users in the Administrators group should have access to this scheduler Thing. It is recommended that non-admin users NOT be granted access to this scheduler.
AuditArchiveCleanupNotificationScheduler
For non-admin users to execute the notification of cleanup service:
AuditArchiveCleanupNotificationSchedulerDesign Time > Read
AuditArchiveCleanupNotificationSchedulerRun Time > Property, Service, or Event Overrides. Define a service override for this service ( Service Execute).
In general, to allow non-admin users in a user group to invoke services of the audit subsystem, a user group should be created and the following permissions should be granted to the user group:
Audit Subsystem — Visibility permissions
Audit Subsystem — Design time permissions — allow read
Audit Subsystem Runtime permissions — Define a service override for each service that you want users in the group to be able to invoke, and allow Service Execute.
The following table lists the permissions that need to be granted to entities to allow a service to be invoked on them in the audit subsystem:
Permissions for Non-Admin Users to Run Audit Services
Service
Entity Type
Entity Name
Visibility
Design Time
Run-Time
QueryAuditHistory
Subsystem
AuditSubsystem
Yes
Read
Service: QueryAuditHistory - Service Execute
Data Shape
AuditHistory
Yes
Read
QueryAuditHistoryWithQueryCriteria
Subsystem
AuditSubsystem
Yes
Read
Service: QueryAuditHistoryWithQueryCriteria - Service Execute
Data Shape
AuditHistory
Yes
Read
ArchiveAuditHistory
Subsystem
AuditSubsystem
Yes
Read
Service: ArchiveAuditHistory: Service Execute
Thing
AuditArchiveScheduler
Yes
None
Property LastArchiveTime: Property read and property write
ArchiveAuditHistoryDirectPersistence
Subsystem
Audit Subsystem
Yes
Read
Service: ArchiveAuditHistory-DirectPersistence: Service Execute
Thing
AuditArchiveSchedulerDirectPersistence
Yes
None
Property LastArchiveTimeDirectPersistence: Property read and property write
ExportAuditData
Subsystem
AuditSubsystem
Yes
Read
Service: ExportAuditData: Service Execute
Thing
AuditArchiveScheduler
Yes
None
Property LastArchivedTime: Property read and property write
Thing
<user-created FileRepository>
Yes
None
All services: Service Execute
ExportOnlineAuditData
Subsystem
AuditSubsystem
Yes
Read
Service: ExportOnlineAuditData: Service Execute
Thing
<user-created FileRepository>
Yes
None
All services: Service Execute
CleanupOfflineAudit
Subsystem
AuditSubsystem
Yes
Read
Service CleanupOfflineAudit: Service Execute
Thing
AuditArchiveCleanupScheduler
Yes
None
Property DaysToArchive Property read and property write
Thing
AuditArchiveCleanupNotificationScheduler
Yes
None
Property read and property write
Thing
<user-created FileRepository>
Yes
None
All services: Service Execute
PurgeAuditData
Subsystem
AuditSubsystem
Yes
Read
Service PurgeAuditData: Service Execute
Thing
AuditPurgeScheduler
Yes
None
Property read and property write
GetAuditEntryCount
Subsystem
AuditSubsystem
Yes
Read
Service GetAuditEntryCount: Service Execute
Was this helpful?