Configure Permissions Guide Part 2

[#1]

• Configure Permissions Guide Part 2
• Step 5: Permissions
• Step 6: Application Keys
• Step 7: Organizations
• Step 8: Next Steps

Configure Permissions Guide Part 2

 

Step 5: 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

1. Once an Entity has been selected for editing, select the Permissions tab.
2. Based on what you would like to edit, select the Visibility, Design Time or Run Time tab.

   

The All Properties, Services, and Events section provides blanket security to all of these features for a User 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.

 

Set Permissions Programmatically

In some cases it will be useful to set permissions using a programmable interface. This can be done through a built-in set of services which can be accessed in many different ways including:

• Internal service call through an entity’s service
• Service call using the extension framework, or
• REST API call to a service on the platform. The following is a list of services built into all entities on the platform.

Service Name	Description
AddDesignTimePermission	Adds a new design time permission
AddRunTimePermission	Adds a new run time permission
CheckDesignTimePermission	Checks to see if an entity has a specific design time permission for the current User
CheckDesignTimePermissionForGroup	Checks to see if an entity has a specific design time permission for a given User Group
CheckDesignTimePermissionForUser	Checks to see if an entity has a specific design time permission for a given User
CheckPermission	Checks to see if the entity has a specific run time permission for the current User
CheckTimePermissionForGroup	Checks to see if the entity has a specific run time permission for a given User Group
CheckDesignTimePermissionForUser	Checks to see if the entity has a specific run time permission for a given User
DeleteDesignTimePermission	Delete a design time permission
DeleteRunTimePermission	Delete a run time permission
GetDesignTimePermission	Get a list of design time permissions in Info Table format
GetDesignTimePermissionAsJSON	Get a list of design time permissions in JSON format
GetPermissionsForCurrentUser	Get the run time permissions for the current User
GetPermissionsForGroup	Get the run time permissions for a given User Group
GetPermissionsForUser	Get the run time permissions for a given User
GetRunTimePermissions	Get a list of assigned run time permissions in Info Table format
GetRunTimePermissionAsJSON	Get a list of assigned run time permissions in JSON form
SetDesignTimePermissionAsJSON	Sets all of the run time permissions for a given Entity to the given JSON list

You may want to apply a set of permissions to a large group of Entities at once. This can be done using either the projects or the tags feature on the platform through the EntityServices resource.

The EntityServices resource has many useful services in it, but for the purpose of this section, we will only talk about the run time permission service. This will act on all entities with the provided tags or assigned to the given project.

Service Name	Description
SetEntityPermission	Sets run time permissions for a set of Entities

Step 6: Application Keys

Application Keys

Application Keys or appKeys are security tokens used for authentication in ThingWorx when not using a standard credentials method of authentication. They are associated with a given user and have all of the permissions granted to the user to which they are associated.

 

Create an Application Key

Using the Application Key for the default user (Administrator) is not recommended. If administrative access is absolutely necessary, create a user and place the user as a member of the SecurityAdministrators and Administrators user groups. Create the User the Application Key will be assigned to.

1. On the Home screen of Composer click + New.

   

2. In the dropdown list, click Applications Keys.

   

3. Use MyAppKey  for the name your Application Key.
4. Set the User Name Reference to a User you created and set the Project field (ie, PTCDefaultProject).

   

5. The Expiration Date field will default to 1 day.
6. Click Save. A Key ID has been generated and can be used to make secure connections.
   
   

IP Whitelisting for Application Keys

One of the features of an Application Key is the ability to set an IP whitelist. This allows the server to specify that only certain IP addresses should be able to use a given Key ID for access. This is a great way to lock down security on the platform for anything that will maintain a static IP address.

For example, connected Web-based business systems may have a static IP from which all calls should be made. Similarly, you can use wildcards to specify a network to narrow the range of IP addresses allowed while still offering some flexibility for devices with dynamic IP addresses.

Extremely mobile devices should likely not attempt to implement this however as they will often change networks and IP addresses and may lose the ability to connect when the IP whitelist feature is used.

Interact with Application Keys Programmatically

Service Name	Description
GetKeyID	Returns the ID of this application key
GetUserName	Get the user name associated with this application key
IsExpired	Returns if this application key is expired
ResetExpirationDateToDefault	Resets the expiration date of the application key to the default time based on configuration in the UserManagement subsystem
SetClientName	Sets the client name for this application key
SetExpirationDate	Sets the expiration date of this application key to a provided date
SetIPWhiteList	Sets the values for the IP whitelist for this application key
SetUserName	Sets the associated user name for this application key

TIP: To learn more about Application Keys, refer to the Create an Application Key Guide.

 

Step 7: 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.

Create an Organization

1. In the ThingWorx Composer, click the + New at the top of the screen.

   

2. Select Organization in the dropdown.

   

3. Name your Organization Constructors.
4. Set the Project field (ie, PTCDefaultProject) and click Save

   

5. Select the Organization tab to see the hierarchy.
6. With the top organization selected, in the Members search bar, search for the user you have created yourself and add them.

   

 

Create Organizational Units

1. Click the green + under the structure you would like to expand.
2. Name your Organization unit UpperManagement.
3. In the Members search bar, search for the user or user group you created and add it.

   

4. Click Save.

Repeat the steps to create the full heirarchy of the organization and its department/unit members.

 

Setup Entity Visibility

ThingWorx provides added security checks and access control with Entity visibility. Visibility ensures an entity is accessible to members of an organizational unit. Those members will then have access to the entity and the underlying security model determines what specific interaction any users that are members of that organization unit may have with a specific asset.

If a user in the system is not granted visibility, then that asset essentially does not exist within that user’s domain.

1. Select the Permissions tab of any custom Thing in Composer.

   

2. Filter and select Constructors in the Search Organizations field.
3. Click Save.

   

Login Pages for Organization

Creating an Organization automatically creates a login page for you. If you would like to add more to this login screen and customize it to fit your needs, create a Mashup and set it to the Organization's Home Mashup field.

If you plan to use a Login Screen, use the View Mashup URL generated from the Login Mashup you create. To view the login page of your application (whether custom or default), type the following URL: [server]/Thingworx/FormLogin/ (ie, localhost/Thingworx/FormLogin/Constructors).

Step 8: Next Steps

Congratulations! You've successfully completed the Configure Permissions guide, and learned how to:

• Configure and utilize the user access system
• Control permissions at design time and run time

The next guide in the Getting Started on the ThingWorx Platform learning path is Build a Predictive Analytics Model. 

If you are completing the Connect and Configure Industrial Devices and Systems learning path, the next guide is Choose a Connectivity Method.

Learn More

We recommend the following resources to continue your learning experience:

Capability	Guide
Build	Design Your Data Model

 

Additional Resources

If you have questions, issues, or need additional information, refer to:

Resource	Link
Support	Help Center