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 (default true) and keyRotationEnabled (default false) 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.enabled field in the Agent Access Contract Request JSON (see Base Access Contract Request). When enabled, the product policy sets jwtRequired=true, and the security-handler fragment 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

Policy fragments

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