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

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

Part 1: Set Up the Microsoft Foundry Resource

Step 1: Navigate to Microsoft Foundry

1. Open a browser and go to the Azure Portal.
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:

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://.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.
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:

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:

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:

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.
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:

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

Resource / Project not found

Model not available

Permission errors during setup

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

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

References

• Microsoft Foundry Quickstart: Set Up Resources
• Create a Project in Microsoft Foundry
• Create a Trust Relationship with an External Identity Provider (Federated Credentials)
• Role-Based Access Control for Microsoft Foundry
• Endpoints for Microsoft Foundry Models