File stores

Portward reads Parquet, CSV and Excel (.xlsx, the first sheet) files where they already live, in a company file store, through that store’s own permissions. Google Drive adds Google Sheets. Each file becomes one dataset. The gateway reads files in memory and never writes them to disk.

Each store below needs a key or a sign-in that can only read, and one folder to read. Amazon S3, Google Cloud Storage and Azure Blob Storage on their own endpoints need no entry on the gateway’s allowed hosts. A custom endpoint does (Allow the host).

Amazon S3 (or S3-compatible)

Create an IAM user (or an access key for one) whose only policy is this. Replace acme-finance with your bucket.

{
  "Version": "2012-10-17",
  "Statement": [
    {"Effect": "Allow", "Action": "s3:ListBucket", "Resource": "arn:aws:s3:::acme-finance"},
    {"Effect": "Allow", "Action": "s3:GetObject", "Resource": "arn:aws:s3:::acme-finance/*"}
  ]
}

In setup, choose Amazon S3 (or S3-compatible) and fill in Name (such as finance_files), Bucket, Folder (optional), Region (empty means us-east-1), Access key ID and Secret access key. For an S3-compatible store such as MinIO, fill in Endpoint too, and add its host to the allowed hosts.

Portward doesn’t test whether an S3 key can write. The policy above is what keeps it read-only, so give the key no other policy.

Google Cloud Storage

Create a service account with Storage Object Viewer on the one bucket, and an HMAC key for it. Replace acme-analytics with your project and acme-safety with your bucket.

gcloud iam service-accounts create portward-files --project=acme-analytics
gcloud storage buckets add-iam-policy-binding gs://acme-safety \
  --member=serviceAccount:portward-files@acme-analytics.iam.gserviceaccount.com --role=roles/storage.objectViewer
gcloud storage hmac create portward-files@acme-analytics.iam.gserviceaccount.com --project=acme-analytics

In setup, choose Google Cloud Storage and fill in Name (such as finance_files), Bucket, Folder (optional), HMAC access key (it starts with GOOG1) and HMAC secret.

As with S3, the role keeps the key read-only. Give the service account no other role.

Azure Blob Storage / Data Lake Gen2

Use a container SAS that can only read and list, with an expiry date. Replace the account, container and date with your own:

az storage container generate-sas --account-name acmefiles --name field-reports --permissions rl \
  --expiry 2027-01-01T00:00Z --https-only --auth-mode key

On an account with Data Lake Gen2 (the hierarchical namespace), the container is the file system. To reach one directory only, use a directory SAS instead and give that directory as the folder in setup:

az storage fs directory generate-sas -f <file-system> -n <directory> --permissions rl \
  --expiry 2027-01-01T00:00Z --https-only --account-name <account> --auth-mode key

With --auth-mode login --as-user instead, the SAS is signed with your Entra sign-in rather than the account key, and lasts at most 7 days.

In setup, choose Azure Blob Storage / Data Lake Gen2 and fill in Name (such as finance_files), Storage account, Container, Folder (optional) and SAS token. Leave Endpoint empty for Azure’s own; the account’s dfs address works too. An endpoint for another Azure cloud or for a storage emulator needs its host on the allowed hosts.

The gateway checks the SAS again each time it loads its sources, at every start and after every setup change. An expired or revoked token disconnects the source.

Microsoft 365 (OneDrive)

The person connecting signs in with Microsoft from setup, through the app the gateway’s operator registered once and named in [setup.sign_in.microsoft365]. Portward asks only for Files.Read, which reads that person’s own files and nothing else. Sign in with an account that holds only what people should see, then name the folder to read, such as Finance/Reports. A whole drive can’t be connected.

SharePoint document library

The person connecting signs in with a Microsoft work account from setup. SharePoint uses the OneDrive app unless the operator named another in [setup.sign_in.sharepoint]. Portward asks for Files.Read.All and Sites.Read.All on behalf of the signed-in person, so it reads only what that account can read, and never writes.

In setup, give the Site address (such as https://contoso.sharepoint.com/sites/Finance), optionally the Library (empty means Documents) and a Folder. Use an account that can read only what people should see.

If your tenant doesn’t let users consent to apps, an admin grants consent for those two permissions once: in the Entra admin center, open Enterprise applications, then the app, then Permissions.

Google Drive

The person connecting signs in with Google from setup, through the app the gateway’s operator named in [setup.sign_in.google_drive]. Portward asks for drive.readonly only. Then give the Folder: its name, its id, or its link.

What the setup check tests

For every store, setup lists the folder and opens each file before it saves:

• It needs at least one file it can read (“no .parquet, .csv or .xlsx files found in”). A file that can’t be read is left out, and if none can, setup says so (“none of the files in”).
• Bucket and container names are checked first (“bucket: the bucket’s name only”, “container: its name only”).
• A custom endpoint must be on the allowed hosts (“isn’t in the hosts the gateway operator allowed for setup”).

For Azure, the SAS token itself is checked:

• It must be a container SAS, or a directory SAS on Data Lake Gen2 (“use a container SAS (sr=c), not an account SAS”).
• It must name its permissions and grant only read and list (“the SAS token grants more than read and list”).
• It must not have expired (“the SAS token expired at”).
• A directory SAS must be given with its directory as the folder (“a directory SAS only reaches its directory”).

For Microsoft 365, SharePoint and Google Drive, the sign-in itself is checked:

• The operator must have set up the app (“the gateway operator hasn’t set up Microsoft sign-in”, “the gateway operator hasn’t set up Google sign-in”).
• Google must grant read-only Drive access and nothing more (“the Google sign-in grants more than read-only Drive access; it was not kept”).
• OneDrive needs a folder (“name the folder to read (the whole drive can’t be connected)”).