65 lines
3.7 KiB
Markdown
65 lines
3.7 KiB
Markdown
# Azure AI Foundry auth recipe (S4.1)
|
|
|
|
> Verified against Microsoft Learn and the pinned `agent-framework-foundry==1.8.2` in this repo's
|
|
> `.venv` (see `.claude/projects/2026-07-15-s41-azure-preflight/research/01-foundry-auth-recipe.md`).
|
|
> This note is the operator's manual auth recipe for the single planned live Foundry run (M1). The
|
|
> offline `python -m portfolio_optimiser.preflight --profile azure` checks the config; this doc
|
|
> covers what preflight cannot: the actual authentication.
|
|
|
|
## The recipe (local dev, Intel Mac)
|
|
|
|
1. **`az login`** — sign in to the correct Entra tenant with the Azure CLI. This is a **manual**
|
|
operator step; the code never runs it (no auto-login).
|
|
2. The code passes a **lazy `AzureCliCredential()`** (`azure.identity.aio`) to `FoundryChatClient`
|
|
(`AzureFoundryBackend.create_chat_client`). Constructing the credential acquires **no token** —
|
|
the token is fetched from the `az login` session only on the first live call. So passing a
|
|
credential object is *not* auto-login.
|
|
- `AzureCliCredential` is preferred over `DefaultAzureCredential` on a non-Azure host: the latter
|
|
probes the IMDS managed-identity endpoint (times out / stalls) and can pick a stray identity.
|
|
3. Set the config the preflight validates:
|
|
- `PORTFOLIO_FOUNDRY_PROJECT_ENDPOINT` — the Foundry **project** endpoint (below).
|
|
- `PORTFOLIO_MODEL_MAP` — path to an out-of-tree model_map with real azure deployment names, so
|
|
tenant-specific names are never committed. (Or replace the `REPLACE-WITH-*` placeholders.)
|
|
|
|
## FoundryChatClient signature (pinned 1.8.2)
|
|
|
|
`FoundryChatClient(*, project_endpoint, model, credential, ...)` — all keyword-only. **`credential`
|
|
is REQUIRED** on the `project_endpoint` path: the 1.8.2 client raises
|
|
`ValueError("Azure credential is required when using project_endpoint without a project_client.")`
|
|
at construction if omitted. There is **no** lazy `DefaultAzureCredential` default. The model
|
|
parameter is `model` (the portal **deployment name**), not `deployment_name`.
|
|
|
|
## Endpoint format
|
|
|
|
Canonical Foundry project endpoint:
|
|
|
|
```
|
|
https://<resource>.services.ai.azure.com/api/projects/<project>
|
|
```
|
|
|
|
The bare-host form `https://<resource>.services.ai.azure.com` also appears in official samples and
|
|
is accepted. The preflight requires `https://` + a host ending `.services.ai.azure.com`; it does
|
|
**not** require the `/api/projects/` path. A `*.openai.azure.com` or `*.cognitiveservices.azure.com`
|
|
endpoint is a **different** client surface (use `OpenAIChatClient`, not `FoundryChatClient`).
|
|
|
|
## RBAC role
|
|
|
|
Assign **`Foundry User`** (role GUID `53ca6127-db72-4b80-b1b0-d745d6d5456d`) to the identity, at the
|
|
Foundry **resource/project** scope. Do **NOT** use `Azure AI Developer` (scoped to hubs/ML
|
|
workspaces, not Foundry projects) or `Cognitive Services User` (the classic Azure OpenAI surface).
|
|
Note the recent rename: `Foundry User` was formerly `Azure AI User` — reference the GUID, not the
|
|
display name, since older community answers use both.
|
|
|
|
## Preflight is necessary-but-not-sufficient
|
|
|
|
A green `preflight` rules out the **offline-detectable** misconfiguration class: unset endpoint,
|
|
malformed/wrong-surface endpoint URL, unresolved `REPLACE-WITH-*` placeholder deployments, and an
|
|
inconsistent model-map. It **cannot** prove the paid live call will succeed. The following surface
|
|
**only at the live call** and are out of scope for an offline check:
|
|
|
|
- **RBAC** — missing/wrong role → 403 (propagation lag can cause 401-then-200).
|
|
- **Token / tenant / consent** — expired or wrong-tenant credential → 401.
|
|
- **`DeploymentNotFound`** — a well-formed deployment name that does not exist in the project → 404.
|
|
- **api-version skew** and regional outages.
|
|
|
|
Treat a green preflight as "config is shaped correctly", never as "M1 will work".
|