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.
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 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 — > . • Audit Subsystem — > . 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: • AuditArchiveCleanupNotificationScheduler— > • AuditArchiveCleanupNotificationScheduler— > . 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 |