Citadel access contract
Or: how to onboard use cases on the AI gateway without manual APIM configuration?
At this point we assume that the assets that we are trying to gain access to, are already deployed using citadel publish contracts.
In Citadel, access contracts are implemented through APIM Products.
A single APIM product is created per contract (so per use case).
This is a bit different from a more traditional usage of Azure API Management where you have one product exposing an API, with many use cases onboarding on the same product. In this typical scenario, you essentially have one contract to manage (which is your backend API spec). In the Citadel gateway, each use case may require fine grained access to several AI capabilities (LLMs, MCP, A2A agents).
Example
Citadel contracts are implemented as infrastructure as code.
Specifically, if using Bicep, the actual contract can be a .bicepparam file.
See this example file.
Contract params
Copied from docs:
| Parameter | Type | Required | Description | Example |
|---|---|---|---|---|
apim |
object | ✅ | APIM instance coordinates | { subscriptionId, resourceGroupName, name } |
keyVault |
object | ✅* | Key Vault for secrets (*required even if not used) | { subscriptionId, resourceGroupName, name } |
useTargetAzureKeyVault |
bool | ❌ | Store secrets in Key Vault (default: false) |
true or false |
useCase |
object | ✅ | Use case naming context | { businessUnit, useCaseName, environment } |
apiNameMapping |
object | ✅ | Map service codes to API names | { OAI: ["azure-openai-service-api"], ... } |
services |
array | ✅ | Services to onboard | See Services Schema below |
productTerms |
string | ❌ | Product terms of service | "By using this product..." |
| useTargetFoundry | bool | ❌ | Create Foundry connections (default: false) | true or false |
| foundry | object | ❌* | Microsoft Foundry coordinates (*required if useTargetFoundry=true) | { subscriptionId, resourceGroupName, accountName, projectName } |
| foundryConfig | object | ❌ | Foundry connection configuration | See Foundry Config below |
| globalGatewayUrl | string | ❌ | Global endpoint (e.g. Front Door) used for all KV/Foundry endpoints (default: '' = primary gateway). See Resiliency Guide | https://ai-gateway.contoso.com |
| additionalApimGateways | array | ❌ | Additional APIM gateways to mirror the contract into, reusing the primary key (default: []) | [{ subscriptionId, resourceGroupName, name }] |
| additionalKeyVaults | array | ❌ | Additional Key Vaults for endpoint + shared key, with endpointSource selector (default: []) | [{ subscriptionId, resourceGroupName, name, endpointSource }] |
| additionalFoundries | array | ❌ | Additional Foundry instances for APIM connections, with endpointSource selector (default: []) | [{ subscriptionId, resourceGroupName, accountName, projectName, endpointSource }] |
Key Rotation: Zero-downtime subscription key rotation is controlled by the optional
usePrimaryKey(defaulttrue) andkeyRotationEnabled(defaultfalse) parameters. Defaults preserve existing behavior. See the Key Rotation Guide.
| usePrimaryKey | bool | ❌ | Which subscription key is active (handed to consumers). true = primary (default), false = secondary. See Key Rotation Guide | true or false |
| keyRotationEnabled | bool | ❌ | Regenerate the non-active key, invalidating its old value (default: false) | true or false |
| rotationKeyOverride | string | ❌ | Explicit rotation key value for deterministic re-runs (default: '' = auto-generate) | <64-char key> |
TODO JWT authentication via policy, see security handler fragments.
JWT Authentication: JWT validation is configured per access contract via the
policies.jwtAuth.enabledfield in the Agent Access Contract Request JSON (see Base Access Contract Request). When enabled, the product policy setsjwtRequired=true, and thesecurity-handlerfragment enforces JWT Bearer token validation in addition to the API key.
Service mapping
Use a shorthand notation that maps onto a service type. The values should be valid API identifiers in APIM.
{
LLM: ["azure-openai-api", "universal-llm-api"]
OAIRT: ["openai-realtime-ws-api"]
DOC: ["document-intelligence-api", "document-intelligence-api-legacy"]
SRCH: ["azure-ai-search-index-api"]
// ... add more services
}
If needed, define custom types which may combine e.g. LLM and DOC services.
Secret management
One subscription key per contract
An access contract may provide access to assets of various types. In Citadel, this contract can be implemented through APIM Products, which provides one subscription key at the product level to provide access to all underlying services.
The underlying endpoints may require secrets of their own, which need to be generated and stored in a key vault. More info
Options
Use key vault for:
- Centralized secret management
- Automatic rotation support
- Access auditing
- Integration with managed identities
Do not directly output secrets in CI/CD.
Skipped for now: For Foundry connections, see this section
TODO: How does the KV flow work exactly?
Permissions
The deployment identity needs:
| Scope | Role | Purpose |
|---|---|---|
| APIM Resource Group | API Management Service Contributor |
Create products and subscriptions |
| Target Key Vault (if used) | Key Vault Secrets Officer |
Write secrets |
| Microsoft Foundry Resource Group (if used) | Contributor |
Create connections |
| Subscription | Reader |
Reference existing resources |
TODO: think about how this works where we maintain everything except the APIM Resource Group and thus don't have service contributordirectly on the APIM RG. ApiOps?
JWT Authentication for Access Contracts
WIP https://github.com/Azure-Samples/ai-hub-gateway-solution-accelerator/blob/main/bicep/infra/citadel-access-contracts/README.md#-jwt-authentication-for-access-contracts
Policy
Detailed guide to access contracts
<inbound>
<base />
<!-- COMMON POLICIES (any asset type) go here, e.g. opt-in content safety -->
<!-- Classify the request as llm | tool | agent -->
<set-variable name="contractToolApis" value="weather-tool,ms-learn-tool" />
<set-variable name="contractAgentApis" value="hr-chat-agent" />
<include-fragment fragment-id="set-asset-kind" />
<choose>
<!-- LLM: model RBAC + token capacity (existing behavior) -->
<when condition="@(context.Variables.GetValueOrDefault<string>("assetKind","llm") == "llm")">
<include-fragment fragment-id="set-llm-requested-model" />
<set-variable name="allowedModels" value="gpt-4o,gpt-4.1" />
<include-fragment fragment-id="validate-model-access" />
<llm-token-limit counter-key="@(context.Subscription.Id)" tokens-per-minute="10000" estimate-prompt-tokens="false" token-quota="1000000" token-quota-period="Monthly" />
</when>
<!-- TOOL (MCP): request-based rate limit + call quota -->
<when condition="@(context.Variables.GetValueOrDefault<string>("assetKind","") == "tool")">
<rate-limit-by-key calls="60" renewal-period="60" counter-key="@(context.Subscription.Id + ":tool")" />
<quota-by-key calls="100000" renewal-period="2592000" counter-key="@(context.Subscription.Id + ":tool")" />
</when>
<!-- AGENT (A2A): request-based rate limit + call quota -->
<when condition="@(context.Variables.GetValueOrDefault<string>("assetKind","") == "agent")">
<rate-limit-by-key calls="30" renewal-period="60" counter-key="@(context.Subscription.Id + ":agent")" />
<quota-by-key calls="50000" renewal-period="2592000" counter-key="@(context.Subscription.Id + ":agent")" />
</when>
</choose>
</inbound>
Classify asset type
Access contract may give access to multiple asset types (llm | agent | tool). This is not known at runtime in APIM (annoyingly), so this policy needs to map the exposed backend asset names (ApiID I think) to a type.
TODO: