Boundcredentials

mTLS Proof-of-Possession (PoP)

This skill helps you configure mTLS Proof-of-Possession in applications that use Microsoft.Identity.Web. mTLS PoP cryptographically binds the access token to a client certificate, proving possession of the private key at the transport layer.

When to Use This Skill

• Configuring ProtocolScheme = "MTLS_POP" in DownstreamApi options
• Calling downstream APIs with proof-of-possession tokens
• Troubleshooting 401 errors related to mTLS PoP
• Adding x-ms-tokenboundauth header for Azure Key Vault
• Understanding which credential type to use for mTLS PoP

Credential Types

mTLS PoP supports three credential types. Each binds the token to a certificate differently:

1. Certificate Credential

The app uses its own certificate for both client authentication and PoP token binding.

{
  "AzureAd": {
    "Instance": "https://login.microsoftonline.com/",
    "TenantId": "<tenant-id>",
    "ClientId": "<client-id>",
    "ClientCredentials": [
      {
        "SourceType": "KeyVault",
        "KeyVaultUrl": "https://myvault.vault.azure.net",
        "KeyVaultCertificateName": "my-app-cert"
      }
    ]
  },

  "DownstreamApi": {
    "BaseUrl": "https://myapi.contoso.com/",
    "RequestAppToken": true,
    "ProtocolScheme": "MTLS_POP",
    "Scopes": [ "api://<api-client-id>/.default" ]
  }
}

2. Pure Managed Identity (MSI)

The binding certificate comes from the IMDS v2 credential endpoint on the VM/VMSS. No app-owned cert needed.

Requirements: Azure VM or VMSS with Managed Identity v2 credential endpoint.

System-Assigned MSI

{
  "DownstreamApi": {
    "BaseUrl": "https://myapi.contoso.com/",
    "RequestAppToken": true,
    "ProtocolScheme": "MTLS_POP",
    "Scopes": [ "api://<api-client-id>/.default" ],
    "AcquireTokenOptions": {
      "ManagedIdentity": { }
    }
  }
}

User-Assigned MSI

{
  "DownstreamApi": {
    "BaseUrl": "https://myapi.contoso.com/",
    "RequestAppToken": true,
    "ProtocolScheme": "MTLS_POP",
    "Scopes": [ "api://<api-client-id>/.default" ],
    "AcquireTokenOptions": {
      "ManagedIdentity": {
        "UserAssignedClientId": "<user-assigned-mi-client-id>"
      }
    }
  }
}

3. Federated Identity Credential (FIC)

Uses a managed identity's signed assertion as a client credential for a regular Entra ID app. The downstream call configuration is the same as other types.

{
  "AzureAd": {
    "Instance": "https://login.microsoftonline.com/",
    "TenantId": "<tenant-id>",
    "ClientId": "<app-client-id>",
    "ClientCredentials": [
      {
        "SourceType": "SignedAssertionFromManagedIdentity",
        "ManagedIdentityClientId": "<user-assigned-mi-client-id>"
      }
    ]
  },

  "DownstreamApi": {
    "BaseUrl": "https://myapi.contoso.com/",
    "RequestAppToken": true,
    "ProtocolScheme": "MTLS_POP",
    "Scopes": [ "api://<api-client-id>/.default" ]
  }
}

Azure Key Vault: Extra Header Required

Azure Key Vault uses TLS renegotiation for client certificate presentation. It requires x-ms-tokenboundauth: true to trigger renegotiation. Without it, AKV returns 401: "Client certificate required for using MTLS_POP token."

Other resources (ARM, Storage, Graph) do NOT need this header — they bind the cert on the initial TLS handshake.

Add ExtraHeaderParameters to your AKV service config:

{
  "AzureKeyVault": {
    "BaseUrl": "https://myvault.vault.azure.net/",
    "RelativePath": "secrets/mysecret?api-version=7.4",
    "RequestAppToken": true,
    "ProtocolScheme": "MTLS_POP",
    "Scopes": [ "https://vault.azure.net/.default" ],
    "AcquireTokenOptions": {
      "ManagedIdentity": {
        "UserAssignedClientId": "<your-mi-client-id>"
      }
    },
    "ExtraHeaderParameters": {
      "x-ms-tokenboundauth": "true"
    }
  }
}

Sovereign Clouds

All require "x-ms-tokenboundauth": "true".

How It Works

1. Token Acquisition: ProtocolScheme = "MTLS_POP" tells MSAL to request a PoP token. For MSI, IMDS v2 returns both the token and a binding certificate.

2. HTTP Client: MsalMtlsHttpClientFactory creates an HttpClient with the binding certificate in HttpClientHandler.ClientCertificates.

3. Request: The outbound request carries:

   • Authorization: MTLS_POP <token> — the proof-of-possession token
   • Client certificate via TLS — proves possession of the private key
   • ExtraHeaderParameters — any additional headers (e.g., x-ms-tokenboundauth for AKV)

4. Validation: The resource verifies the token's cnf claim matches the presented certificate thumbprint.

Troubleshooting

References

• mTLS PoP support (PR #3839)
• ExtraHeaderParameters tests (PR #3864)
• Sample: daemon-app-msi-mtls
• Managed Identity docs
• DownstreamApi options