Managed in Azure: Setup Guide

This guide lists what your teams do to have DocAI Fabric deployed in your own Azure: you create a new, empty Azure subscription for it, connect the subscription to your network and grant us access. We handle everything else: resource provisioning, Azure OpenAI and Document Intelligence setup, infrastructure configuration, and all future deployments.

DocAI Fabric runs inside your private network. Your users reach it from your corporate network or VPN, and the application is not exposed to the internet. The services that hold your data (document storage, secrets, the job queue and the AI models) are reachable only through private endpoints in your network.

Choose your layout, level of protection and regions in the Overview first.

How Setup Works

Step	Who	What happens	Result
1. Agree the plan	Both	We send your customer ID; together we settle the layout, protection, regions and AI processing	Your choices
2. Prepare and send us the details	You	Subscription, service principal, network, hostnames and certificates, and a review of our log access, for every environment at once	The details we need to deploy
3. Deploy	We	We deploy one environment, test first	Its addresses and its admin key, sent to you
4. Finish the setup	You	DNS records, email, the first administrator, our log access, and the acceptance check	A working environment
5. Close the public endpoints	We	We switch off public network access on the data services	The environment is private end to end

Steps 3 to 5 then repeat for production and any further environment. Everything you do is in this guide; the pages it links to give the details.

Step 1: Agree the Plan

We send you your customer ID: a short identifier, for example acme. Our pipeline uses it to sign in to your subscription (Step 2.3) and it names the resource groups we create.

Together we decide, using the Overview:

Layout: one environment, test and production, or test and production with a recovery region; plus any further environments, such as dev, uat or more than one production
Level of protection for each production environment: Standard, Zone-resilient, Regional recovery or Warm standby
Main region, and the second region if production has a recovery region
Where AI processing happens: Global (recommended), Data zone or Provisioned

Settle the layout and the production levels of protection before our first deployment: like the private network, zone redundancy is fixed when an environment is created.

Step 2: Prepare Your Azure and Send Us the Details

You prepare everything here once, for all your environments, before our first deployment.

Before starting, make sure you have:

Your customer ID from Step 1
Azure CLI installed (install guide)
Permission to create an Azure subscription, or access to a billing administrator who can create one for you
Owner role on the new subscription once created
Permission to register applications in Microsoft Entra ID
Your network team, for Step 2.4

Verify your Entra ID permissions

After az login, check that you can create app registrations:

az ad app create --display-name "permission-test" 2>&1 && \
  az ad app delete --id $(az ad app list --display-name "permission-test" --query "[0].appId" -o tsv)

Success (no errors) → you have the required permissions.
"Insufficient privileges" → your organization restricts app registrations. Ask your IT / Entra ID administrator (someone with the Application Administrator or Global Administrator role) to complete Steps 2.2 and 2.3 on your behalf; the commands are the same.

2.1 Create a New Azure Subscription

The subscription holds DocAI Fabric and nothing else: no other workloads and none of your other data. That is why granting our pipeline Owner on it (Step 2.2) is low-risk: the only things it can reach are DocAI Fabric's resources and the network your team prepares for them. We ask for no permissions outside this subscription. It also follows Azure's guidance of one subscription per application workload.

Create the subscription in the Azure Portal:

Go to Azure Portal → Cost Management + Billing → Subscriptions → Add
Choose an appropriate offer (the same offer type as your other subscriptions)
Name it something clear, e.g. <yourcompany>-docaifabric
Note the Subscription ID once it is created (you can also retrieve it from the CLI):

az login
az account show --query id -o tsv

All your environments live in this subscription, each in its own resource group.

Enterprise Agreement or Microsoft Customer Agreement

If your organisation uses an EA or MCA, your billing administrator may need to create the subscription. The process is the same: ask them to create a new subscription and assign you as Owner so you can complete the remaining steps.

2.2 Create a Service Principal for Our CI/CD

We need a service principal in your Microsoft Entra ID tenant to authenticate our CI/CD pipeline. You create it: it lives in your tenant, under your control. It has no password or secret; our pipeline signs in through OIDC federation (Step 2.3).

Create it:

az login

APP_ID=$(az ad app create \
  --display-name "sp-docaifabric-<YOUR_COMPANY>" \
  --query appId -o tsv)
az ad sp create --id $APP_ID

echo "App ID:    $APP_ID"
echo "Tenant ID: $(az account show --query tenantId -o tsv)"

Note the App ID (also called Client ID) and Tenant ID; you send them to us in Step 2.6.

Grant it Owner on the subscription:

az role assignment create \
  --assignee "$APP_ID" \
  --role Owner \
  --scope "/subscriptions/<YOUR_SUBSCRIPTION_ID>"

If your policy does not allow granting Owner, assign Contributor and User Access Administrator instead: together they give the same permissions, and both are needed.

Grant it on the subscription, not on a resource group you create in advance: we create the resource groups ourselves, and registering support log access needs the subscription scope.

2.3 Configure OIDC Federation

Add one federated credential per environment, so our CI/CD pipeline signs in without any stored secret. You need two things:

Your customer ID from Step 1, for example acme.
Your environment names: you choose them. Use lowercase letters, digits and hyphens, starting with a letter, up to 20 characters: usually test and prod, plus any others you want, such as dev, uat, or several production environments like prod-eu and prod-us.

Set both at the top of the script, then run it:

CUSTOMER_ID="acme"          # the customer ID we sent you
ENVIRONMENTS="test prod"    # your environment names, separated by spaces

APP_ID=$(az ad app list \
  --display-name "sp-docaifabric-<YOUR_COMPANY>" \
  --query "[0].appId" -o tsv)

for ENV in $ENVIRONMENTS; do
  az ad app federated-credential create --id "$APP_ID" --parameters "{
    \"name\": \"github-deploy-$ENV\",
    \"issuer\": \"https://token.actions.githubusercontent.com\",
    \"subject\": \"repo:docaifabric/docaifabric:environment:customer-$CUSTOMER_ID-$ENV\",
    \"audiences\": [\"api://AzureADTokenExchange\"]
  }"
done

A new environment later needs one more credential: run the script again with just its name.

2.4 Prepare the Network

Whether the application is private is fixed when its environment is created; changing it later means downtime and a new IP address. So your network team prepares this before our first deployment.

Subnets

Create a virtual network in the DocAI Fabric subscription, connected to your corporate network the way your other workloads are (for example, peered to your hub). For each environment, it needs two empty subnets in the region from Step 1:

Subnet	Size	Settings	What it holds
Application	`/27` or larger	Delegated to `Microsoft.App/environments`	The application's private load balancer and its replicas
Private endpoints	`/27` or larger	No delegation	One private IP address per data service (about eight)

Environments can share one virtual network, with two subnets each, or use one network each. A recovery region needs its own pair of subnets in the second region: see Disaster Recovery.

If the virtual network must live in another subscription (for example a central network subscription), grant our service principal Network Contributor on the two subnets only, not on the network or its subscription, so it can attach the application and the private endpoints.

Outbound traffic

If outbound traffic from the virtual network goes through a firewall (for example a 0.0.0.0/0 route to your hub firewall), allow the following from the application subnet:

Destination	Port	Why
Service tags `MicrosoftContainerRegistry` and `AzureFrontDoor.FirstParty` (FQDN rules: `mcr.microsoft.com`, `*.data.mcr.microsoft.com`)	443	Azure Container Apps platform images
Service tags `AzureContainerRegistry` and `Storage.<region>` (FQDN rule: the registry name we send you after Step 2.6, `<name>.azurecr.io`)	443	The DocAI Fabric application image
Service tag `AzureActiveDirectory`	443	Sign-in of the application's managed identity
Service tag `AzureMonitor`	443	Logs and metrics
`license.docaifabric.com`	443	Licence check
Your SMTP relay	Its port (usually 587)	Invitation and password-reset emails
Azure DNS `168.63.129.16` (unless the virtual network uses your own DNS servers)	53	Name resolution

