# Azure OpenAI and AI Foundry

Avallone can use your Azure OpenAI or AI Foundry deployment as its AI provider. Avallone signs in to the deployment with your app registration, so you don't need to give it an API key.

## Before you start

- Set up [Microsoft credentials](/connectors/microsoft/credentials) for your tenant, Avallone-managed or Custom.
- Deploy the models you want Avallone to use to an Azure OpenAI or AI Foundry resource.

> [!NOTE]
> With Avallone-managed credentials, Avallone does not show the client ID that Step 1 needs. Contact Avallone support for it before you start.

## Step 1: Give the app registration access to the resource

Azure OpenAI access is not an API permission on the app registration. It is an Azure role assignment on the Azure OpenAI resource.

In the Azure portal:

1. Open the Azure OpenAI or AI Foundry resource behind the endpoint. That is the `<name>` in `https://<name>.openai.azure.com`.
2. Go to **Access control (IAM) → Add → Add role assignment**.
3. Choose the role **Cognitive Services OpenAI User**. It lets Avallone call the chat completions and embeddings APIs of the deployment.
4. Under **Members**, choose **User, group, or service principal**. Search for your app registration by name or client ID, select it, and assign the role.

Or with the Azure CLI:

```bash
az role assignment create \
  --assignee "<clientId>" \
  --role "Cognitive Services OpenAI User" \
  --scope /subscriptions/<sub-id>/resourceGroups/<rg>/providers/Microsoft.CognitiveServices/accounts/<resource-name>
```

> [!WARNING]
> Other roles don't work. Reader, Contributor and **Cognitive Services User** manage the resource, but don't let Avallone call the models. With one of them, Azure answers `401 Principal does not have access to API/Operation`. Note that Cognitive Services User is a different role from Cognitive Services OpenAI User.

Assign the role on the resource the endpoint points at, or on its resource group. A new role assignment can take a few minutes to take effect.

## Step 2: Set up the endpoint in Avallone

1. Go to **Settings → Avallone AI**.
2. Choose **Custom (OpenAI-compatible)** as the provider.
3. Enter the **Endpoint**. That is the base URL of your Azure OpenAI deployment, such as `https://<name>.openai.azure.com/openai/v1/`.
4. Check **Use Microsoft credentials**, instead of entering an API key.
5. Select the models to use.
6. Save, then click **Test** to check that Avallone can reach the deployment.

If the test fails right after you assigned the role, wait a few minutes and try again.

## References

- [Azure OpenAI API prerequisites](https://learn.microsoft.com/en-us/azure/foundry/openai/api-version-lifecycle?tabs=python#prerequisites): requires the Cognitive Services OpenAI User role.
- [Configure Microsoft Entra ID for Foundry Models](https://learn.microsoft.com/en-us/azure/foundry/foundry-models/how-to/configure-entra-id): how to set up Entra ID sign-in in general.
- [Control plane and data plane](https://learn.microsoft.com/en-us/azure/foundry/concepts/authentication-authorization-foundry#control-plane-and-data-plane): why roles that manage the resource can't call the models.