Microsoft Identity Web

Microsoft.Identity.Web provides secure defaults for authentication and authorization, but allows for several customization areas. You can customize:

• Configuration: All MicrosoftIdentityOptions, OpenIdConnectOptions, and JwtBearerOptions properties.
• Events: OpenID Connect events like OnTokenValidated, OnRedirectToIdentityProvider, etc.
• Token Acquisition: Correlation IDs and extra query parameters.
• Claims: Adding custom claims to the ClaimsPrincipal.
• UI: Sign-out pages and redirect behavior.
• Sign-In: Login hints and domain hints.

Customization Methods

You can use two primary approaches to apply customizations:

1. Configure<TOptions>: Configures options before they are used.
2. PostConfigure<TOptions>: Configures options after all Configure calls have been executed.

Execution Order: Configure $\rightarrow$ Configure $\rightarrow$ ... $\rightarrow$ PostConfigure $\rightarrow$ PostConfigure $\rightarrow$ ... $\rightarrow$ Options used

Token Binding (mTLS PoP) is an advanced security feature that cryptographically binds access tokens to a specific X.509 certificate (as described in RFC 8705).

How it works:

1. Token Acquisition: The client requests a token including the certificate's thumbprint.
2. Token Binding: The authorization server issues a token containing a cnf (confirmation) claim with the certificate's SHA-256 thumbprint (x5t#S256).
3. API Call: The client sends both the bound token and the client certificate to the downstream API.
4. Verification: The API validates that the certificate presented in the TLS connection matches the thumbprint in the token's cnf claim.

Security Benefits:

• Token Theft Protection: Stolen tokens cannot be used without the corresponding private key.
• Replay Attack Prevention: Tokens cannot be replayed from different clients.
• Zero Trust Alignment: Binds credentials to specific devices.

For complex authorization logic, use ASP.NET Core Authorization Policies. Policies allow you to centralize rules, combine multiple requirements (scopes, roles, and custom claims), and make authorization logic testable and reusable.

Common Patterns:

• Policy with RequireScope: Use policyBuilder.RequireScope("scope1", "scope2") within AddAuthorization to define a named policy.
• Default Policy: Set a DefaultPolicy in AddAuthorization so that every [Authorize] attribute automatically enforces those requirements.
• Combining Requirements: Use policyBuilder.RequireRole("Admin") alongside RequireScope to create multi-factor authorization rules.
• Custom Requirements: Use policyBuilder.AddRequirements(new ScopeAuthorizationRequirement(...)) for low-level policy construction.

builder.Services.AddAuthorization(options =>
{
    // Pattern 1: Named Policy
    options.AddPolicy("TodoReadPolicy", policyBuilder =>
    {
        policyBuilder.RequireScope("read", "access_as_user");
    });

    // Pattern 2: Default Policy (applies to all [Authorize] attributes)
    options.DefaultPolicy = new AuthorizationPolicyBuilder()
        .RequireScope("access_as_user")
        .Build();

    // Pattern 3: Complex Policy
    options.AddPolicy("AdminPolicy", policyBuilder =>
    {
        policyBuilder.RequireScope("admin");
        policyBuilder.RequireRole("Admin");
        policyBuilder.RequireAuthenticatedUser();
    });
});

// Usage in Controller
[Authorize(Policy = "TodoReadPolicy")]
public IActionResult Get() => Ok();

Microsoft Identity Web uses a provider-based architecture to resolve credentials (like client secrets, certificates, or Managed Identity assertions) and wire them into MSAL (Microsoft Authentication Library) for token acquisition.

High-Level Flow

1. App requests an authorization header via DefaultAuthorizationHeaderProvider.
2. TokenAcquisition service determines if token binding is required.
3. CredentialsProvider calls a Credential Loader to resolve the actual credential.
4. The resolved credential is passed to MSAL (e.g., via .WithClientSecret, .WithCertificate, or .WithClientAssertion) to execute the token request.

Credential Type vs. Token Type Support

Token binding can be used in conjunction with Federated Identity Credentials (FIC). In these flows, the binding certificate is automatically returned by the inner token acquisition process and flows through to the outer application.

