Azure Blob Storage

Azure Blob Storage stores arbitrary unstructured data like images, files, and backups. Aidbox integrates with Blob Storage through Shared Access Signatures (SAS) , which provide temporary, secure URLs for uploading and retrieving data.

Aidbox supports three authentication methods for generating SAS tokens:

• Workload identity (since 2511) - uses Azure AD workload identity with managed identities, no credentials stored in Aidbox
• User delegation SAS (since 2508) - uses Azure Application credentials (client ID and secret) to generate SAS tokens
• Account SAS - uses storage account keys directly

Workload identity is the most secure option, as it eliminates the need to manage credentials. It works with any environment that supports OpenID Connect (OIDC) federation, including Kubernetes, GitHub Actions, and other CI/CD platforms.

Workload identity

Workload identity allows Aidbox to access Azure Blob Storage using managed identities instead of storing credentials. This approach uses OpenID Connect (OIDC) to exchange identity tokens from your platform (Kubernetes, GitHub Actions, etc.) for Azure AD tokens.

Prerequisites

Configure Azure workload identity for your environment:

1. 1.

   Create storage account and container in Azure if you don't have one already.

2. 2.

   Create user-assigned managed identity in Azure. See Create a user-assigned managed identity .

3. 3.

   Configure federated credential to establish trust between your OIDC identity provider (like Kubernetes or GitHub Actions) and the managed identity. This allows the identity provider to request Azure tokens on behalf of Aidbox. See Configure federated identity credentials .

4. 4.

   Assign storage roles - Grant the managed identity access to your storage account by assigning these roles:

   • Storage Blob Data Contributor - for read, write, and delete permissions
   • Storage Blob Delegator - for generating user delegation SAS tokens

   Assign both roles to the managed identity (from step 2) on your storage account. See Assign Azure roles .

5. 5.

   Deploy Aidbox with OIDC token access. Your platform must provide OIDC tokens to Aidbox. For Kubernetes with AKS:

   Create a ServiceAccount with the managed identity client ID annotation:

   apiVersion: v1
   kind: ServiceAccount
   metadata:
     name: aidbox-sa
     namespace: aidbox
     annotations:
       azure.workload.identity/client-id: "<managed-identity-client-id>"
   

   Label your pod with azure.workload.identity/use: "true":

   apiVersion: v1
   kind: Pod
   metadata:
     name: aidbox
     namespace: aidbox
     labels:
       azure.workload.identity/use: "true"
   spec:
     serviceAccountName: aidbox-sa
     containers:
     - name: aidbox
       image: healthsamurai/aidboxone:edge
   

   The <managed-identity-client-id> is the client ID from the user-assigned managed identity created in step 2. See Use workload identity with AKS .

After deployment, Aidbox automatically detects the managed identity through DefaultAzureCredential and uses it to generate SAS tokens. No additional configuration resources like AzureAccount or AzureContainer are needed.

Generate SAS URLs

With workload identity configured, request SAS URLs by specifying the storage account and container in the URL path.

Get write URL:

POST /azure/storage/<storage-account>/<container-name>
Content-Type: application/json

{
  "filename": "document.pdf"
}

Response:

{
  "url": "https://<account>.blob.core.windows.net/<container>/document.pdf?sv=...&sig=..."
}

Get read URL:

GET /azure/storage/<storage-account>/<container-name>/<blob-path>

Get delete URL:

DELETE /azure/storage/<storage-account>/<container-name>/<blob-path>

Configuration

Query parameters:

Request body (POST only):

See also:

• Azure AD workload identities overview
• Workload identity federation
• Configure workload identity on AKS (Kubernetes example)
• DefaultAzureCredential class

User delegation SAS

User delegation SAS generates signed URLs using Azure Application credentials. This method requires storing client ID and secret in Aidbox but provides better security than account keys.

Prerequisites

Configure Azure AD application and Aidbox resources:

1. 1.

   Create storage account and container in Azure if you don't have one already.

2. 2.

   Register application in Azure AD to get tenant ID, client ID, and client secret. See Register an application in Microsoft Entra ID .

3. 3.

   Create AzureAccount resource in Aidbox with application credentials:

POST /AzureAccount
Content-Type: application/json

{
  "id": "my-azure-account",
  "tenantId": "<tenant-id>",
  "clientId": "<client-id>",
  "clientSecret": "<client-secret>",
  "sasType": "userDelegation"
}

