Hybrid VPC — Azure Blob Storage

This guide covers setting up Hybrid VPC with Azure Blob Storage as your storage backend. Reducto reads and writes documents in one container of your Storage account, and signs short-lived, read-only SAS links to results in that container. Reducto connects in one of two ways:

Managed identity (recommended): Reducto signs in to your Entra ID tenant as a user-assigned managed identity that you own. You give Reducto no secret, and your Storage account can disable shared key access.
Connection string: You give Reducto a Storage account connection string that contains an account key.

Managed identity

You create a user-assigned managed identity in your tenant and add a federated identity credential to it. The credential trusts Reducto’s AWS account, so Reducto signs in as the identity with a short-lived token from AWS instead of a stored secret. Azure role assignments decide what the identity can reach.

Architecture

Reducto’s workers request a short-lived token from AWS. The token names Reducto’s federation role for the region and an audience that contains your Reducto organization ID.
Microsoft Entra ID accepts the token only if your identity’s federated credential matches its issuer, subject, and audience. Entra ID then issues a token for your identity.
Reducto uses that token to read your input documents and to write results and intermediate artifacts to your container.
When a response contains a URL to a result or an image, that URL is a read-only user delegation SAS link to one blob in your container. Reducto signs it with a user delegation key that it requests as your identity. The link expires after at most 12 hours.

Reducto derives the audience from the organization that sends the request. Another Reducto customer who enters your tenant ID and client ID gets a token for their own organization ID, which your federated credential does not trust.

Federated credential values

Add one federated credential to the identity for each Reducto region that processes your documents. All three fields must match exactly.

Field	Value
Issuer	`https://a1fb3098-741e-48ff-bd36-481253997312.tokens.sts.global.api.aws`
Subject	The federation role of the region (see the table below)
Audience	`api://reducto-hybrid-vpc/<your Reducto organization ID>`

Data residency	Subject
US	`arn:aws:iam::731106932034:role/reducto-entra-federation-prod`
EU	`arn:aws:iam::731106932034:role/reducto-entra-federation-prod-eu`
AU	`arn:aws:iam::731106932034:role/reducto-entra-federation-prod-au`

Microsoft Entra ID allows one federated credential per issuer and subject on an identity. Use a separate identity for each Reducto organization that uses the same region.

Prerequisites

Azure subscription with permission to create a managed identity and a Storage account, and to assign roles on the Storage account (Owner, or User Access Administrator plus Contributor)
Terraform 1.2+ with the AzureRM provider 4.65 or later (optional, for automated setup)
Blob data access for the Terraform identity: The Storage account disables shared key access, so the provider calls the Blob data plane with Entra ID (storage_use_azuread = true). Before you apply, assign the user or service principal that runs Terraform Storage Blob Data Contributor on the subscription, because the example creates the resource group during the apply. If you adapt the example to use an existing resource group, you can assign the role on that group instead. Owner and Contributor alone do not include Blob data actions
Your Reducto organization ID (provided during onboarding)

Setup

Terraform
Azure CLI

Create main.tf

terraform {
  required_version = ">= 1.2"
  required_providers {
    azurerm = {
      source  = "hashicorp/azurerm"
      version = ">= 4.65" # user_assigned_identity_id on the federated credential
    }
  }
}

provider "azurerm" {
  features {}
  storage_use_azuread = true # The Storage account disables shared key access
}

variable "name_prefix" {
  type = string
}

variable "location" {
  type    = string
  default = "eastus"
}

variable "reducto_organization_id" {
  type = string
}

variable "reducto_regions" {
  description = "Reducto regions that process your documents: prod (US), prod-eu, prod-au"
  type        = set(string)
  default     = ["prod"]
}

locals {
  reducto_issuer = "https://a1fb3098-741e-48ff-bd36-481253997312.tokens.sts.global.api.aws"
}

resource "azurerm_resource_group" "this" {
  name     = "${var.name_prefix}-reducto-rg"
  location = var.location
}

resource "azurerm_storage_account" "this" {
  name                            = substr(replace("${var.name_prefix}reducto", "-", ""), 0, 24)
  resource_group_name             = azurerm_resource_group.this.name
  location                        = azurerm_resource_group.this.location
  account_tier                    = "Standard"
  account_replication_type        = "LRS"
  min_tls_version                 = "TLS1_2"
  allow_nested_items_to_be_public = false
  shared_access_key_enabled       = false # Reducto signs in with the managed identity
}

resource "azurerm_storage_container" "this" {
  name                  = "reducto-documents"
  storage_account_id    = azurerm_storage_account.this.id
  container_access_type = "private"
}

resource "azurerm_storage_management_policy" "this" {
  storage_account_id = azurerm_storage_account.this.id
  rule {
    name    = "reducto-auto-expire"
    enabled = true
    filters {
      blob_types   = ["blockBlob"]
      prefix_match = ["${azurerm_storage_container.this.name}/"] # Only the Reducto container
    }
    actions {
      base_blob {
        delete_after_days_since_modification_greater_than = 1
      }
    }
  }
}

resource "azurerm_user_assigned_identity" "reducto" {
  name                = "${var.name_prefix}-reducto"
  resource_group_name = azurerm_resource_group.this.name
  location            = azurerm_resource_group.this.location
}

resource "azurerm_federated_identity_credential" "reducto" {
  for_each = var.reducto_regions

  name                      = "reducto-${each.key}"
  user_assigned_identity_id = azurerm_user_assigned_identity.reducto.id
  issuer                    = local.reducto_issuer
  subject                   = "arn:aws:iam::731106932034:role/reducto-entra-federation-${each.key}"
  audience                  = ["api://reducto-hybrid-vpc/${var.reducto_organization_id}"]
}

resource "azurerm_role_assignment" "data" {
  scope                = azurerm_storage_container.this.id
  role_definition_name = "Storage Blob Data Contributor"
  principal_id         = azurerm_user_assigned_identity.reducto.principal_id
  principal_type       = "ServicePrincipal"
}

resource "azurerm_role_assignment" "delegator" {
  scope                = azurerm_storage_account.this.id
  role_definition_name = "Storage Blob Delegator"
  principal_id         = azurerm_user_assigned_identity.reducto.principal_id
  principal_type       = "ServicePrincipal"
}

output "tenant_id" {
  value = azurerm_user_assigned_identity.reducto.tenant_id
}

output "client_id" {
  value = azurerm_user_assigned_identity.reducto.client_id
}

output "account_url" {
  value = azurerm_storage_account.this.primary_blob_endpoint
}

output "container" {
  value = azurerm_storage_container.this.name
}

Initialize and apply

terraform init
# Replace acme, eastus, and the organization ID with your own values.
# Add "prod-eu" or "prod-au" to reducto_regions for EU or AU data residency.
terraform apply \
  -var name_prefix=acme \
  -var location=eastus \
  -var reducto_organization_id="your-reducto-organization-id" \
  -var 'reducto_regions=["prod"]'

Read the values for Reducto

terraform output

Send tenant_id, client_id, account_url, and container to your Reducto team. None of them is a secret.

Create the Storage account and container

RG=acme-reducto-rg
ACCOUNT=acmereducto
CONTAINER=reducto-documents
LOCATION=eastus

az group create -n $RG -l $LOCATION
az storage account create -n $ACCOUNT -g $RG -l $LOCATION --sku Standard_LRS \
  --allow-shared-key-access false --allow-blob-public-access false --min-tls-version TLS1_2
ACCOUNT_ID=$(az storage account show -n $ACCOUNT -g $RG --query id -o tsv)

# Creating a container with --auth-mode login needs a data role for your own user.
az role assignment create --assignee "$(az ad signed-in-user show --query id -o tsv)" \
  --role "Storage Blob Data Owner" --scope $ACCOUNT_ID
az storage container create -n $CONTAINER --account-name $ACCOUNT --auth-mode login

A new role assignment can take a few minutes to apply. If the container command returns AuthorizationPermissionMismatch, wait and retry.

Create the managed identity and its federated credential

IDENTITY=acme-reducto
ORG_ID="your-reducto-organization-id"

az identity create -n $IDENTITY -g $RG -l $LOCATION

# One credential per Reducto region: prod (US), prod-eu, prod-au
for REGION in prod; do
  az identity federated-credential create -n "reducto-$REGION" \
    --identity-name $IDENTITY -g $RG \
    --issuer "https://a1fb3098-741e-48ff-bd36-481253997312.tokens.sts.global.api.aws" \
    --subject "arn:aws:iam::731106932034:role/reducto-entra-federation-$REGION" \
    --audiences "api://reducto-hybrid-vpc/$ORG_ID"
done

Assign the two roles

PRINCIPAL=$(az identity show -n $IDENTITY -g $RG --query principalId -o tsv)

az role assignment create --assignee-object-id $PRINCIPAL --assignee-principal-type ServicePrincipal \
  --role "Storage Blob Data Contributor" \
  --scope "$ACCOUNT_ID/blobServices/default/containers/$CONTAINER"
az role assignment create --assignee-object-id $PRINCIPAL --assignee-principal-type ServicePrincipal \
  --role "Storage Blob Delegator" --scope $ACCOUNT_ID

Read the values for Reducto

az account show --query tenantId -o tsv
az identity show -n $IDENTITY -g $RG --query clientId -o tsv
echo "https://$ACCOUNT.blob.core.windows.net"
echo $CONTAINER

Send these four values to your Reducto team. None of them is a secret.

Components provisioned

Component	Purpose	Required
Storage account	Azure Blob Storage. Shared key access can be off	Yes
Blob container	Container for documents, results, and artifacts	Yes
User-assigned managed identity	The identity that Reducto signs in as	Yes
Federated identity credential	Trusts Reducto’s federation role for one region and your organization	Yes, one per region
Storage Blob Data Contributor on the container	Read and write documents, results, and artifacts	Yes
Storage Blob Delegator on the Storage account	Request user delegation keys to sign result links	Yes
Lifecycle management rule	Automatic blob expiry (default: 1 day)	Recommended

Integration values

Value	Description	Where to find
`tenant_id`	Directory (tenant) ID of the identity	`az account show --query tenantId`
`client_id`	Client ID of the managed identity	Managed identity → Overview
`account_url`	Blob endpoint, `https://<account>.blob.core.windows.net`	Storage account → Endpoints
`container`	Blob container name	Storage account → Containers
Data residency	`us`, `eu`, or `au`: the Reducto region that processes your documents	Your choice

Reducto supports the Azure public cloud (*.blob.core.windows.net) for managed identity connections.

Revoking access

Remove the role assignments to stop Reducto’s access to your data. Azure applies the change within minutes.
Revoke user delegation keys to invalidate result links that Reducto has already signed: az storage account revoke-delegation-keys -n "your-storage-account" -g "your-resource-group". This revokes every user delegation SAS on the Storage account.
Delete the federated credential to stop new sign-ins. An access token that Reducto already holds stays valid until it expires, for up to 24 hours, so also remove the role assignments for immediate effect.

Connection string

Reducto connects with a Storage account connection string that contains an account key. Use this option if you cannot create a managed identity.

Prerequisites

Azure subscription with permission to create a Storage account and read its access keys
Shared key access enabled on the Storage account (allowSharedKeyAccess = true, the Azure default)
Terraform 1.2+ with the AzureRM provider (optional, for automated setup)
Values from Reducto (provided during onboarding): your Reducto organization ID

Architecture

You create a Storage account and a private container.
You send Reducto the container name and the Storage account connection string.
Reducto stores the connection string in a Hybrid VPC environment for your organization. API responses and audit logs never show it after it is saved.
Reducto workers use the connection string to read your input documents and to write results and intermediate artifacts to the container.
When a response contains a URL to a result or an image, that URL is a read-only SAS link to one blob in your container. Reducto signs it with the account key from the connection string. The link expires after at most 12 hours.

Setup

Terraform
Azure Portal (manual)

Create main.tf

terraform {
  required_version = ">= 1.2"
  required_providers {
    azurerm = {
      source  = "hashicorp/azurerm"
      version = ">= 4.0"
    }
  }
}

provider "azurerm" {
  features {}
}

variable "name_prefix" {
  type = string
}

variable "location" {
  type    = string
  default = "eastus"
}

resource "azurerm_resource_group" "this" {
  name     = "${var.name_prefix}-reducto-rg"
  location = var.location
}

resource "azurerm_storage_account" "this" {
  name                            = substr(replace("${var.name_prefix}reducto", "-", ""), 0, 24)
  resource_group_name             = azurerm_resource_group.this.name
  location                        = azurerm_resource_group.this.location
  account_tier                    = "Standard"
  account_replication_type        = "LRS"
  min_tls_version                 = "TLS1_2"
  allow_nested_items_to_be_public = false
  shared_access_key_enabled       = true # Required: Reducto authenticates with the account key
}

