Skip to content

docs(design): devex proposal for Bearer tokens with bound credentials#3833

Open
gladjohn wants to merge 2 commits into
masterfrom
gladjohn-patch-4
Open

docs(design): devex proposal for Bearer tokens with bound credentials#3833
gladjohn wants to merge 2 commits into
masterfrom
gladjohn-patch-4

Conversation

@gladjohn
Copy link
Copy Markdown
Contributor

@gladjohn gladjohn commented Jun 1, 2026

What

Adds a developer-experience design document for opting individual
ClientCredentials[] entries into the bound-credential flow when
acquiring Bearer access tokens in Microsoft.Identity.Web.

The doc lives at docs/design/bearer_tokens_with_bound_credentials_devex.md,
alongside the existing managed_identity_capabilities_devex.md and
msi-fic-pure-mtls-pop-devex.md.

Why

When a confidential client app requests a Bearer access token today, the
credential presented to Entra is also a Bearer artifact — a client
assertion JWT signed locally with an X.509 certificate, or a signed
assertion issued by a federation provider (e.g. Managed Identity).

A bound credential is a sender-constrained variant of the same
credential:

  • For an X.509 certificate, MSAL calls the Entra mTLS endpoint and
    presents the certificate over mTLS. No client assertion JWT is created.
  • For a FIC with Managed Identity, MSAL fetches a bound credential bundle
    (signed assertion + binding certificate) from MSI and calls Entra over
    mTLS using the binding certificate.

In both cases the access token returned to the app is a regular Bearer
token
. The downstream API does not change.

The underlying capability is already shipped in MSAL.NET
(#5849)
and a new property is in review on the abstractions
(#252).
This spec covers how IdWeb consumes that property.

What's in scope

  • Per-credential opt-in — one configuration knob on each
    ClientCredentials[] entry. Apps can mix bound and non-bound credentials
    freely.
  • Two credential pathsCertificate (and the certificate-flavored
    sources) and SignedAssertionFromManagedIdentity. Other source types
    ignore the flag.
  • No change to downstream APIs — the access token returned is a regular
    Bearer; the DownstreamApi section is untouched.
  • Two new dev-app samplesdaemon-app-cert-bound and
    daemon-app-fic-bound.
  • Two doc updates
    docs/authentication/credentials/certificates.md and
    docs/authentication/credentials/certificateless.md get a "Use as a bound
    credential" subsection.

What's out of scope

  • Code changes — this PR is docs-only. Implementation lands in a
    follow-up PR once abstractions
    #252
    is finalized.
  • mTLS Proof-of-Possession access tokens — covered separately by
    #3832
    (msi-fic-pure-mtls-pop-devex.md). The two opt-ins are independent.
  • Flows other than client_credentials — the underlying MSAL capability
    currently covers only client_credentials. Other flows are out of scope.

API surface — still being decided

The configuration property name and type are still in review on the
abstractions PR. The current proposal on
#252
is:

public bool UseBoundCredential { get; set; }   // default false

Reviewer feedback has suggested:

public bool? PreferBoundCredential { get; set; }   // default null

so the library default can change over time without breaking explicit
overrides. This IdWeb spec will be updated once #252 is finalized. The
shape and behavior described in the doc are otherwise stable.

Prerequisites for the implementation PR

  • Microsoft.Identity.Web takes a dependency on the abstractions version
    that ships the new property (merge of [Bug] Fixes in MsalSessionTokenCacheProvider.cs #252).
  • MSAL.NET capability is already shipped (#5849).
  • Flow is Entra-only and currently client_credentials-only — not
    enabled in all clouds.
  • No tenant or client allow-listing is required for this flow (unlike mTLS
    PoP access tokens).
  • Platform support for the binding certificate:
    • Certificate flow: any platform.
    • FIC flow: requires the V2 MI credential endpoint, currently Windows
      Confidential VMs (Key Guard + attestation).

This update refines the proposal for bearer tokens with bound credentials in Microsoft.Identity.Web, including clarifications on naming conventions and the developer experience for opting into the bound-credential flow.
@gladjohn gladjohn requested a review from a team as a code owner June 1, 2026 20:21
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant