Roles define the user’s permissions (privileges) to access, view, edit, configure, and manage device-specific and other users’ information. Roles are often referred to as user roles. Every user role has a set of privileges to specific resources, such as devices, users, firmware images, device templates, etc.

To configure user roles and privileges for resources, Ayla has a Role Based Access Control (RBAC) system. Some of the main aspects of Ayla’s RBAC are:

• Addresses enterprise and consumer access security concerns.
• Provides flexible access to device data and device control based on assigned user roles.
• Supports a hierarchy of roles.

There are two parts to RBAC:

• Administrative: This involves setting up roles and the privileges associated with them using the Ayla Customer Dashboard.
• Operational: This involves creating users with specified roles and associating resources with them using the Ayla Service APIs.

This section of the Users and Roles guide describes:

• Predefined roles and privileges in the Ayla Platform
• Roles/privileges enabled for specific features
• Options to manage and customize roles using Ayla's customer portals
• Options to manage and customize roles using Ayla's RESTful APIs

Features/Roles Matrices

User roles are an integral part of the functional requirements for all features in the Ayla Platform. Some features are designed with privileges for one or more user roles fully enabled, while other features are designed for a set of user roles in which each role has specific privileges when using that feature. The matrices in this section specify which of the following privileges are configured for the user role(s) assigned to each feature in the platform; refer to Roles and Privileges Defined for a description of these privileges:

• View
• Create or Reserve
• Edit or Update
• Register or Unregister
• Delete, Disable, Factory Reset
• Upload, Download, or Refresh
• Run, Configure, Map, or Confirm
• All (used if all of the privileges in this list are enabled for the user role)

Roles and Privileges Defined

The Ayla Platform has a hierarchy of predefined OEM roles with associated privileges that differentiate the level of access the user has to Ayla product features and services. Refer to the Feature/Roles Matrices for custom privileges that meet the functional requirements for specific features. All users have complete access to devices registered to their accounts.

Privileges

Though some features and services have specific operational requirements, most require the following basic privileges used in the Ayla Platform:

• View
  This is similar to read-only access. You can review the user and/or device information, including configurations, results, reports, etc., but cannot perform actions like configure settings, modify, download, etc.

• Create/Reserve
  With the Create privilege, you can add user and device information and make configurations across the platform.

   

  The Reserve privilege applies to Factory Actions, a feature used to enable the interface between the Ayla platform and the OEM manufacturing process. Reserve is the process of putting aside Device Serial Numbers (DSNs) for future use.

• Edit/Update
  You can change and make new configurations and account settings. This is similar to the permission commonly known in our industry as write access.

• Register/Unregister
  This is permission to register and unregister devices. Users can register and unregister their own devices. With this privilege, OEM Admins can register and unregister other users’ devices as well.

• Delete/Disable/Factory Reset
  Delete gives you the ability to remove configurations, devices, users, etc. from the platform.

   

  Disable allows you to unconfigure settings for devices, users, and all features and services in the platform.

   

  Factory Reset enables you to complete four actions:
  • Reset the template.
  • Reset the device.
  • Unregister the device.
  • Reset the datapoint.

• Upload/Download/Refresh
  You can upload and download objects, i.e., images, email templates, etc.

   

  Refresh enables you to view the latest results, e.g., refresh a table listing in the Ayla Customer Dashboard to view the most up-to-date configurations.

• Run/Configure/Map/Confirm
  Run is different from the industry standard called write access. The Run privilege is the ability to execute an action, e.g., run an OTA job in the Command Center.

   

  Configure allows you to configure, update, and edit settings for devices, users, and other features/services, as well as clone and create them.

   

  Map enables you to use the feature to find the geographic location of a device or group of devices on a map.

   

  Confirm enables you to confirm an action.

User Roles

OEM::Admin
This role has complete control over everything in the platform. Ayla’s OEM customers, therefore, most often limit the number of users (employees) in their organization who are assigned to this role. OEMs must have this role to use the Dealer Management features.
The platform privileges include:

