> ## Documentation Index
> Fetch the complete documentation index at: https://www.truefoundry.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Azure Workload Identity Federation Authentication

> Configure keyless Workload Identity Federation for Azure OpenAI, Azure AI Foundry models, and Azure guardrails (PII, Content Safety, Prompt Shield)

<Note>
  Azure Workload Identity Federation is only supported on **self-hosted** deployments of the AI
  Gateway (Gateway Plane only, or Control Plane + Gateway Plane). It does **not** work on the
  **SaaS version of the Gateway**.
</Note>

This guide explains how to configure Workload Identity Federation (WIF) using Microsoft Entra ID
for Azure OpenAI and Azure AI Foundry models in TrueFoundry's AI Gateway. Workload Identity
Federation lets the gateway authenticate to Azure **without any client secrets or certificates**. The
gateway's Kubernetes service account token is exchanged for an Entra ID access token through a
federated identity credential. The same authentication is supported for Azure AI Foundry-based
guardrails: [Azure PII](/docs/ai-gateway/azure-pii),
[Azure Content Safety](/docs/ai-gateway/azure-content-safety), and
[Azure Prompt Shield](/docs/ai-gateway/azure-prompt-shield).

If you prefer secret-based or certificate-based authentication instead, see
[Azure Entra ID Client Secret Based Authentication](/docs/ai-gateway/azure-entra-client-secret-auth)
or [Azure Entra ID Certificate Based Authentication](/docs/ai-gateway/azure-entra-certificate-auth).

## Prerequisites

