---
title: "Microsoft Azure"
source: "https://docs.vertesiahq.com/environments/azure"
markdown: "https://docs.vertesiahq.com/llms/environments/azure.md"
---

# Microsoft Azure

## Overview

This guide explains how to connect Microsoft Foundry to Vertesia, enabling Vertesia to access large language models (LLMs) hosted by Microsoft on Azure. The integration uses **workload identity federation** (passwordless authentication) through Microsoft Entra ID, meaning no long-lived secrets or API keys from Azure are stored in Vertesia — instead, Vertesia's Security Token Service (STS) exchanges tokens with Microsoft Entra on behalf of each environment.

By the end of this guide, you will have:

- A Microsoft Foundry resource with a project and deployed models
- A Microsoft Entra app registration with a federated credential linked to your Vertesia environment
- The Entra app granted appropriate permissions to call the Microsoft Foundry APIs
- A configured Vertesia environment that can use your Azure-hosted models

---

## Architecture Overview

Understanding the hierarchy of objects is essential before starting:

```
Azure Subscription
└── Resource Group
    └── Microsoft Foundry Resource  (the top-level Azure resource)
        └── AI Foundry Project     (the workspace you use in the portal)
            └── Model Deployments  (the specific models you enable)

Microsoft Entra ID (separate from AI Foundry)
└── App Registration               (represents Vertesia as an external client)
    ├── Federated Credential       (trusts Vertesia's STS to exchange tokens)
    └── Service Principal          (the identity that is assigned roles in Azure)
```

**Key insight:** The Entra App Registration acts as the "bridge" between Vertesia and Azure. Vertesia uses federated identity (not a traditional API key) to request tokens from Microsoft Entra, which then authorizes calls to the Microsoft Foundry APIs. The "API key" field in Vertesia is actually a combination of the **Tenant ID** and **Client ID** from the app registration — not a traditional Azure key.

---

## Prerequisites

Before you begin, ensure you have the following:

### Azure Requirements

| Requirement | Details |
| :---- | :---- |
| Azure account | An active Azure subscription |
| Permissions | **Contributor** role (or higher) on the target subscription or resource group to create Microsoft Foundry resources |
| Role assignment rights | **Owner** role on the subscription or resource group to assign roles to the app registration's service principal |
| Microsoft Entra access | **Application Administrator**, **Cloud Application Administrator**, or equivalent role to create app registrations and federated credentials |

> **Note:** If you have Owner on the subscription, this covers all the above requirements. If you only have Contributor, you will need to work with an Azure administrator to complete the IAM role assignment step.

### Vertesia Requirements

| Requirement | Details |
| :---- | :---- |
| Vertesia account | Access to the Vertesia environment where you want to configure the AI provider |
| Environment ID | The ID of the Vertesia environment (found in the environment settings page URL or settings panel) |
| Vertesia STS Issuer URL | The token issuer URL for Vertesia's Security Token Service (obtain this from your Vertesia administrator or the provider setup instructions in the UI) |

---

## Part 1: Set Up the Microsoft Foundry Resource

### Step 1: Navigate to Microsoft Foundry