• Manage all users and privileges (create, edit, delete).
• Access all public and OEM scope templates.
• Perform Host OTAs.
• Access to all OEM devices.

OEM::Staff
This role is usually assigned to OEM customer’s direct or contract employees. The platform privileges include:

• View all users and devices but cannot make changes.
• Access all public and OEM scope templates.

OEM::SupportManager
This role is for users in the OEM customer’s support organization who do not require OEM Admin responsibilities but need the following privileges to accomplish specific functions:

• Perform specific OTA actions, i.e., single push, create groups/job (configure and run jobs).
• Delete commands.
• Access to all of the privileges assigned to the OEM Support Engineer.

OEM::SupportEngineer
This is a specialized role assigned to users in the OEM customer’s support organization whose responsibilities require the following privileges:

• Edit end-user email.
• Resend confirmation instructions.
• Unregister a device.
• Reboot devices.
• Update the device timezone.
• OEM staff access.

OEM::ModuleOEMManufacturer
This role is for OEM product manufacturers with end-user devices or embedded gateways that are based on Ayla Production Modules (formerly referred to as Black Box modules). These OEM users require the following privileges to use the Factory Actions feature to, for example, upload provisioning logs and search for their devices (regardless of module manufacturer who manufactured the devices):

• Access to Devices page and Factory Actions.
• Access to all Factory jobs.
• Upload provision file.

OEM::SoftwareOEMManufacturer
This role is for OEM product manufacturers with end-user devices or embedded gateways that are based on Ayla Integrated Agents (formerly referred to as White Box). These OEM users (i.e., firmware engineers) require the following privileges to use the Factory Actions feature to, for example, reserve devices, upload provisioning logs, and search for their devices:

• Access to Devices page and Factory Actions.
• Reserve Device Serial Numbers (DSNs).
• Upload the provision file.

OEM::Developer
This is a specialized role assigned to developers in our OEM customer’s organization (and third-party developers) whose responsibilities require the following privileges:

• Access to all public and OEM scope templates.
• Read and write access to devices.

OEM::Partner
This role is for the employees of Ayla’s OEM customers’ partner companies (i.e. a customer service team) who use Ayla as an Single Sign On (SSO) mechanism to log in to the dashboard to obtain particular device information for various purposes. Examples of their privileges are:

• Create, update, or delete their devices only.
• Only access information on serviced devices tagged with the dealer company label.

End::User
This role is for all users with end user accounts in the Ayla Platform and includes the following privileges:

• Access to all their registered devices.
• Create, edit, or delete their registered devices only (devices the end user owns).

Dealer::Admin
This role is for those at the OEM’s organization responsible for managing users and registered devices associated with the Dealer company. They require the following privileges:

• View all registered devices for their Dealer company.
• View, create, edit, or delete accounts for the Dealer company, Dealer users, and the dealer company’s end users. This includes accounts for OEM users assigned Dealer::Staff and Dealer::Admin privileges.
• Assign Dealer::Staff and Dealer::Admin privileges.
• Select and view all details on the Dealers registered devices.

Dealer::Staff
This role is for Dealer users (employees of the Dealer company). They require the following privileges:

• View all registered devices for their dealer company.
• View, create, and update/edit accounts for the Dealer company, Dealer users, and the dealer company’s end users.
• Select and view all details on the Dealers registered devices.

Role Management Using the Customer Portals

If you are an OEM user with an OEM::Admin role (referred to as an OEM Admin), you can assign and manage roles in the Ayla Customer Dashboard and the Ayla Developer Portal. In the dashboard, you can also restrict a specific privilege (i.e., read or write) for a role.

When logged in to the dashboard, your username and assigned role displays in the upper right corner (shown in the example below). You can click the gear icon and select My Profile to display your profile. Refer to the following example:

Note that the OEM Admin in the Field Service environment can only create users with roles in the Field Service. Those users cannot access the Developer Service. In the same way, the OEM Admin can create users in the Developer Service environment who do not have access in the Field Service. If a user needs access to both the Developer and Field Services, the OEM Admin in each service must create that user.

Assigning/Managing Roles Using the Customer Dashboard

In the dashboard, the OEM Admin can assign, change, and delete roles for users from their accounts.

For OEM Users, the OEM Admin must assign at least one role when creating the account, as shown below:

OEM users can have multiple roles in the Ayla Platform. For existing OEM users, you can search for the user on the OEM Users page and view all of the user’s assigned roles on this page. You can then click the user's account to open it (shown below). In edit mode, you can delete the OEM user's assigned roles and assign new roles to the OEM user. Refer to the following example:

When an OEM Admin creates an end user account, the End::User role is automatically assigned, and the end user account is associated with the OEM Admin’s account. The OEM Admin can change any associated end user accounts to an OEM user account by assigning an OEM role. This is done from the End Users page in edit mode of the user's account details. Refer to the following example:

The OEM Admin can also assign Dealer roles to associated end users from their accounts. Again, the OEM Admin selects the end user’s account from the End Users page and clicks the EDIT button. For Dealer roles, however, the OEM Admin must first associate the end user with the Dealer company by selecting it in the Dealer drop-down list, and then assign the Dealer role by selecting it in the drop-down list next to “as:”. Refer to the following example:

The next time you access the end user’s account, the new Dealer roles are displayed in the Roles field, as shown below:

When the OEM::Admin associates an end user with a Dealer company and then assigns the end user a Dealer role, the end user is called a Dealer user. The OEM Admin can then access the Dealer user’s account from the Dealers page in the dashboard, and assign or change Dealer roles. On the Dealers page, you click the Dealer company associated with the Dealer user and then click the Dealer User tab. Refer to the following example. Notice that the roles assigned to the Dealer users are shown on this tab.

From the Dealer User tab (shown above), you can click a Dealer User to open the account details where you can delete a Dealer role by clicking the trash can icon or add new Dealer roles using the Add New Role drop-down field. Refer to the following example:

If the end user signed up for an Ayla account outside the Ayla Customer Dashboard (e.g., using the Ayla Developer Portal), the OEM needs to contact Ayla Technical Support to associate the end users account with the OEM Admin in order to assign new roles to the end user.

Denying Roles in the Customer Dashboard

OEMs can deny the read or write permissions for specific roles. This is used to restrict specific users from creating, modifying, or viewing device properties.

This is configured from the Properties tab once you have opened the template on the Templates page. Refer to the following example:

On the Properties tab, you click the property and then the Denied Roles tab. On this tab, you can create new denied roles or delete existing roles. Refer to the following example:

Assigning/Managing Roles Using the Developer Portal

OEMs can use the Ayla Developer Portal to create custom roles for devices, as well as change and delete these roles.

In the Developer Portal, you create and manage roles for your devices using the Roles tab for the device. Refer to the following example:

You click ADD to use the New Role Label dialog box to configure your role. Refer to the following example:

To change the role, you click the role in the table listing to open the Edit Role Label dialog box. You can also delete roles by selecting the role in the table listing and then clicking the Delete button. Refer to the following example:

Role Management Using Ayla's RESTful APIs

Ayla’s services include RESTful APIs that enable you to create users with specified roles and then associate resources with these roles. Please refer to the Ayla API Reference, which is an interactive environment to learn and test all the APIs in the Ayla IoT Cloud.

Following are examples of what you can accomplish using the APIs for Users and Roles:

• Create and delete users
• Add metadata and contacts to user accounts
• Manage users and roles, for example:
  • Associate users with role labels
  • Disassociate users from role labels
  • Assign roles
  • Revoke roles
• Associate Devices with Users
• Associate Users with Dealers
• Associate Dealers with Devices
• Share devices among users