Until we close the public endpoints (Step 5), the application may also reach the data services over them, on port 443: *.blob.core.windows.net, *.vault.azure.net, *.openai.azure.com, *.cognitiveservices.azure.com, and *.redis.azure.net on port 10000. Allow these for the first deployment and remove them after Step 5.

Microsoft's reference for Container Apps behind a firewall: Securing a virtual network in Azure Container Apps.

Choose how private endpoints get DNS records

We create the private endpoints in the DocAI Fabric subscription, on your private-endpoint subnet. Each needs a DNS record so the application reaches the service through it. The records themselves come after the deployment; what you decide now is how they are created, because it changes what we deploy. Tell us which of these fits your organisation:

Central private DNS zones (usual in a hub-and-spoke network): the records go into your existing privatelink.* zones for Blob and File storage, Key Vault, Redis, Azure OpenAI, Cognitive Services and Azure AI Services. If your Azure Policy creates the records when an endpoint is created, there is nothing more to do. Otherwise we send you the records (each name and its private IP address) after the deployment, and your team adds them in Step 4. Either way we need no access to your zones.
Zones in the DocAI Fabric resource group: we create the zones and link them to the virtual network. This works only when the virtual network uses Azure-provided DNS; if your DNS servers resolve through a central resolver, use the central zones.

The application itself also needs DNS records, which you create in Step 4 once we send you its private IP address.

Hostname and certificate

Choose a hostname for each environment (for example docai.<yourcompany>.com and docai-test.<yourcompany>.com) and provide a TLS certificate for it as a PFX file with its password. Azure cannot issue a managed certificate for an application that is not reachable from the internet. We agree a secure channel for the certificate; we upload it to the environment.

2.5 Review Our Support Log Access

Our support team needs read-only access to each environment's logs. It is required for a deployment we operate: it is how we detect, diagnose and fix problems without holding credentials or asking you for log excerpts. Have your security team review it now; you confirm it in Step 2.6.

What is granted, through Azure Lighthouse:

the built-in, read-only roles Reader, Log Analytics Reader and Monitoring Reader;
on each DocAI Fabric resource group only, with nothing else in your subscription or tenant;
to one support group in our Microsoft Entra ID tenant. Our team signs in to our own tenant, so no guest accounts appear in your directory and your Conditional Access policies for guests are unaffected;
covering logs, metrics and resource configuration, not the contents of your storage: no documents.

The template that registers it names our tenant, the support group and the three roles, so your security team can see exactly what is granted:

https://app.docaifabric.com/docs/lighthouse/log-access-delegation.json

Who registers it. Our deployment registers it in Step 3, with the service principal from Step 2.2, and you run nothing. If your policy requires your own team to register it, tell us in Step 2.6; you then run one command per environment in Step 4.5, once the resource group exists.

2.6 Send Us the Details

Item	Details
Subscription ID	From Step 2.1 (or `az account show --query id -o tsv`)
Tenant ID	From Step 2.2
Service principal App ID	From Step 2.2
Federated credentials	The subjects you created in Step 2.3, one per environment. This command lists them: `az ad app federated-credential list --id "$APP_ID" --query "[].subject" -o tsv`
Subnet resource IDs	Application and private-endpoint subnet for each environment, in the form `/subscriptions/<sub>/resourceGroups/<rg>/providers/Microsoft.Network/virtualNetworks/<vnet>/subnets/<subnet>`
Private endpoint DNS	Central zones, with or without a policy that creates the records, or zones in our resource group
Hostnames and certificates	One per environment
Acceptance check	The person on your side who runs Step 4 for each environment, or VPN access for our team so we can check it ourselves
Azure Policy	Assignments that apply to the subscription, especially any that restrict SKUs, regions, resource providers or public network access (see Network and Security)
Change window	When we may deploy updates to production
Support log access	Your confirmation of the access in Step 2.5, and whether we register it (the default) or your team does

