- Configure Permissions Guide Part 1
- Overview
- Step 1: Completed Example
- Step 2: Common Terms
- Step 3: Users
- Step 4: User Groups
Configure Permissions Guide Part 1
Overview
This project will introduce you to permissions inside of the ThingWorx platform. Permissions are used to control usage during development, runtime, and experience. Following the steps in this guide, you will be able to create Users, User Groups, Application Keys, and Organizations and tie them together. We will teach you how to create functional permission schemes in the ThingWorx platform to create a secure application and development environment.
NOTE: This guide's content aligns with ThingWorx 9.3. The estimated time to complete ALL 2 parts of this guide is 30 minutes.
Step 1: Completed Example
Download and unzip the completed files attached to this tutorial: PermissionsEntities.zip.
In this tutorial, we walk through security concepts within ThingWorx. Utilize this file to see a finished example and return to it as a reference if you become stuck creating your own fully flushed out application.
Keep in mind, this download uses the exact names for entities used in this tutorial. If you would like to import this example and also create entities on your own, change the names of the entities you create.
Step 2: Common Terms
It is important to understand the terminology before creating Users, Groups, and Permissions:
Term | Definition |
Entity | Generic name for any of the customizable building blocks inside the ThingWorx Platform |
User | An Entity dedicated to identifying a person or device accessing the platform |
User Group | An Entity that defines role-based permissions for Users in bulk |
Tags and Projects | Mechanisms used to group Entities together by marking them as similar or related |
Composer | The ThingWorx GUI tool for building your solution |
Resource | A collection of Services which are not stateful (i.e. they do not have Properties, Events, etc.); they can be found in Composer under the System category |
Organization | Hierarchical structures that allow you to assign visibility to Entities in the ThingWorx Model |
Step 3: Users
Users represent an individual person or connected system. They contain information such as a username, email, and password (Standard Credentials) as well as peripheral information such as Name of the actual person/system/device it was created for. Users can be created, updated, and deleted just like every other Entity.
Create User
- In the ThingWorx Composer, click the + New at the top of the screen.
- Select User in the dropdown.
- Name the User default_user and add a password.
- Set the Project field (ie, PTCDefaultProject) and click Save.
User-Related Services
There are a few Services available through a resource called EntityServices, that allow you to interact with user entities programmatically.
Once a user has been created, you can interact with it through some built-in Services:
Default Users
There are two key users built into every instance of ThingWorx when initially created.
Administrator: When setting up your platform, you'll use the Administrator user first, because it is the user that will allow you to set up new users and assign them to Administrator or other roles.
NOTE: It is extremely important to reset the Administrator password after your first login. Leaving the default password could allow the system to be compromised in the future.
System User: The System User is created to allow service chaining on a given Thing when a user may not have direct permissions for every part of the chain. It exists so that access to given Services can be granted based on some previous logic instead of direct overarching permissions. For example: if the user is within the building, then trigger a Service, otherwise do not trigger the Service.
Step 4: User 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. For example: Creating a User group such as "Solution Architects" would allow you to do something like set all permissions for design time but limit permissions for run time. Similarly you could create a user group called "Solution Users" who have no design time permissions and specific run time permissions.
Create Group and Add Users
- In the ThingWorx Composer, click the + New at the top of the screen.
- Select User Group in the dropdown.
- Name your group ExampleGroup.
- Set the Project field (ie, PTCDefaultProject) and click Save.
- Click Members to view current members in the group.
- Filter and select the user you want to add in the Available Members section.
- Click the arrow on their row or drag the User to the Members section.
- Click Save.
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.
User Group Services
There are a few Services available through a resource called EntityServices, that allow you to interact with user group entities programmatically.
Service Name | Description |
CreateGroup | Creates a new User Group |
DeleteGroup | Deletes a user Group |
Once a group has been created you can interact with it through built-in services to add or remove a User.
Service Name | Description |
AddMember | Adds a User or User Group to this group |
AssignMembers | Adds a list of Users or User Groups to this group |
DeleteMember | Removes a User or User Group from the members of this group |
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.
Click here to view Part 2 of this guide.
