- GUIDE CONCEPT
- Step 1: Examples and Strategy
- Step 2: Creating Security Groups
- Step 3: Configuring Permissions
- Step 4: Next Steps
Learn how to create or update your system to be more secure
GUIDE CONCEPT
ThingWorx allows for a layer of security within your company or organization to be utilized for authentication and user management.
These concepts and steps will allow you to focus on development of your application while still allowing the ability to utilize the power of ThingWorx!
We will teach you how to enable and configure ThingWorx to perform your security needs.
YOU'LL LEARN HOW TO
- Securing data and private information
- Use services, alerts, and subscriptions to handle processes without human interaction
- Handling group and organization permissions
NOTE: The estimated time to complete this guide is 60 minutes.
Step 1: Examples and Strategy
Download the attached FoodIndustry.zip users and extract/import the contents. These are to be used as you work through this learning path. For the completed example, download FoodIndustryComplete.zip.
In this tutorial we continue with our real-world scenario for the Fizos food company. We already have our factory data, automated cooking processed for our sausage product lines, and an automated process for picking up and delivering goods. What we need now is to ensure our organization, security groups, and data is truly secure. Having security permissions at each level and each type of entity involved with our company enables us to have full control over every aspect.
Setting Up Organizations
Organizations are hierarchical structures that allow the user to assign visibility to entities in the ThingWorx Model. This model provides the top down structure from the highest level in an organization or department, to the lower levels of said entity. Each level within this structure also allows for users and groups to be added. This provides a greater level of customization to resources within the ThingWorx Composer.
We will not only create an organization that represents Fizos, but we will have membership in the organization to represent partners, external users, guests, etc. With this level of granularity, we have more control over what is happening at each level.
- In the ThingWorx Composer, click the + New at the top of the screen.
- Select Organization in the dropdown.
- Name your Organization Fizos.
- Set the Project field (ie, PTCDefaultProject).
- Click Save
- Select the Organization tab to see the hierarchy.
- Select Unit 1 in the middle of the canvas.
- Update the Name field to Company and save your changes.
Create Additional Organization Units
Now let's add a node for Employees, Interfaces(APIs), Partners, Customers, Guests, and other groups we might consider important.
- Click the green + under the structure you would like to expand.
- Name your Organization unit Employees.
- Click Save. We won't add groups as yet. We will do that in the following sections.
Repeat the steps to create the full top level units. It should look similar to the following:
We now have the starting structures for Fizos. Next, we will need to add security groups and more units.
Step 2: Creating Security Groups
In many IoT solutions there will be a large scale of users using the system. Because of this it doesn’t make sense to manually set the permissions of every user added to the system. This is why we created User Groups. User Groups provide a role-based approach to permissions and exist to give similar users the same permissions across multiple entities on the platform. User groups set permissions exactly the same way as users do (see next section), but you can simply add a user to a user group in order to set permissions at scale.
Creating a user group such as Fizos.External.SecurityGroup would allow you to have a group with no design time permissions, but allow run time permissions for specific aspects of your solution such as reading product pricing from a service. Similarly you could create a user group called Fizos.Developers.SecurityGroup (under the Employees unit) who would have design time and run time permissions to work on your solution.
Create Security Groups
- In the ThingWorx Composer, click the + New at the top of the screen.
- Select User Group in the dropdown.
- Name your group Fizos.Partners.SecurityGroup.
- Set the Project field with an existing Project (ie, PTCDefaultProject).
- Click Save.
Repeat these steps to create more user groups for each of the top level units we created in the last section (Customers, External, Interfaces, Employees). We can also add in some groups from the companies we listed as customers and partners earlier in this learning path. Below is an example of all the groups I created for this example:
NOTE: Individual user permissions will override group user permissions. In other words, if you initially add a user to a group so they inherit the permissions of the group, you will still be able to customize permissions for an individual user in that group as needed.
Default User Groups
The platform has a few user groups included in the platform by default. These are used to set up common roles that are often associated with using the platform and have built in permissions. These groups are not meant to be used when creating new applications or general permissions.
Step 3: Configuring Permissions
These permissions can be accessed on any entity created on the platform. All entities have permission control for both design time and run time.
| Permission Time | Control |
| Design time | Controls what users are able to do with entities themselves while building the solution. |
| Run time | Controls what the users are able to do with the data for an entity when they use the solution. |
| Permission Type | Description |
| Property Read | Read property values |
| Property Write | Update property values |
| Service Execute | Execute Services in this Entity |
| Event Execute | Queue or fire Events in this Entity |
| Event Subscribe | Ability to subscribe to Events in this Entity |
| Access Type | Description |
| Allow | Allow the user's access to this feature. |
| Deny | Deny the user's access to this feature. |
| Inherit | Set the user's access to this feature based on permissions in Entities this Entity is based on or the configurations at a higher level. |
Add Permissions for an Entity
- Once an entity has been selected for editing, select the Permissions tab.
- Based on what you would like to edit, select the Design Time or Run Time tab.
The All Properties, Services, and Events section provides blanket security to all of these features for a group or user. The Property, Service, or Event Overrides section is used for any overrides that need to be made for specific features.
In the example blow, the User a.jones has the ability to read properties, fire events, and subscribe to events. The User does not have the ability to update a property or execute a Service. In the second section, a.jones is allowed to call the GetConfigurationTable Service (even though he was restricted from doing so in the other section).
To set a permission, filter and select a User/User Group. When their name is in the table, click the Permission Type you would like for this Entity. Default permissions are added to the User or User Group you filtered and selected. This will be full access permissions unless you've changed one of the fields.
Bulk Permissions Handling
When you would like to set the permissions to an entity in bulk, ie permissions for all Things, you can use the Collections option.
- On the left hand side, click the lock.
- Click the Collections option under Permissions.
- Select the checkbox next to Things.
- Click Edit Permissions button.
Now you will see the same interface you used above, except this time, it will be for all Things instead of a singular entity. You can use these permission settings to stop access to all of the entities you would not want an external user being able to see.
Bulk Permissions Reporting
When you would like to verify the permissions to an entity, ie permissions for all Fizos.Logistics, you can use the Access Report option.
- On the left hand side, click the lock.
- Click the Access Report option under Permissions.
- Set the User or User Group. (in this case Fizos.VizosMeatMarket.SecurityGroup)
- Set the Entity (in this case Fizos.Logistics)
- Click Apply.
You will be able to see what this User Group has access to as it pertains to the Fizos.Logistics Entity. Try other Entities and User Groups.
Step 4: Next Steps
Congratulations! You've successfully completed the Securing Industry Data guide.
In this guide, you learned how to:
- Securing data and private information
- Use services, alerts, and subscriptions to handle processes without human interaction
- Handling group and organization permissions
If you wish to return to the learning path, click Complex and Automatic Food and Beverage Systems Learning Path
Learn More
We recommend the following resources to continue your learning experience:
| Capability | Guide |
| Build | ThingWorx Solutions in Food Industry |
| Build | Design Your Data Model |
| Build | Implement Services, Events, and Subscriptions |
Additional Resources
If you have questions, issues, or need additional information, refer to:
| Resource | Link |
| Community | Developer Community Forum |
