> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.mixlayer.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.mixlayer.com/_mcp/server.

# Azure Workload Identity

> Authenticate Azure workloads with a managed identity

An Azure workload can use its managed identity to request a short-lived Microsoft Entra access token. Mixlayer verifies that token and exchanges it for a short-lived Mixlayer access token, so the workload does not need a stored Mixlayer API key.

This guide uses a user-assigned managed identity so its lifecycle is independent of any one Azure resource. A system-assigned identity also works.

## 1. Create the audience application

In the [Microsoft Entra admin center](https://entra.microsoft.com), create a single-tenant app registration to represent Mixlayer as the token audience:

1. Open **App registrations**, select **New registration**, and choose **Accounts in this organizational directory only**.
2. Under **Expose an API**, add the default Application ID URI: `api://<application-client-id>`.
3. Open **Manifest** and set `api.requestedAccessTokenVersion` to `2`.
4. Record the application (client) ID and your Microsoft Entra tenant ID.

The application registration contains no Mixlayer secret. It gives the managed identity a dedicated audience for tokens intended for Mixlayer.

## 2. Assign a managed identity

Create or select a user-assigned managed identity and attach it to the Azure resource that runs your workload. Record both identifiers:

| Identifier            | Use                                                                   |
| --------------------- | --------------------------------------------------------------------- |
| Client ID             | Selects the user-assigned identity when the workload requests a token |
| Object (principal) ID | Identifies the workload in Mixlayer policy                            |

All code running within an Azure resource can request tokens for identities assigned to that resource. Do not share the resource with workloads that should have different Mixlayer access.

## 3. Configure the Mixlayer provider

Create an OIDC provider in [Workload Identity](https://console.mixlayer.com/app/workload-identity):

| Setting          | Value                                                |
| ---------------- | ---------------------------------------------------- |
| Issuer URI       | `https://login.microsoftonline.com/<tenant-id>/v2.0` |
| Allowed audience | The audience application's client ID                 |
| JWKS source      | OIDC discovery                                       |

Map the immutable managed-identity object ID and tenant:

```text
mixlayer.subject    = assertion.oid
attribute.tenant_id = assertion.tid
```

Admit only the expected tenant and managed identity:

```cel
attribute.tenant_id == "00000000-0000-0000-0000-000000000000" &&
mixlayer.subject == "11111111-1111-1111-1111-111111111111"
```

Replace the placeholders with your tenant ID and the managed identity's object (principal) ID. Use `true` as the final authorization rule and grant only the permissions the workload needs.

## 4. Request an Entra token

From an Azure VM or virtual machine scale set, request a token through the Instance Metadata Service. The `resource` is the Application ID URI, while the resulting v2 token's `aud` claim is the application's client ID.

**`file=`**

```bash file=get-azure-managed-identity-token.sh
export AZURE_WIF_APPLICATION_ID="22222222-2222-2222-2222-222222222222"
export AZURE_MANAGED_IDENTITY_CLIENT_ID="33333333-3333-3333-3333-333333333333"

export MIXLAYER_SUBJECT_TOKEN=$(
  curl --fail-with-body --silent --show-error --get \
    http://169.254.169.254/metadata/identity/oauth2/token \
    -H "Metadata: true" \
    --data-urlencode "api-version=2018-02-01" \
    --data-urlencode "resource=api://$AZURE_WIF_APPLICATION_ID" \
    --data-urlencode "client_id=$AZURE_MANAGED_IDENTITY_CLIENT_ID" |
  jq -er .access_token
)
```

Omit `client_id` when using a system-assigned identity. Other Azure hosting services expose managed identity through service-specific endpoints; use the Azure Identity SDK there to request a token for `api://<application-client-id>`.

## 5. Exchange and use the Entra token

**`file=`**

```bash file=exchange-azure-workload-identity.sh
MIXLAYER_ACCESS_TOKEN=$(
  jq -n \
    --arg provider "$MIXLAYER_IDENTITY_PROVIDER_ID" \
    --arg token "$MIXLAYER_SUBJECT_TOKEN" \
    '{
      grant_type: "urn:ietf:params:oauth:grant-type:token-exchange",
      subject_token_type: "urn:ietf:params:oauth:token-type:jwt",
      subject_token: $token,
      identity_provider_id: $provider
    }' |
  curl --fail-with-body --silent --show-error \
    https://api.mixlayer.com/v1/workload_identity/token \
    -H "Content-Type: application/json" \
    --data-binary @- |
  jq -er .access_token
)

curl https://mixlayer.ai/v1/models \
  -H "Authorization: Bearer $MIXLAYER_ACCESS_TOKEN"
```

Cache the Mixlayer token in memory until shortly before expiry, then request and exchange a new Entra token.

## Troubleshooting

* Decode a sample token locally and confirm `ver` is `2.0`, `iss` exactly matches the provider, and `aud` is the audience application's client ID.
* Confirm `oid` is the managed identity's object (principal) ID, not its client ID.
* If the VM has multiple user-assigned identities, include the intended identity's client ID in the metadata request.
* A metadata error about an unknown resource usually means the Application ID URI is incorrect or belongs to another tenant.
* Do not proxy the Instance Metadata Service or log either access token.