1. Open a browser and go to the [Azure Portal](https://portal.azure.com).
2. In the search bar at the top, type **Microsoft Foundry** and select it from the results.
3. You will land on the Microsoft Foundry overview page.

>
> **Important distinction:** There are two types of AI resource in Azure:
>

> - **AI Foundry Resource** (recommended): Provides access to managed foundation models. This is the correct type for most enterprise use cases.
> - **AI Hub Resource** (legacy): Required only for Hugging Face models. Unless specifically requested, use the standard AI Foundry Resource.

### Step 2: Create a Microsoft Foundry Resource

1. From the Microsoft Foundry overview page, click **Create a resource** (or **\+ Create**).
2. A resource creation form will appear. Fill in the following fields:

| Field | Value |
| :---- | :---- |
| **Subscription** | Select your Azure subscription |
| **Resource Group** | Select an existing resource group, or create a new one (e.g., `my-company-ai`) |
| **Region** | Select the Azure region closest to your team or where your data should reside |
| **Name** | Enter a unique name (e.g., `mycompany-ai-resource`). This name will become part of your endpoint URL and **must be globally unique** |
| **Pricing tier** | Standard S0 |

3. Ensure the option to allow project management is enabled (this is typically enabled by default for AI Foundry resources created through the portal).
4. Click **Review \+ Create**, then **Create**.
5. Wait for the deployment to complete (typically 1–3 minutes).

>
> **Endpoint URL Note:** The resource name you choose becomes the subdomain in your endpoint URL. For example, if you name the resource `mycompany-ai`, your endpoint will be `https://mycompany-ai.services.ai.azure.com/`. Both `*.services.ai.azure.com` and `*.openai.azure.com` formats are accepted.

### Step 3: Open the Microsoft Foundry Portal

1. Once the resource is created, navigate to it in the Azure Portal (search for the resource name, or find it in the resource group).
2. On the resource's overview page, click **Go to Microsoft Foundry Portal**.
3. This opens the AI Foundry Portal at `ai.azure.com`, scoped to your resource.

---

## Part 2: Create a Project

Projects are the primary workspaces within an AI Foundry Resource. Each resource can contain multiple projects. Model deployments and API access are organized at the project level.

### Step 4: Create a New Project

1. In the Microsoft Foundry Portal (`ai.azure.com`), look for the project selector in the upper-left area.
2. Click **Create new project** (or select **Create a project** from the main screen).
3. Enter a project name (e.g., `vertesia-production`). This name will also appear in your Vertesia environment configuration.
4. Click **Create project** and wait for the project to initialize.

>
> **Key rule:** One federated credential in Microsoft Entra corresponds to one Vertesia environment. If you plan to connect multiple Vertesia environments (e.g., staging and production) to the same Microsoft Foundry resource, you can reuse the same resource and project with multiple federated credentials — or create separate projects for better isolation.

---

## Part 3: Deploy Models

Before Vertesia can call any models, you must explicitly deploy the models you want to use within your project.

### Step 5: Deploy a Model

1. In the Microsoft Foundry Portal, with your project open, navigate to **Models and Endpoints** in the left sidebar (under the **Build** or **My assets** section).
2. Click **Deploy model**.
3. Select the model catalog source.
4. Browse or search for the model you want.
5. Click **Deploy** on the model you want.
6. A deployment configuration panel will appear:
   - **Deployment name:** A name for this deployment (recommend using the default model name). This name is used when making API calls.
   - **Deployment type:** Standard (recommended for most use cases)
   - **Tokens per minute (TPM) rate limit:** Set based on your expected usage
7. Click **Deploy** to confirm.

>
> **Deployment name matters:** When Vertesia makes API calls, it uses the deployment name you assign here. If you use a custom name, you will need to ensure Vertesia is configured accordingly. Using the default model name simplifies this.

Repeat this step for each model you want to make available through Vertesia.

---

## Part 4: Collect Microsoft Foundry Connection Details

Before moving to the identity configuration, collect the following values — you will need them when configuring Vertesia.

### Step 6: Get Your Resource Name and Project Name

From the AI Foundry Portal, note:

- **Resource Name:** The name you gave the resource in Step 2 (e.g., `mycompany-ai`)
- **Project Name:** The name of the project created in Step 4 (e.g., `mycompany-production`)

The **Endpoint URL** for your Vertesia configuration will be:

```
https://<resource-name>.services.ai.azure.com/
```

> You can also find the project endpoint directly in the AI Foundry Portal on the project overview page (the "project endpoint" field).

---

## Part 5: Create a Microsoft Entra App Registration

This step creates the identity that Vertesia will use to authenticate with Azure. You are not creating a user — you are registering Vertesia as a trusted external application.

### Step 7: Open Microsoft Entra ID

1. Go to the [Azure Portal](https://portal.azure.com).
2. In the search bar, type **Microsoft Entra ID** and select it.

>
> **Navigation note:** Microsoft Entra ID is sometimes referred to as "Azure Active Directory" in older documentation. Accessing it through the Azure Portal (portal.azure.com) is the most straightforward path.

### Step 8: Create an App Registration

1. In the Microsoft Entra ID blade, select **App registrations** from the left navigation menu.
2. Click **\+ New registration** at the top.
3. Fill in the registration form:

| Field | Value |
| :---- | :---- |
| **Name** | A descriptive name for this registration (e.g., `Vertesia Microsoft Foundry Inference` or `vertesia-ai`). This is for your identification only. |
| **Supported account types** | **Accounts in this organizational directory only (Single tenant)** |
| **Redirect URI** | Leave blank — not required for this integration |

4. Click **Register**.

### Step 9: Record the Tenant ID and Client ID

After the app registration is created, you will be on the **Overview** page. Record the following values — you will need them for Vertesia:

| Field | Also Called | Description |
| :---- | :---- | :---- |
| **Application (client) ID** | Client ID | The unique identifier for this app registration |
| **Directory (tenant) ID** | Tenant ID | The unique identifier for your Azure AD / Entra tenant |

These two values combined form the "API key" used in Vertesia:

```
{Tenant ID}:{Client ID}
```

> **Example:** If your Tenant ID is `11111111-aaaa-bbbb-cccc-222222222222` and your Client ID is `33333333-dddd-eeee-ffff-444444444444`, the Vertesia API key would be: `11111111-aaaa-bbbb-cccc-222222222222:33333333-dddd-eeee-ffff-444444444444`

---

## Part 6: Add a Federated Credential

A federated credential tells Microsoft Entra to trust tokens issued by Vertesia's Security Token Service (STS). This is what allows Vertesia to authenticate as the app registration without a traditional password or certificate.

### Step 10: Navigate to Certificates and Secrets

1. In your app registration, select **Certificates & secrets** from the left navigation menu.
2. Click the **Federated credentials** tab.
3. Click **\+ Add credential**.

### Step 11: Configure the Federated Credential

1. In the **Federated credential scenario** dropdown, select **Other issuer**.

>
> **Important:** Select "Other issuer" — not "Managed identity" or any of the pre-configured options (GitHub, Kubernetes, etc.). Vertesia operates as an external OpenID Connect (OIDC) provider.
>

2. Fill in the credential fields:

| Field | Value | Notes |
| :---- | :---- | :---- |
| **Issuer** | Vertesia's STS Issuer URL | This is the URL of Vertesia's token endpoint. Obtain this from your Vertesia administrator or the setup tooltip in the Vertesia provider configuration UI. It will be in a format similar to `https://sts.vertesia.io` or equivalent regional STS endpoint like `https://sts.eu1.vertesia.io`. |
| **Type** | `Explicit subject identifier` | Select the `Explicit subject identifier` option. |
| **Value** | Your Vertesia information | This ties the credential to a specific Vertesia organization/environment. The format is `env:{ORGANIZATION_ID}:{ENVIRONMENT_ID}` to restrict the credential to a single environment, or `env:{ORGANIZATION_ID}` to use the credential in more than one environment within a Vertesia organization. The `ORGANIZATION_ID` is available in the user menu on the right of the top nav bar in Vertesia Studio. The `ENVIRONMENT_ID` is available in the environment settings page. |
| **Name** | A descriptive label | Choose a name that identifies the Vertesia environment this credential is for (e.g., `vertesia-production`). **This name cannot be changed after creation.** |
| **Audience** | `api://AzureADTokenExchange` | Leave this as the default. |

3. Optionally, add a **Description** for future reference (e.g., "Allows Vertesia production environment to access Microsoft Foundry").
4. Click **Add** to save the credential.

>
> **Critical:** The Subject Identifier must exactly match the organization/environment identifier(s) that Vertesia includes in the tokens it sends to Microsoft Entra. If there is a mismatch, token exchange will silently fail. Double-check the value with your Vertesia configuration.
>
> **Scope:** Each federated credential is tied to the Subject Identifier. If you need to connect multiple Vertesia organizations or environments, then create additional federated credentials on the same app registration.

---

## Part 7: Grant the App Registration Access to Microsoft Foundry

The app registration now exists as an identity in Entra, but it does not yet have permission to call Microsoft Foundry APIs. You must grant it the appropriate Azure role on the AI Foundry resource or project.

### Step 12: Assign a Role via IAM

1. Go to the [Azure Portal](https://portal.azure.com).
2. Navigate to your **Microsoft Foundry Resource** (search for the resource name in the search bar, or browse to it via the resource group).
3. In the resource's left navigation menu, select **Access control (IAM)**.
4. Click **\+ Add** \> **Add role assignment**.
5. In the **Role** tab, search for and select **Foundry User**.

>
> **Role guidance:**
>

> - **Foundry User** (formerly **Azure AI User**) — Minimum role required for Vertesia to call AI APIs and run inference. Recommended for least-privilege access.
> - **Contributor** — Broader access; allows creating and modifying resources within the scope. Use only if administrative capabilities are also needed.
> - Do **not** use roles prefixed with "Cognitive Services" for Foundry scenarios.
6. Click **Next** to go to the **Members** tab.
7. For **Assign access to**, select **User, group, or service principal**.
8. Click **\+ Select members**.
9. In the search box, type the name of the app registration you created in Step 8 (e.g., `Vertesia AI Foundry Integration`).
10. Select it from the search results and click **Select**.
11. Click **Review \+ assign**, then **Review \+ assign** again to confirm.

>
> **Scope note:** Assigning the role at the **resource level** grants Vertesia access to all projects within that resource. Assigning it at the **project level** (navigate to the specific project in the Azure Portal, then to its IAM settings) restricts access to that project only, which is the recommended least-privilege approach.

---

## Part 8: Configure Vertesia

With all Azure components in place, you can now configure the Vertesia environment to use Microsoft Foundry as an LLM provider.

### Step 13: Add the Microsoft Foundry Provider in Vertesia

1. Log in to your Vertesia account.
2. Navigate to **Settings** \> **Environments** (or the relevant section for managing AI providers/environments).
3. Select the environment you want to configure, or create a new environment.
4. Choose **Microsoft Foundry** as the AI provider.
5. Fill in the connection details:

| Vertesia Field | Value | Where to Find It |
| :---- | :---- | :---- |
| **Endpoint / Resource Name** | `{resource-name}.services.ai.azure.com` | The name you chose for the Microsoft Foundry Resource in Step 2 |
| **Project Name** | The project name from Step 4 | Visible in the AI Foundry Portal, upper-left project selector |
| **API Key** | `{Tenant ID}:{Client ID}` | From the app registration Overview page (Step 9\) |

> **Endpoint format:** Enter only the resource name portion or the full URL, as instructed by the Vertesia UI. Both `https://{resource-name}.services.ai.azure.com` and `https://{resource-name}.openai.azure.com` are accepted by Azure.
>

6. Save the environment configuration.

### Step 14: Verify the Connection

1. Within Vertesia, test the environment connection using the built-in connection test (if available).
2. Alternatively, create a simple AI task or prompt in the environment and confirm that the response comes back from Azure.
3. If the connection fails, refer to the Troubleshooting section below.

---

## Troubleshooting

### Authentication errors / Token exchange failure

| Symptom | Likely Cause | Resolution |
| :---- | :---- | :---- |
| "Unauthorized" or 401 errors | The app registration's service principal does not have an IAM role on the AI Foundry resource | Re-check Step 12; ensure the role assignment was applied and saved correctly |
| Token exchange fails silently | The Subject Identifier in the federated credential does not match the environment ID Vertesia sends | Verify the Subject Identifier in the federated credential matches the Vertesia environment ID exactly (case-sensitive) |
| Wrong issuer error | The Issuer URL in the federated credential is incorrect | Confirm the issuer URL with your Vertesia administrator and update the credential |

### Resource / Project not found

| Symptom | Likely Cause | Resolution |
| :---- | :---- | :---- |
| "Resource not found" | Incorrect resource name or endpoint URL in Vertesia | Verify the resource name in the Azure Portal and ensure no typos in the Vertesia endpoint field |
| "Project not found" | Incorrect project name | Check the project name in the AI Foundry Portal (it is case-sensitive) |

### Model not available

| Symptom | Likely Cause | Resolution |
| :---- | :---- | :---- |
| Model name not recognized | The model was not deployed in the AI Foundry project | Deploy the model in the AI Foundry Portal (Step 5\) |
| Quota exceeded | The model deployment's TPM (tokens per minute) limit is too low | Increase the TPM limit in the AI Foundry Portal under Models and Endpoints |

### Permission errors during setup

| Symptom | Likely Cause | Resolution |
| :---- | :---- | :---- |
| Cannot see resource group in portal | Missing permissions on the resource group | Ask your Azure administrator to grant Contributor access at the subscription or resource group level |
| Cannot create app registration | Missing Entra permissions | Ask your Azure administrator to grant Application Administrator or Cloud Application Administrator role in Microsoft Entra |

---

## Important Notes and Limitations

### Federated Credentials Per Vertesia Environment

Each federated credential on the Entra app registration is tied to a specific Vertesia orgzanization/environment ID in the Subject Identifier field. This means:

- One Vertesia environment requires one federated credential.
- Multiple credentials can be on the **same** app registration.
- There is a limit of **20 federated credentials** per app registration.

### Resource Type Selection

- Use **Microsoft Foundry Resource** (AIServices type) for standard foundation models.
- **Hub Resources** (the older resource type) are required only for Hugging Face models. Hub resources are considered a more legacy path and new capabilities will primarily be introduced in the standard AI Foundry resource.

### Deployment Names

The deployment name you assign to a model in the AI Foundry Portal is the name used in API calls. It is recommended to use the default model name to avoid confusion, but custom names are supported.

### Endpoint URL Formats

Microsoft Foundry accepts endpoints in two formats — both are equivalent:

- `https://{resource-name}.services.ai.azure.com/`
- `https://{resource-name}.openai.azure.com/`

### Name Immutability

The **Name** field on a federated credential cannot be changed after creation. If you need to rename it, delete the credential and create a new one (the Issuer and Subject can still be the same).

### Azure RBAC Propagation Delay

Role assignments in Azure can take several minutes (up to 10 minutes in some cases) to propagate. If you receive authorization errors immediately after assigning a role, wait a few minutes and try again.

---

## Summary of Values Needed in Vertesia

| Vertesia Setting | Where to Find It |
| :---- | :---- |
| **Endpoint** | `https://{resource-name}.services.ai.azure.com/` — resource name from Step 2 |
| **Project Name** | Chosen in Step 4, visible in AI Foundry Portal |
| **API Key** | `{Tenant ID}:{Client ID}` from app registration Overview (Step 9\) |

And the values needed for the federated credential in Microsoft Entra (Step 11):

| Credential Field | Value |
| :---- | :---- |
| **Issuer** | Vertesia's STS URL |
| **Subject Identifier** | Vertesia organization/environment ID from Vertesia Studio |
| **Audience** | `api://AzureADTokenExchange` |

---

## References

- [Microsoft Foundry Quickstart: Set Up Resources](https://learn.microsoft.com/en-us/azure/foundry/tutorials/quickstart-create-foundry-resources)
- [Create a Project in Microsoft Foundry](https://learn.microsoft.com/en-us/azure/foundry/how-to/create-projects)
- [Create a Trust Relationship with an External Identity Provider (Federated Credentials)](https://learn.microsoft.com/en-us/entra/workload-id/workload-identity-federation-create-trust)
- [Role-Based Access Control for Microsoft Foundry](https://learn.microsoft.com/en-us/azure/foundry/concepts/rbac-foundry)
- [Endpoints for Microsoft Foundry Models](https://learn.microsoft.com/en-us/azure/foundry/foundry-models/concepts/endpoints)