Connecting Azure Blob Storage on Clarisights

Connect an Azure Blob Storage container as a read-only custom source so Clarisights can ingest CSV, CSV.GZ, and Parquet files that your internal ETLs, BI tools, or partner feeds land in Azure. Once connected, the files in your configured container path are read on a refresh cadence you set per pipeline.

At a glance

Authentication options

Two authentication methods are supported. Shared access signature (SAS) tokens are not supported.

• Storage account access key: the simplest option and works with any storage account. The key grants access to the whole storage account.

• Service principal (Microsoft Entra ID app registration with a client secret): gives scoped, revocable access to a single container without sharing an account key. The storage account must have hierarchical namespace enabled (Azure Data Lake Storage Gen2). Hierarchical namespace is chosen when the storage account is created, so if your account does not have it, use the access key option instead.

Setting up the connection

1. In Azure, identify the storage account and container that holds your data, and confirm the object path (file or folder) you want Clarisights to read.

2. Create the credential you will share with Clarisights:

   • Access key: in the Azure portal, open the storage account and go to Security + networking → Access keys. Copy either of the two storage account access keys shown there.

   • Service principal: register an application in Microsoft Entra ID and create a client secret for it. Then open the container, go to Access control (IAM), and assign the application the Storage Blob Data Reader role. Note the application (client) ID, the directory (tenant) ID, and the client secret value.

3. If your storage account has a firewall enabled, allow-list the Clarisights outbound IPs. Your Clarisights contact will share the current list.

4. Send the connection details (see the table below) to your Clarisights contact via the secure channel they provide. We will configure the source and confirm once the first read succeeds.

⚠ Common error: AuthenticationFailed: Server failed to authenticate the request. The storage account access key is wrong, was rotated, or doesn’t belong to the storage account name you shared. Re-copy a current key from Access keys in the Azure portal and resend it through the secure channel. With a service principal, check that the client secret has not expired and that the Storage Blob Data Reader role is assigned on the right container.

⚠ Common error: BlobNotFound: the object path is wrong. Verify the container name and that files actually exist at that path. Path matching is case-sensitive. If your path uses date placeholders, double-check that files for the resolved date are present.

Connection details exchange

What we read

Clarisights reads files from the object path you configure and treats everything under that path as one logical dataset. Supported formats:

• CSV: the first row is treated as the header. All files under the path must use the same column set in the same order.

• CSV.GZ: gzip-compressed CSV; same header rules as CSV.

• Parquet: schema is read from the file metadata; all files under the path must share the same schema.

If your path matches multiple files (for example, one file per day under the same folder), Clarisights concatenates them. The schema must match across every file, otherwise the read will fail.

Path date placeholders

If your upstream lands files in date-partitioned folders (one folder or file per day), you don’t need to update the connection every day. The object path can include date placeholders that Clarisights resolves on every run, using the channel’s timezone.

Example. If your files land at daily_exports/2026-04-25/orders.csv, configure the object path as:

daily_exports/<year>-<month>-<day_of_month>/orders.csv

Clarisights resolves this on every run to yesterday’s folder, which suits an upstream that finalises a day’s file the morning after. To read today’s folder instead, add the marker right after the placeholders:

daily_exports/<year>-<month>-<day_of_month>*::<today-0days>/orders.csv

The dates resolve in the channel’s configured timezone, so make sure your channel timezone matches the timezone your upstream uses to partition files.

Connector specifics

• Path conventions. Files matched by your object path are read together as a single dataset. Keep one path per logical pipeline so different schemas don’t collide.

• Schema must match across files. CSV column headers must be identical (same names, same order), and Parquet files must share the same schema. Mixing schemas under the same path will fail the read.

• Archive tier blobs. If a blob has been moved to the Azure Archive access tier (manually or by a lifecycle policy), it must be rehydrated to Hot or Cool before Clarisights can read it. Reads against Archive blobs return an error until rehydration completes.

• Firewall allow-listing. If the storage account restricts network access, you must allow-list the Clarisights outbound IPs we share with you, otherwise reads will be blocked at the network layer.

Limitations & known constraints

• Read-only: Clarisights does not write back to your storage account.

• Only CSV, CSV.GZ, and Parquet are supported. Other formats (JSON, Avro, ORC, Excel) are not.

• All files matched by a path must share one schema. If your upstream changes column names or order, expect failures until every matched file is updated.

• Lifecycle policies that move blobs to the Archive tier will break reads until those blobs are rehydrated.

• Path matching is case-sensitive.

• Storage account access keys grant access to the entire storage account. To scope access to a single container, use a service principal (requires hierarchical namespace), or a separate storage account dedicated to the Clarisights feed.

Operating notes

• Refresh cadence is configured per pipeline at setup time. Talk to your Clarisights contact if you need to change it.

• Credential rotation. Azure storage accounts have two access keys so you can rotate without downtime: send Clarisights the secondary key, wait for confirmation that the new key is live, then regenerate the primary in Azure. Repeat in reverse on the next rotation. For a service principal, create a new client secret before the current one expires, send it to Clarisights, and delete the old secret once we confirm the switch.

• Firewall changes. If you change the storage account firewall or move to a private endpoint, let Clarisights know in advance so we can re-validate access.

• Schema changes. If you plan to add, remove, or rename columns in your upstream files, coordinate with Clarisights so the source can be re-mapped without an outage.

• Date placeholders & timezone. Date placeholders resolve in the channel’s configured timezone. If you change the timezone of your upstream partitioning, let Clarisights know so the channel timezone can be aligned.

Need help?

When contacting support from the in-app messenger, please include:

• The integration name and the storage account / container you connected (Integrations → Channel)

• The exact error message or screenshot

• The step where the issue occurred

• When the issue started