* A [Microsoft Entra ID application](https://learn.microsoft.com/en-us/entra/identity-platform/quickstart-register-app)
  registered in your Azure tenant
* Azure OpenAI or Azure AI Foundry resource deployed
* The TrueFoundry AI Gateway running on a Kubernetes cluster with a configured OIDC issuer URL, and
  the namespace and service account name used by the gateway pod
* The Kubernetes service account used by the gateway must have permission to issue `TokenRequest`
  resources for itself (the TrueFoundry-provided Helm chart configures this RBAC automatically)

## Azure Configuration

<Steps>
  <Step title="Get Application Details from Entra ID">
    Navigate to [Azure Portal](https://portal.azure.com) > **Microsoft Entra ID** >
    **App registrations** and select your application.

    From the **Overview** page, note the following values:

    * **Application (client) ID**
    * **Directory (tenant) ID**
  </Step>

  <Step title="Add a Federated Identity Credential">
    In your app registration, navigate to **Certificates & secrets** > **Federated credentials** >
    **Add credential**.

    For the **Federated credential scenario**, select **Kubernetes accessing Azure resources**, then
    fill in:

    <Tip>
      Run these commands to look up the values before filling in the form:

      ```bash theme={"dark"}
      # OIDC issuer URL
      kubectl get --raw /.well-known/openid-configuration | jq -r .issuer

      # Service account name: list pods to find the gateway pod, then inspect it
      kubectl get pods -n <namespace>
      kubectl get pod <gateway-pod-name> -n <namespace> -o jsonpath='{.spec.serviceAccountName}'
      ```
    </Tip>

    | Field                | Description                                                 |
    | -------------------- | ----------------------------------------------------------- |
    | Cluster issuer URL   | The OIDC issuer URL of the cluster running the gateway      |
    | Namespace            | The Kubernetes namespace of the gateway pod                 |
    | Service account name | The Kubernetes service account name used by the gateway pod |
    | Name                 | A descriptive name for this federated credential            |

    Azure automatically builds the **Subject identifier** as
    `system:serviceaccount:<namespace>:<service-account-name>` and uses the audience
    `api://AzureADTokenExchange`.

    <Note>
      The namespace and service account name must match the gateway pod's service account
      (the `K8S_SERVICE_ACCOUNT_NAME` the gateway is deployed with). If they don't match, the token
      exchange will fail.
    </Note>

    The **Cluster issuer URL** is your cluster's OIDC issuer (on Amazon EKS it looks like
    `https://oidc.eks.<region>.amazonaws.com/id/EXAMPLED0123456789ABCDEF0123456789`). The
    **Namespace** is where the gateway pod runs (commonly `truefoundry`) and the **Service account name**
    is the `K8S_SERVICE_ACCOUNT_NAME` it is deployed with (defaults to `default`).

    <Frame caption="Add credential form with the Kubernetes accessing Azure resources scenario">
      <img src="https://mintcdn.com/truefoundry/Ql9ugJjyWcbaMcSL/images/azure-entra-wif-federated-credential-form.png?fit=max&auto=format&n=Ql9ugJjyWcbaMcSL&q=85&s=ba7377f02e3333460a8f9156e5a37975" alt="Azure app registration Add credential form showing the Kubernetes accessing Azure resources scenario with cluster issuer URL, namespace, service account name, and the auto-generated subject identifier" width="1400" height="1474" data-path="images/azure-entra-wif-federated-credential-form.png" />
    </Frame>
  </Step>

  <Step title="Assign RBAC Role to App Registration">
    Navigate to your **Azure resource** > **Access control (IAM)** > **Add role assignment**.

    <Tabs>
      <Tab title="Azure OpenAI">
        Assign **Cognitive Services OpenAI User** role to your app registration.

        [Learn more about Azure OpenAI RBAC](https://learn.microsoft.com/en-us/azure/ai-services/openai/how-to/role-based-access-control)
      </Tab>

      <Tab title="Azure AI Foundry">
        Assign **Azure AI User** role to your app registration.

        [Learn more about Azure AI Foundry RBAC](https://learn.microsoft.com/en-us/azure/ai-foundry/concepts/rbac-azure-ai-foundry)
      </Tab>
    </Tabs>

    <Frame caption="Add role assignment for app registration">
      <img src="https://mintcdn.com/truefoundry/62IaXsiblF4PkZxX/images/azure-iam-role-assignment.png?fit=max&auto=format&n=62IaXsiblF4PkZxX&q=85&s=6e726d6aa341dfaf5d99d879431bf526" alt="Access control IAM page showing role assignment" width="2014" height="860" data-path="images/azure-iam-role-assignment.png" />
    </Frame>

    <Info>
      Role assignments may take a few minutes to propagate.
    </Info>
  </Step>
</Steps>

## TrueFoundry Configuration

<Steps>
  <Step title="Configure Workload Identity Authentication">
    <Tabs>
      <Tab title="Azure OpenAI">
        Navigate to **AI Gateway** > **Models** > **Azure OpenAI**, then click **Add Account** and
        select **Workload Identity Federation**. Fill in the following:

        | Field     | Description                                            |
        | --------- | ------------------------------------------------------ |
        | Tenant ID | Directory (tenant) ID from app registration overview   |
        | Client ID | Application (client) ID from app registration overview |

        No secret or certificate is required. The gateway exchanges its Kubernetes service account
        token for an Entra ID access token using the federated identity credential you configured
        above.
      </Tab>

      <Tab title="Azure AI Foundry">
        For Azure AI Foundry, authentication is configured **at the model level**, not the account
        level. When adding a model under **AI Gateway** > **Models** > **Azure AI Foundry**, select
        **Workload Identity Federation** as the authentication type and fill in:

        | Field     | Description                                            |
        | --------- | ------------------------------------------------------ |
        | Tenant ID | Directory (tenant) ID from app registration overview   |
        | Client ID | Application (client) ID from app registration overview |

        No secret or certificate is required. The gateway exchanges its Kubernetes service account
        token for an Entra ID access token using the federated identity credential you configured
        above.
      </Tab>
    </Tabs>
  </Step>

  <Step title="Add Models and Test">
    Add your models as described in the [Azure OpenAI](/docs/ai-gateway/azure-openai) or
    [Azure AI Foundry](/docs/ai-gateway/azure-ai-foundry) documentation.

    Test the connection using the Playground to verify authentication works.
  </Step>
</Steps>

## Reference Links

* [Register an Entra ID application](https://learn.microsoft.com/en-us/entra/identity-platform/quickstart-register-app)
* [Workload identity federation overview](https://learn.microsoft.com/en-us/entra/workload-id/workload-identity-federation)
* [Configure a federated identity credential on an app](https://learn.microsoft.com/en-us/entra/workload-id/workload-identity-federation-create-trust)
* [Azure OpenAI RBAC](https://learn.microsoft.com/en-us/azure/ai-services/openai/how-to/role-based-access-control)
* [Azure AI Foundry RBAC](https://learn.microsoft.com/en-us/azure/ai-foundry/concepts/rbac-azure-ai-foundry)