resource "azurerm_storage_container" "this" {
  name                  = "reducto-documents"
  storage_account_id    = azurerm_storage_account.this.id
  container_access_type = "private"
}

resource "azurerm_storage_management_policy" "this" {
  storage_account_id = azurerm_storage_account.this.id
  rule {
    name    = "reducto-auto-expire"
    enabled = true
    filters {
      blob_types   = ["blockBlob"]
      prefix_match = ["${azurerm_storage_container.this.name}/"] # Only the Reducto container
    }
    actions {
      base_blob {
        delete_after_days_since_modification_greater_than = 1
      }
    }
  }
}

output "container_name" {
  value = azurerm_storage_container.this.name
}

output "connection_string" {
  value     = azurerm_storage_account.this.primary_connection_string
  sensitive = true
}

Initialize and apply

terraform init
# Replace acme and eastus with your own prefix and Azure region
terraform apply -var name_prefix=acme -var location=eastus

Read the values for Reducto

terraform output container_name
terraform output -raw connection_string

Send both values to your Reducto team through a secure channel. Do not paste the connection string into email or chat.

Create a Storage account

Go to Azure Portal → Storage accounts → Create
Configure:
- Performance: Standard
- Redundancy: LRS (or your preferred level)
Under Advanced, keep Enable storage account key access turned on
Under Networking, keep public network access enabled (see Network access)

Create a Blob container

Open the new Storage account
Go to Data storage → Containers → + Container
Name: reducto-documents
Anonymous access level: Private

Add a lifecycle rule (recommended)

Go to Data management → Lifecycle management → Add a rule
Limit the rule to the Reducto container with the blob prefix reducto-documents/
Delete block blobs 1 day after they were last modified (see Data Lifecycle)

Copy the connection string

Go to Security + networking → Access keys
Select Show next to key1 → Connection string and copy it
Send the connection string and the container name to your Reducto team through a secure channel

Components provisioned

Component	Purpose	Required
Storage account	Azure Blob Storage, with shared key access enabled	Yes
Blob container	Container for documents, results, and artifacts	Yes
Lifecycle management rule	Automatic blob expiry (default: 1 day)	Recommended

Integration values

Value	Description	Where to find
`container`	Blob container name	Storage account → Containers
`connection_string`	Connection string that contains `AccountName` and `AccountKey`	Storage account → Access keys
Data residency	`us`, `eu`, or `au`: the Reducto region that processes your documents	Your choice

The connection string has this form:

DefaultEndpointsProtocol=https;AccountName=<account>;AccountKey=<key>;EndpointSuffix=core.windows.net

A SAS-only connection string (one that contains SharedAccessSignature= and no AccountKey=) is not supported. Reducto can read and write blobs with it, but requests that return result or image URLs fail because Reducto cannot sign SAS links without the account key.

Rotating the account key

The connection string contains one of the two account keys. To rotate without downtime:

Copy the connection string for the key that Reducto does not use (for example, key2).
Send the new connection string to your Reducto team, and wait for confirmation that the environment uses it.
Wait 12 hours. SAS links that Reducto signed with key1 before the switch stay valid for up to 12 hours.
Regenerate the old key (key1) in Access keys.

When you regenerate a key, every SAS link signed with that key stops working immediately. When you regenerate the key that Reducto currently uses, requests also fail until Reducto has the new connection string.

Environments

Reducto registers your values as a Hybrid VPC environment for your organization, with one data residency: us, eu, or au. One organization can have more than one environment, for example one Storage account per data residency or per client (see Multiple Environments). Send requests to the Reducto API of the environment’s data residency:

Data residency	API base URL
US	`https://platform.reducto.ai`
EU	`https://eu.platform.reducto.ai`
AU	`https://au.platform.reducto.ai`

A request that names no environment uses your organization’s default environment for the region of the API that you call. To select an environment, pass its name in settings.hybrid_vpc.environment for /parse, or in parsing.settings.hybrid_vpc.environment for /extract and /split. A request that names an environment of another data residency fails with HTTP 400.

Usage

After Reducto enables the environment, Reducto writes results and intermediate artifacts for your organization to your container. You can also pass a blob in the same Storage account as the input. Reducto reads it with the environment’s credentials, so the blob can stay private. With a managed identity, Reducto can read only the containers the identity has a role on. To read inputs from a container other than the Reducto container, assign Storage Blob Data Reader on that container to the identity. If you configure the recommended lifecycle rule, keep source documents that you want to retain outside the Reducto container, because the rule deletes them (see Data Lifecycle). The examples read your Reducto API key from the REDUCTO_API_KEY environment variable:

