Access Control

Some applications may require setting different levels of access, both for uploading and downloading files. Harvest Files supports defining file access permissions based on Soracom Access Management (SAM) Role permissions.

When configuring Harvest Files, you can select the Role ID of the SAM role you would like to attach to the group by using the Assumed Role option. All subscribers within the group will inherit the permissions specified in the SAM role.

SAM role permissions for Harvest Files include the following API actions:

FileEntry:listFiles - A device is allowed to retrieve a list of files within a specified directory
FileEntry:getFile - A device is allowed to download specific file(s)
FileEntry:putFile - A device is allowed to upload specific file(s)

When defining the role permissions, a condition should also be specified, which defines the path where the permitted action applies. The path specified in the condition parameter can include the following placeholders:

.* - A wildcard, which will match any directory or file path after a specified string. For example, firmware/versions/.* will match firmware/versions/production.bin and firmware/versions/beta/20190601.bin, but will not match any files outside of the firmware/versions/ directory.
:imsi - A placeholder, which will automatically be replaced by the IMSI of the subscriber making the request. For example, uploads/:imsi/.* will allow each subscriber to access files within its own directory, but not files in other IMSI directories.

Each permission statement should use the following format:

{
  "effect": "allow",
  "api": "FileEntry:*",
  "condition": "pathVariable('path') matches 'uploads/:imsi/.*'"
}

Example

Given that we have created a SAM role called my-test-role, and in its permissions we have defined the following Harvest Files permissions:

{
  "statements": [
    {
      "effect":"allow",
      "api": "FileEntry:listFiles",
      "condition": "pathVariable('path') matches 'firmware/versions/'"
    },
    {
      "effect":"allow",
      "api": "FileEntry:getFile",
      "condition": "pathVariable('path') matches 'firmware/versions/.*'"
    },
    {
      "effect":"allow",
      "api": "FileEntry:putFile",
      "condition": "pathVariable('path') matches 'logs/:imsi/.*'"
    }
  ]
}

When we set the Harvest Files Assumed Role option as my-test-role, the subcsribers within the group will then have the following permissions:

Each subscriber will be able to list all files within the firmware/versions/ directory.
Each subscriber will be able to download any file within the firmware/versions/ directory, including any files located in subdirectories.
Each subscriber will be able to upload files only to its own logs/:imsi/ directory.

Soracom Harvest Files

Access Control

Example