4. 4.
   Create AzureContainer resource to link Aidbox to your storage container:

POST /AzureContainer
Content-Type: application/json

{
  "resourceType": "AzureContainer",
  "id": "my-container",
  "account": {
    "id": "my-azure-account",
    "resourceType": "AzureAccount"
  },
  "storage": "<storage-account-name>",
  "container": "<container-name>"
}

5. 5.

   Assign storage roles to the application:

   • Storage Blob Delegator - allows generating user delegation SAS tokens
   • Storage Blob Data Contributor - grants read, write, and delete permissions for blob data

   See Assign Azure roles .

Generate SAS URLs

Request SAS URLs using the AzureContainer resource ID.

Get write URL:

POST /azure/storage/<container-id>

{
  "blob": "document.pdf"
}

Get read URL:

GET /azure/storage/<container-id>/<blob-path>

Get delete URL:

DELETE /azure/storage/<container-id>/<blob-path>

Configuration

Query parameters:

Request body (POST only):

See AzureAccount and AzureContainer resource reference for configuration details.

Account SAS

Account SAS generates signed URLs using storage account keys. This is the simplest method but less secure since it requires storing the account key in Aidbox. Not recommended for production use.

Prerequisites

Configure storage account keys and Aidbox resources:

1. 1.

   Create storage account and container in Azure if you don't have one already.

2. 2.

   Get storage account key from Azure Portal under "Access keys" section. See Manage storage account access keys .

3. 3.

   Create AzureAccount resource with account name and key:

POST /AzureAccount
Content-Type: application/json

{
  "id": "my-storage-account",
  "key": "<storage-account-key>"
}

4. 4.
   Create AzureContainer resource to link Aidbox to your storage container:

POST /AzureContainer
Content-Type: application/json

{
  "resourceType": "AzureContainer",
  "id": "my-container",
  "account": {
    "id": "my-storage-account",
    "resourceType": "AzureAccount"
  },
  "storage": "<storage-account-name>",
  "container": "<container-name>"
}

Generate SAS URLs

Request SAS URLs using the AzureContainer resource ID.

Get write URL:

POST /azure/storage/<container-id>

{
  "blob": "document.pdf"
}

Get read URL:

GET /azure/storage/<container-id>/<blob-path>

Get delete URL:

DELETE /azure/storage/<container-id>/<blob-path>

Configuration

Query parameters:

Request body (POST only):

See AzureAccount and AzureContainer resource reference for configuration details.

Using SAS URLs

Once you have obtained a SAS URL from any of the methods above, you can use it directly with standard HTTP clients.

Upload file

Upload a file using the write URL:

curl -X PUT "<signed-url>" \
  -H "x-ms-blob-type: BlockBlob" \
  -H "Content-Type: text/plain" \
  -d "hello"

For binary files, use --data-binary with a file:

curl -X PUT "<signed-url>" \
  -H "x-ms-blob-type: BlockBlob" \
  -H "Content-Type: image/png" \
  --data-binary @image.png

Download file

Download a file using the read URL:

curl -s "<signed-url>"

Save to file:

curl -s "<signed-url>" -o downloaded-file.txt

Delete file

Delete a file using the delete URL:

curl -X DELETE "<signed-url>"

Display image in HTML

Option 1: Use signed URL directly

Get the signed URL from Aidbox and use it in HTML:

<img src="<signed-url>" alt="Image from Azure Blob Storage" />

This requires a two-step process: first get the URL from Aidbox API, then use it in your HTML.

Option 2: Use redirect feature

Add ?redirect=true parameter to have Aidbox automatically redirect to the signed URL.

For User delegation SAS and Account SAS:

GET /azure/storage/<container-id>/<blob-path>?redirect=true

For Workload identity:

GET /azure/storage/<storage-account>/<container>/<blob-path>?redirect=true

Both return HTTP 302 redirect with Location header containing the signed URL.

This allows you to directly reference the Aidbox endpoint in HTML:

<!-- User delegation SAS / Account SAS -->
<img src="/azure/storage/<container-id>/<blob-path>?redirect=true" alt="Image" />

<!-- Workload identity -->
<img src="/azure/storage/<storage-account>/<container>/<blob-path>?redirect=true" alt="Image" />