We reply with each environment's registry name for your outbound rule, and we agree the date of the first deployment.

Azure OpenAI quota

We check the quota available in your subscription during the first deployment and size the models to it. The models we use (gpt-5.4-mini for document processing, gpt-5.4 for the assistant) are usually available on new subscriptions without a quota request. If one is needed, for either model or for higher throughput later, we'll tell you and you submit it via Azure Portal → Quotas → Azure OpenAI (usually approved within a few hours).

Step 3: We Deploy the Environment

We deploy one environment at a time, test first. For each, we:

create its resource group, docailab-<customer-id>-<environment>-rg (for example docailab-acme-prod-rg), and every resource listed in What We Provision;
put the application on your application subnet and the private endpoints on your private-endpoint subnet;
set the application URL to your hostname and upload your certificate;
size the AI capacity to your subscription's quota;
register the read-only support log access, unless your team registers it.

The data services keep their public network access until Step 5, so the environment works before every DNS record is in place.

We then send you:

the environment's private IP address and default domain;
the private endpoint DNS records, if your team adds them by hand;
through the secure channel, the environment's admin key, which you use in Step 4. Keep it in your password vault: it administers the whole environment.

Step 4: Finish the Setup

Your team does this from a machine on your network, for each environment. It takes about an hour.

4.1 Create the DNS Records

For the application: a private DNS zone named after the default domain, with * and @ A records pointing at the private IP address, and an A record for your hostname pointing at the same address.
For the private endpoints, only if your team adds them by hand: the records we sent you, in your central privatelink.* zones.

4.2 Connect the Administration CLI

Install the da command-line tool from your environment and point it at your hostname with the admin key: System Administration (CLI). You use it for the next two steps.

4.3 Set Up Email

Point the application at your SMTP relay, then send yourself a test email: Configure SMTP. The relay's password stays with your team; we never see it. The test email also confirms the application URL: its links must open your hostname.

4.4 Create Your Tenant and First Administrator

Public sign-up is switched off on deployments we operate, so you create the first tenant and its administrator with the CLI:

da admin tenant create "Acme Corp" --admin-email admin@acme.com --admin-name "Ada Lovelace"

The administrator receives an invitation email and then invites the rest of the team from the Team page. More options: Tenants and Sign-up.

4.5 Confirm Our Support Log Access

If your team registers the access (Step 2.5), a subscription Owner runs this for the environment's resource group:

az deployment sub create \
  --name docai-fabric-support-access \
  --location <YOUR_REGION> \
  --template-uri "https://app.docaifabric.com/docs/lighthouse/log-access-delegation.json" \
  --parameters rgName=docailab-<customer-id>-<environment>-rg

Either way, check that it is listed in the Azure Portal under Service providers → Delegations, scoped to the environment's resource group.

4.6 Run the Acceptance Check

Sign in as the new administrator and process a sample document, then tell us the result. Our pipeline cannot reach a private application, so this check is yours (or ours, with VPN access).

Step 5: We Close the Public Endpoints

Once you confirm Step 4, we check that we can read the environment's logs and that the application reaches every data service through its private endpoint, then switch off public network access on storage, Key Vault, Redis, Azure OpenAI and Document Intelligence. The application keeps running throughout. Your firewall team can then remove the public data-service rules from Step 2.4.

Production and further environments repeat Steps 3 to 5. Everything from Step 2 is already in place, so each takes your team only Step 4.

What We Provision on Your Behalf

Resource	Purpose
Resource groups	One per environment, containing everything below
Azure OpenAI: GPT-5.4-mini	Document classification and extraction
Azure OpenAI: GPT-5.4	The in-app assistant
Azure Document Intelligence	OCR processing
Container Apps environment and Container App	Application hosting, on your application subnet
Container Registry	The application image
Azure Managed Redis	Job queue and caching
Storage Account	Document storage
Key Vault	Secrets management
Log Analytics + Application Insights	Logging and monitoring
Managed Identity	Keyless access from the application to the other resources
Private endpoints	Storage, Key Vault, Redis, Azure OpenAI and Document Intelligence, on your private-endpoint subnet

The models listed are our current choice. We recommend changes as better models become available or as your documents require, and make them once you accept.

All resources are created inside your subscription. You retain full ownership and can inspect, modify, or delete anything at any time.

Network and Security

Component	Reachable from	Access control
DocAI Fabric application	Your network and VPN only (private IP address on your application subnet)	DocAI Fabric sign-in
Storage, Key Vault, Redis, Azure OpenAI, Document Intelligence	Your network only (private endpoints; public network access switched off)	The application's managed identity; keys kept in Key Vault
Container Registry	Public endpoint	Microsoft Entra ID only: our pipeline pushes with your service principal, the application pulls with its managed identity. No admin password, no anonymous pull
Log Analytics, Application Insights	Public endpoint	Microsoft Entra ID only; our support team reads logs through Azure Lighthouse, read-only
Deployments	Azure Resource Manager	Your service principal, through OIDC; every change is in your Azure Activity Log

Two components keep a public endpoint, and neither holds your documents:

Container Registry. Our deployment pipeline builds each release and pushes the image into your registry, which it cannot do over a private endpoint. The registry holds only the DocAI Fabric application image, and every push and pull is authenticated with Microsoft Entra ID.
Log Analytics and Application Insights. A private-only workspace would also block the read-only support access described below. These hold application logs and metrics, not documents.

If your Azure Policy denies public network access on these resource types, we need a policy exemption for the DocAI Fabric resource groups' Container Registry, Log Analytics workspace and Application Insights.

Logs and Audit

All logs, metrics, and audit trails live in your subscription; you control access and retention.

What you get	Where it lives	What it captures
Application Insights	Your resource group	App-level telemetry, errors, performance traces
Log Analytics workspace	Your resource group	Container console logs, request logs, custom queries via KQL
Azure Activity Log	Subscription-level (built in)	Every resource change, including deployments performed by our CI/CD, visible to you in real time

Our support team reads them through the read-only access from Step 2.5. How your own team reads them: Application Logs.

Default log retention is 30 days in Log Analytics. If you have compliance requirements for longer retention, let us know: we can configure archive tier or continuous export to Storage when we deploy.

After Go-Live

Updates: we deploy new releases to production in your change window and notify you before and after. Only the application changes; your data and settings stay as they are.
Our log access stays listed under Service providers → Delegations. It is read-only and covers logs and metrics, which hold no documents. You can remove it at any time; as it is how we support the environment, please talk to us first.
Your own monitoring: your team reads the logs and metrics with the Azure tools it already has: Application Logs.
Running the deployment (updates, security, revoking our access): Running Your Deployment.
A recovery region, now or later: Disaster Recovery.

How Setup Works​

Step 1: Agree the Plan​

Step 2: Prepare Your Azure and Send Us the Details​

2.1 Create a New Azure Subscription​

2.2 Create a Service Principal for Our CI/CD​

2.3 Configure OIDC Federation​

2.4 Prepare the Network​

Subnets​

Outbound traffic​

Choose how private endpoints get DNS records​

Hostname and certificate​

2.5 Review Our Support Log Access​

2.6 Send Us the Details​

Step 3: We Deploy the Environment​

Step 4: Finish the Setup​

4.1 Create the DNS Records​

4.2 Connect the Administration CLI​

4.3 Set Up Email​

4.4 Create Your Tenant and First Administrator​

4.5 Confirm Our Support Log Access​

4.6 Run the Acceptance Check​

Step 5: We Close the Public Endpoints​

What We Provision on Your Behalf​

Network and Security​

Logs and Audit​

After Go-Live​