export REDUCTO_API_KEY="your-api-key"

from reducto import Reducto

client = Reducto()  # Reads REDUCTO_API_KEY from environment

result = client.parse.run(
    input="https://acmereducto.blob.core.windows.net/reducto-documents/documents/contract.pdf",
)

import Reducto from "reductoai";

const client = new Reducto(); // Reads REDUCTO_API_KEY from environment

const result = await client.parse.run({
  input: "https://acmereducto.blob.core.windows.net/reducto-documents/documents/contract.pdf",
});

curl -X POST "https://platform.reducto.ai/parse" \
  -H "Authorization: Bearer $REDUCTO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"input": "https://acmereducto.blob.core.windows.net/reducto-documents/documents/contract.pdf"}'

Replace acmereducto with your Storage account name and reducto-documents with your container name. For EU or AU data residency, use the regional API base URL from Environments.

Network access

Reducto workers connect to your Storage account over its public blob endpoint (https://<account>.blob.core.windows.net). Azure Private Link is not supported for Azure Blob Storage. If you restrict Public network access to selected networks, contact Reducto before you do so, or Reducto cannot read or write your container. SAS links in responses also use the public blob endpoint. The application that opens those links must be able to reach your Storage account.

Data Lifecycle

Configure lifecycle management to automatically delete blobs after processing. The Terraform examples above create this rule; the Azure CLI steps do not. The rule below deletes every block blob in the Reducto container one day after it was last modified, including documents that you upload there, so keep source documents that you want to retain in another container. Scope the rule to the Reducto container with prefixMatch, so that it does not delete blobs in other containers of the same Storage account:

{
  "rules": [
    {
      "name": "auto-expire",
      "type": "Lifecycle",
      "definition": {
        "actions": {
          "baseBlob": {
            "delete": {
              "daysAfterModificationGreaterThan": 1
            }
          }
        },
        "filters": {
          "blobTypes": ["blockBlob"],
          "prefixMatch": ["reducto-documents/"]
        }
      }
    }
  ]
}

Security

No stored secret (managed identity): Reducto signs in with a short-lived AWS token, and your federated credential accepts it only for your organization. Your Storage account can disable shared key access.
Least privilege (managed identity): The identity holds Storage Blob Data Contributor on the Reducto container only, and Storage Blob Delegator to sign links.
Account key scope (connection string): The account key gives full access to the Storage account, not only to the container. Use a dedicated Storage account for Reducto so that the key cannot reach other data. API responses and audit logs redact the connection string after it is saved.
Short-lived links: Every URL that Reducto returns is a read-only SAS link to one blob. It expires after at most 12 hours.
Automatic cleanup: Lifecycle management policies ensure no long-term data persistence.

Troubleshooting

Error	Cause and fix
`Reducto could not sign in as this managed identity` (HTTP 400)	The tenant ID or client ID is wrong, or no federated credential matches. Check the issuer, the subject for your region, and the audience `api://reducto-hybrid-vpc/<your organization ID>`. A new federated credential can take a few minutes to apply.
`Reducto has no access to this storage` (HTTP 400)	The identity lacks a role. Assign Storage Blob Data Contributor on the container and Storage Blob Delegator on the Storage account, then wait a few minutes.
`Azure container ... does not exist` (HTTP 400)	The container name does not match a container in the Storage account.
A result link returns HTTP 403	The link expired, the user delegation keys were revoked, or the identity lost Storage Blob Data Contributor.
`Azure connection string must include AccountName and AccountKey`	The connection string is SAS-only. Use a connection string with an account key, or use a managed identity.

Get Started

Developer Tools

Core Functions

Workflows and Pipelines

Configurations

Reference

Components

Enterprise Resources

Security and privacy

On-premise Resources

Hybrid VPC — Azure Blob Storage

Managed identity

Architecture

Federated credential values

Prerequisites

Setup

Components provisioned

Integration values

Revoking access

Connection string

Prerequisites

Architecture

Setup

Components provisioned

Integration values

Rotating the account key

Environments

Usage

Network access

Data Lifecycle

Security

Troubleshooting