Access policies

Access policies manage direct access to devices (Secure Device Access, or SDA). They are commonly used to let field technicians handle deployed devices on your behalf through an application running on a mobile phone, a tablet and so on.

You can associate an access policy with a user or group. You cannot currently directly associate a policy with an API key, but if a group contains an API key, the group's policy will apply to the key.

Access policies are tailored to the SDA application your field technicians use and the embedded application on the device. For example, you must know the names of functions the embedded application can expose. For more information about implementing SDA, see Using SDA in your IoT and Android device applications.

The Access Policies page shows all of your team's policies. You can search for a policy by name.

The available actions are:

• Create a new policy.
• View and edit a policy.
• Deactivate or delete a policy.
• View trust anchors (a direct link to the Trust anchors page).

Tip: You can perform all access management actions with the Account Management API.

A note on non-SDA access policies

Portal creates policies exclusively for SDA; you can see the Secure Device Access tag on these policies (in the Policy Details > Attributes tab). If you create policies using the Account Management API, you can create them for other purposes, such as restricting access to Portal. These more generic policies do not have the SDA tag and are not editable in Portal.

Creating a new access policy

To create a new access policy:

1. In Access Management > Access policies, click New access policy.

2. Give the policy a name and, optionally, a description.

3. Set the access token validity, between 1 and 999 days.

   • When the token expires, the access policy (and the application relying on it) will lose access to the device. This limits the potential for breaches, so it's best practice to be strict and keep the validity to a minimum. See the policy security section for more information.
   • You need to create a new policy or reset the token validity when it expires.

4. Set the scope of the policy, which determines whether the policy grants a user:

   • Full access to the settings and maintenance tasks on the IoT device.
   • Partial access to the IoT device, which restricts the policy user to a limited set of operations.

   Note: The device manufacturer must provide you with a list of all the operations the mobile application can perform. The list of operations a technician can request must be the same in the code of your IoT device and SDA technician applications, and in your Device Management account.

5. Define the devices covered by the policy.

   Note: A policy's devices list is not set when the policy is created; if new devices that match the policy connect to Device Directory, they are added to the policy.

   You can reference devices in a policy using their:

   • Device IDs: Enter as free text. A device ID must be in UUID format (letters and numbers only). The IDs are separated by a new line.

   • (Device) Endpoint names: Enter as free text. An endpoint name can contain only letters, numbers, hyphens and spaces. The endpoint names are separated by a new line.

     Endpoint name is the only device reference you can use for devices that haven't bootstrapped and registered yet.

   • Custom attributes: Enter key-value pairs, which you can then add to the devices in the Devices page. Only devices that have all of the custom attributes in the policy are added.

   The device must have bootstrapped and registered to be visible in Portal, so you can set these attributes, but the device does not have to be online at the time you set the attributes. Similarly, the device must have bootstrapped and registered if you want to use the Device ID in the access policy.

6. Portal gives a live preview of matching devices. A device must have already connected to Device Directory at least once.

7. Assign users or user groups to the policy.

   At this point, you cannot assign API keys to the policy. However, if an API key is part of a group, and you associate that group to the policy, the API key will be part of the policy.

8. Save the policy.

   You are asked to enter your password.

Managing policies

For an existing policy, you can:

• View policy details.
• Edit the policy.
• Deactivate or delete the policy.

To view and edit policy details, in Access Management > Access policies, click the policy’s name. The Policy details pane has four tabs:

• Summary: basic policy information. Not editable.
• Permissions: scope and device list. Not editable.
• Groups, Users: list of groups (with user count) and individual users that use the policy. Not editable.
• Attributes: full policy information as returned by the API. Not editable.

Editing a policy

To edit a policy:

1. In Access Management > Access policies, click the policy’s name.

   The Policy details pane opens.

2. Click the Edit button.

The editing process is identical to the initial creation process, as explained above.

Deactivating or deleting a policy

You can temporarily deactivate a policy or permanently delete it. Both actions are available in the Policy details page:

• The page shows a status of Active or Inactive. Click the Edit button by the status field to change it.
• The page also offers a Delete button.

You may want to delete a policy:

• If you think a third party or any other unauthorized person has access to an application that uses the policy.
• For any other security consideration. For example, if you no longer use and maintain the application that relied on a specific key, it's good to remove the key in case the unmaintained application has a security vulnerability.

Deleting a policy cannot be undone. If you're not sure you should be deleting it, consider temporarily deactivating it.

Managing policy security

When users in the field requests an access token, Device Management provides them with an access token based on the policies to which they are assigned. Users can continue to access IoT devices with the same access token, as long as the token is valid, without having to connect to Device Management. This means that changes you make on the Portal side, such as editing or deleting a policy, do not revoke users’ access until the next time they request an access token.

The solution to this problem is to make the token’s validity short when you set up the policy. When the token expires, the device rejects it. The application then gets a new token from Device Management, and this token is based on the new policy.