Security Policies

Overview

By default, requests that modify existing files or account settings are authenticated, but requests to upload or deliver files are not. Requests are authenticated by checking a policy string that is signed by a shared secret. Applications can be configured on an individual basis so that every request is authenticated. All security settings are configurable in the Developer Portal.

Request Default Authentication
Modifies existing file yes
Modifies account settings yes
Uploads new file no
Delivers file no

Policies and Signatures

Authentication and authorization against our APIs relies on Base64URL-encoded JSON “policies” and HMAC-SHA256 “signatures”. The policy determines which actions are authorized, and the signature authenticates the policy. Depending on the API, these values may be required as part of the path, query parameters, or body of a request.

The secret used for signing is automatically generated for each application. The secret should be carefully protected and never exposed client-side. A secure application stack requires backend code that generates and signs short-lived and limited-scope policies for clients. The secret can be regenerated as needed, but this will invalidate existing signatures.

Policy Structure

A policy must contain an “expiry” but can exclude all other values. A minimal policy, containing only an expiry, permits nearly all requests. The “call” value limits the types of requests allowed, and additional values limit request parameters. Getting EXIF data from image files requires explicit permission.

This policy allows any request except one to get EXIF data:

{
  "expiry": 501379200
}

This policy only allows uploading and saving to custom storage:

{
  "expiry": 501379200,
  "call": ["pick", "store"]
}

Policy Keys

A valid policy must contain an “expiry” value set in the future, but can exclude any other values.

Key Value Purpose
expiry Unix timestamp Sets policy expiration
call Array of call names Limits allowed requests, defaults to all
handle ID string Limits file modifications to a single file
container Regex Limits storage containers allowed for uploads
path Regex Limits storage paths allowed for uploads
url Regex Limits source URL’s allowed for transformations
minSize Size in bytes Sets a min size for uploads
maxSize Size in bytes Sets a max size for uploads

Please notice that while using the container, path, or URL policy keys, all special characters should be escaped with a backslash in order to use them in regular expressions.

Example

The example of the url:

https://sample-domain.com/default/file_sample(1).docx

Regular expression with the properly escaped special characters:

https\:\/\/sample\-domain\.com\/default\/file_sample\(1\)\.docx

Calls

Policies without a “call” array allow every call by default except “exif”. Requests to get EXIF data require the “exif” call explicitly.

Name Allows
pick Uploading
read Reading
remove Deleting
store Saving to custom storage (also need “pick”)
write Overwriting (not new uploads)
convert Converting (and using the document viewer)
exif Getting exif metadata for image files
stat Getting file metadata
runWorkflow Running workflow jobs

Example

The Developer Portal contains a widget for creating and signing policies, and each of the SDKs contains helper functionality for the same. The below example shows how to create and use a policy for file delivery.

Create a JSON policy string:

{
  "expiry": 1523595600,
  "call": ["read", "convert"],
  "handle": "bfTNCigRLq0QMOrsFKzb"
}

Base64URL encode the policy string:

ewogICJleHBpcnkiOiAxNTIzNTk1NjAwLAogICJjYWxsIjogWyJyZWFkIiwgImNvbnZlcnQiXSwKICAiaGFuZGxlIjogImJmVE5DaWdSTHEwUU1PcnNGS3piIgp9

Create a HMAC-SHA256 signature of the encoded policy (using ‘mysecret’ as key):

5191e4c6c304c08296eab217ee05236a5bacaab9b581b535d5922a41079b77e0

Using the policy and signature with a download URL:

https://cdn.filestackcontent.com/bfTNCigRLq0QMOrsFKzb?policy=ewogICJleHBpcnkiOiAxNTIzNTk1NjAwLAogICJjYWxsIjogWyJyZWFkIiwgImNvbnZlcnQiXSwKICAiaGFuZGxlIjogImJmVE5DaWdSTHEwUU1PcnNGS3piIgp9&signature=5191e4c6c304c08296eab217ee05236a5bacaab9b581b535d5922a41079b77e0

Using a policy and a signature when transforming your files (resize transformation URL):

https://cdn.filestackcontent.com/resize=width:300/security=policy:ewogICJleHBpcnkiOiAxNTIzNTk1NjAwLAogICJjYWxsIjogWyJyZWFkIiwgImNvbnZlcnQiXSwKICAiaGFuZGxlIjogImJmVE5DaWdSTHEwUU1PcnNGS3piIgp9,signature:5191e4c6c304c08296eab217ee05236a5bacaab9b581b535d5922a41079b77e0/bfTNCigRLq0QMOrsFKzb

Enforcing Security Policy with Path

Security policies play a vital role in ensuring the protection and controlled access of files in Filestack. This document provides step-by-step instructions on how to enforce security policies with path restrictions. Following these steps, you can secure your file uploads and control access based on specific paths.

Pre-requisites

Before proceeding with enforcing security policies with paths, ensure that the security feature is enabled in the Filestack Developer Portal. Additionally, if you are adding any path to your security policy, it’s crucial to ensure that your account is linked to external storage like S3, Dropbox, etc.

Please be aware that this functionality is designed to limit access to uploaded files by ensuring that the access policy aligns with the resource folder where the file is stored. The upload path can be determined by specifying the “store” parameter in the upload request, e.g., storeTo: {path: 'site_uploads/'}, or by using the path in the security policy. To access a specific file, individuals must have a policy signature with a path that matches the resource folder where the file is stored, especially if security is enabled in the development portal.

For files uploaded before March 11, 2024, users must manually create a policy with the path where the files were stored, or simply use the root path, or no path at all, to gain access to the files.

Steps

Follow the steps below to enforce the security policy with the path:

Step 1: Enable Security in the Developer Portal.

  • Log in to the Filestack Developer Portal using your credentials.
  • Navigate to the Security Settings and ensure that the security option is enabled for your application.

Step 2: Define the Path for Uploads.

  • Determine the path or directory where you want your uploaded files to be stored. For example, having a path like: /upload/path/test/*
  • For detailed instructions on specifying the path in your security policy, refer to the official Filestack documentation.

Step 3: Upload Files with Signature and Policy.

  • While uploading files using the Filestack file picker, include the generated signature and policy in the upload process.
  • The signature and policy should be associated with the desired path to store the files.

Step 4: Accessing Files with Security Policy.

  • When accessing the uploaded files, consider the following scenarios based on the security policies and their corresponding paths:

Scenario 1: Accessing with a matching path.

If the security policies for accessing the file have a path that matches the path in which the file was uploaded, then the file will be accessible.

For example, if the file was uploaded using the policy with the path: /test/uploads/2024/*

and access with security policy with the path: /test/uploads/2024/*

then the file will work fine.

Note: If the file was uploaded using policy with path /test/uploads/2024/* and access with security policy with path /test/uploads/2024/Jan, then the file will not be accessible. This is because the file will be stored in a bucket, for example, /test/uploads/2024/filename.pdf, and using the policy /test/uploads/2024/Jan will not match the bucket where the file is stored and hence it will fail because the file was uploaded to the root of 2024 folder. Still, we are accessing the policy with one more folder after 2024.

Scenario 2: Accessing without matching path.

If the security policies for accessing the file do not have a path that matches the path specified in the policy used during the upload, then the file will not be accessible.

For example, if the file was uploaded using policy with path: /test/uploads/2024/*

and access with security policy with path: /test/uploads/2023/Jan

Scenario 3: Using the root path to access a file uploaded with a specific path.

If the security policy for accessing the file has a root path while the file was uploaded with a specific path, then the file will be accessible. For example, if the file was uploaded using policy with path: /test/uploads/2024/*

and access with security policy with path / or no path.

Scenario 4: Access a file uploaded with the root folder or no path by using a specific path.

If the security policy for accessing the file has a specific path while the file was uploaded with the root folder or no path, then the file will not be accessible.

For example, if the file was uploaded using policy with root path / and access with security policy with path: /test/uploads/2024/Jan

Scenario 5: Accessing a file without any security policy.

If a security policy is not provided or omitted while accessing a file initially uploaded with security policies, then the file will not be accessible.

For example, if the file was uploaded using policy with path: /test/uploads/2024/*

and access without a security policy.

Scenario 6:

Suppose we initially uploaded a file without a security policy, and now the user enables the security policy from the dev portal. In that case, it cannot be accessed normally without a security policy.

Scenario 7:

If you add a path in your policy and no external storage is linked, e.g., S3, Dropbox, etc., the file will be uploaded to the root folder, but accessing the file with the same policy will fail. So, it is important that external storage is linked if a path is added to the policy.

Conclusion

Enforcing security policies with path restrictions is an effective way to protect and control access to files in Filestack. By following the steps outlined in this document, you can configure your application to enforce security policies based on specific paths, ensuring the integrity and confidentiality of your uploaded files.

Note: For more detailed information on each feature and all the improvements, visit the Filestack blog page.