Missing `mutualTLS` Security Scheme Support in Microsoft.OpenApi

[mdaneri]

Summary

Microsoft.OpenApi does not support the mutualTLS security scheme type introduced in OpenAPI 3.1.
This makes it impossible to accurately represent client certificate (mTLS) authentication using the official OpenAPI object model and writers provided by the library.

Affected Package

• Microsoft.OpenApi
• All versions that include SecuritySchemeType without mutualTLS

Background

The OpenAPI Specification v3.1.0 added a new security scheme type:

type: mutualTLS

This scheme represents mutual TLS (client certificate authentication) at the transport layer.

Reference:

• OpenAPI 3.1 Spec — Security Scheme Object
  https://spec.openapis.org/oas/v3.1.0.html#security-scheme-object

Current Behavior

The SecuritySchemeType enum in Microsoft.OpenApi is defined as:

public enum SecuritySchemeType
{
    ApiKey,
    Http,
    OAuth2,
    OpenIdConnect
}

There is no enum value for mutualTLS.

As a result:

• Consumers cannot model mTLS using OpenApiSecurityScheme
• Writers cannot emit type: mutualTLS
• Users must rely on vendor extensions or documentation-only workarounds
• OpenAPI 3.1 documents generated with Microsoft.OpenApi cannot be spec-complete

Expected Behavior

Microsoft.OpenApi should support OpenAPI 3.1 mutualTLS security schemes natively.

Proposed API Changes (Non-Breaking)

public enum SecuritySchemeType
{
    ApiKey,
    Http,
    OAuth2,
    OpenIdConnect,
    MutualTls // new
}

Writer output:

components:
  securitySchemes:
    mtls:
      type: mutualTLS

Notes

• mutualTLS does not require additional fields
• No scopes or headers are involved
• This is purely a transport-level authentication indicator
• This aligns with OpenAPI 3.1 and does not affect 3.0.x output unless explicitly used

Why This Matters

• mTLS is widely used in:
  • Financial APIs (Open Banking, PSD2)
  • Service meshes (Envoy, Istio)
  • Internal microservice authentication
• Microsoft.OpenApi is commonly used as the canonical OpenAPI model in .NET ecosystems
• Lack of mutualTLS support forces incorrect modeling or lossy documentation

Workarounds Today

• Fake apiKey schemes with documentation disclaimers
• Vendor extensions such as x-mtls
• Out-of-band documentation

All of these are inferior to native support.

Request

Please add first-class support for mutualTLS security schemes in Microsoft.OpenApi to align with OpenAPI 3.1.