Scenario 1: Final mtls_pop token

When the caller requests ProtocolScheme = "MTLS_POP", the inner OIDC exchange is performed in token-binding mode. The final access token is mtls_pop, bound to the certificate returned by the inner acquisition.

Configuration Example:

{
  "AzureAd": {
    "Instance": "https://login.microsoftonline.com/",
    "TenantId": "<outer-tenant>",
    "ClientId": "<outer-client-id>",
    "ClientCapabilities": [ "cp1" ],
    "ClientCredentials": [
      {
        "SourceType": "CustomSignedAssertion",
        "CustomSignedAssertionProviderName": "OidcIdpSignedAssertion",
        "CustomSignedAssertionProviderData": { "ConfigurationSection": "OidcFicIdp" }
      }
    ]
  },
  "OidcFicIdp": {
    "Instance": "https://login.microsoftonline.com/",
    "TenantId": "<inner-tenant>",
    "ClientId": "<inner-client-id>",
    "ClientCredentials": [
      {
        "SourceType": "StoreWithDistinguishedName",
        "CertificateStorePath": "CurrentUser/My",
        "CertificateDistinguishedName": "CN=MyInnerAppCert"
      }
    ]
  }
}

Note: Register the provider with services.AddOidcFic();.

Scenario 2: Final Bearer token using bound client assertion

If you want the client assertion to be sender-constrained (sent as jwt-pop over mTLS) but want the resulting access token to be a regular Bearer token (to avoid affecting downstream APIs), set UseBoundCredential = true on the outer OIDC CustomSignedAssertion credential and do not request MTLS_POP.

Configuration Example:

{
  "ClientCredentials": [
    {
      "SourceType": "CustomSignedAssertion",
      "CustomSignedAssertionProviderName": "OidcIdpSignedAssertion",
      "CustomSignedAssertionProviderData": { "ConfigurationSection": "OidcFicIdp" },
      "UseBoundCredential": true
    }
  ]
}

Key Takeaways for FIC + Token Binding

• The binding certificate flows automatically from the inner acquisition to the outer application.
• You do not need to configure a second binding-certificate credential.
• UseBoundCredential is used for the Bearer token scenario.
• ProtocolScheme = "MTLS_POP" is used for the mtls_pop token scenario.

A Correlation ID is a GUID that uniquely identifies an authentication or token acquisition request across your application, the Microsoft Identity platform, MSAL.NET, and Microsoft backend services. These are critical when contacting Microsoft support.

Obtaining Correlation IDs

1. From AuthenticationResult

When a token is successfully acquired, the CorrelationId is available on the result object.

2. From MsalServiceException

If token acquisition fails, the exception contains a CorrelationId that can be logged or returned to the user.

3. Setting a Custom Correlation ID

You can pass a custom correlation ID (such as an Activity.Current.Id or HttpContext.TraceIdentifier) when calling downstream APIs using TokenAcquisitionOptions.

// Example: Obtaining CorrelationId from MsalServiceException
try
{
    var token = await _tokenAcquisition.GetAccessTokenForUserAsync(new[] { "user.read" });
}
catch (MsalServiceException ex)
{
    _logger.LogError(ex, "Token acquisition failed. CorrelationId: {CorrelationId}, ErrorCode: {ErrorCode}", ex.CorrelationId, ex.ErrorCode);
}

// Example: Setting a custom CorrelationId for downstream API calls
await _downstreamApi.GetForUserAsync<Todo>("TodoListService", options =>
{
    options.TokenAcquisitionOptions = new TokenAcquisitionOptions
    {
        CorrelationId = Guid.Parse(customCorrelationId)
    };
});

Microsoft.Identity.Web follows strict rules to prevent configuration conflicts. You must choose one of two approaches. Setting both will cause an InvalidOperationException at startup.

The Two Approaches

1. Authority Only: Provide a single Authority URL. The library parses this into an Instance and TenantId.
2. Instance + TenantId: Provide Instance and TenantId separately. This is the preferred method for Azure AD (AAD) to enable AAD-specific security and resilience.

Precedence Table

*Note: For single-tenant apps, always specify TenantId when using Instance.