Self-Authenticated Media URLs¶

When the 3LC Dashboard displays media samples (images, videos, audio), it must load the underlying bytes into the browser. Where those bytes come from, and how the browser fetches them, affect performance and memory usage for the Dashboard.

The Dashboard prefers to render media samples through native browser tags (<img>, <video>, and <audio>) wherever possible. Native media tags let the browser stream and decode media incrementally and let it discard decoded bytes once they are no longer on screen.

For a media tag to be used, however, the browser must be able to fetch the underlying bytes from a plain URL, without any custom Authorization headers. The Object Service makes that possible by handing the Dashboard a self-authenticated URL for each media sample - a URL that carries its own short-lived credentials in the query string, so the browser can fetch the bytes directly through a media tag.

Where Media Bytes Come From¶

Self-authenticated URLs handed to the Dashboard can take one of two forms:

  • Cloud-direct. When the media is stored in cloud storage (e.g. AWS S3, GCS, or Azure Blob Storage), the Object Service can issue a URL that points directly at the cloud object - an AWS presigned URL, a GCS V4 signed URL, or an Azure SAS URL. The Dashboard embeds that URL in a media tag and the bytes flow directly from cloud storage to the browser, without going through the Object Service.

  • Proxied through the Object Service. When a cloud-direct URL is not available or not appropriate (see below), the Object Service issues a URL that points back at itself. The browser fetches that URL and the Object Service reads the underlying bytes and streams them back.

The cloud-direct route avoids the latency and memory overhead of pulling every byte through the Object Service. The proxied route is a safe fallback that works for any URL the Object Service itself can read.

How It Works¶

When the Dashboard needs to display a media sample, it asks the Object Service to resolve the sample’s URL. The Object Service responds with either a cloud-direct URL or a proxied URL. Both URL kinds are short-lived, expiring after 30 minutes.

The Object Service chooses the proxied URL whenever a cloud-direct URL is not appropriate, which happens when:

  • The original sample URL points to a file on disk.

  • The original sample URL points to data that requires server-side transcoding before the browser can render it (e.g. TIFF images and NumPy .npy files representing images).

  • The URL adapter for the storage backend does not implement self-authenticated URL generation.

  • Self-authenticated URL generation fails at runtime (e.g. transient cloud API failure or insufficient permissions on the credentials the Object Service is running with) - a warning naming the bucket and the cause is logged once, and the proxy is used as a safe fallback. The failure is remembered for the whole bucket, so later samples in it go straight to the proxy without repeating the cloud call: for 15 minutes when the error looks like a missing permission, and for 1 minute otherwise (a transient cloud error, say). Samples already being resolved when the first failure arrives still try to sign, so a burst of failed cloud calls can precede the warning.

  • Cloud-direct URLs have been explicitly disabled (see below).

Cloud Permissions for Cloud-Direct URLs¶

Signing a cloud-direct URL can need more than permission to read the object:

  • AWS S3. Any credentials that can read the object can also presign a URL for it. No extra permission is needed. A URL presigned with temporary credentials (an STS session, an assumed role, instance-profile credentials) stops working when those credentials expire, even if the URL was requested for longer.

  • Google Cloud Storage. A V4 signed URL needs an RSA signature from the service account’s private key. When the Object Service runs with a service-account key file (GOOGLE_APPLICATION_CREDENTIALS), the key is local and signing needs nothing further. When it runs on a GCE VM or other metadata-server credentials, there is no local key and signing goes through the IAM Credentials API instead, which requires the iam.serviceAccounts.signBlob permission on the service account itself - typically granted by giving the account the roles/iam.serviceAccountTokenCreator role on itself. Without it, every media sample in the bucket is proxied and the log shows a Permission 'iam.serviceAccounts.signBlob' denied warning. Note that signing via the IAM Credentials API costs one extra API round trip per media sample.

  • Azure Blob Storage. A SAS URL is signed either with the storage account key, or with a user delegation key, which needs the Microsoft.Storage/storageAccounts/blobServices/generateUserDelegationKey action. The built-in Storage Blob Data Reader, Contributor and Owner roles and Storage Blob Delegator include it, but only when assigned at the storage account, resource group or subscription: a role assigned on a single container can read but cannot sign. In that case, also assign Storage Blob Delegator on the storage account.

After granting the permission, cloud-direct URLs resume within 15 minutes, or at once if the Object Service is restarted. If granting it is not an option, disable cloud-direct URLs (see below) so the service stops attempting to sign.

Disabling Cloud-Direct URLs¶

Cloud-direct URLs assume that the machine running the Dashboard in the browser can reach the cloud storage backend. That is often true, but not always. In cases where it is not true, a cloud-direct URL would be unreachable by the browser, even though the Object Service itself can read the bytes. One particular example of such a case is when using the 3LC Enterprise On-Prem deployment with end-user machines that do not have internet access.

To handle such cases, the Object Service exposes a configuration option that disables cloud-direct URLs and forces every media URL to be served through the proxy endpoint instead:

  • Config key: service.disable-external-media-urls

  • Environment variable: TLC_SERVICE_DISABLE_EXTERNAL_MEDIA_URLS

  • CLI argument: --disable-external-media-urls (on the 3lc service command)

  • Default: False

When this option is set, the Object Service always hands the Dashboard a proxied URL, regardless of whether the underlying URL adapter supports cloud-direct URLs. Media samples will still display in the Dashboard, but their bytes will flow through the Object Service rather than directly from cloud storage.