OpenAPI 3.2: `oauth2MetadataUrl` Missing from `Microsoft.OpenApi.OpenApiSecurityScheme`

[mdaneri]

Summary

Microsoft.OpenApi can serialize OpenAPI 3.2 documents, but the Security Scheme Object is missing support for the OpenAPI 3.2 field:

• oauth2MetadataUrl (type: string, format: uri, applies to type: oauth2)

This prevents consumers from producing spec-complete OpenAPI 3.2 documents when describing OAuth2 servers using RFC 8414 metadata.

Spec Reference

OpenAPI 3.2.0 adds oauth2MetadataUrl to the Security Scheme Object. citeturn0search0turn0search10
The field is defined as a URL to the OAuth2 authorization server metadata (RFC 8414). citeturn0search5turn0search2

Current Behavior

OpenApiSecurityScheme does not expose a property for oauth2MetadataUrl, and the serializer does not emit it for OpenAPI 3.2 output.

Even when using SerializeAsV32, the switch over SecuritySchemeType only handles:

• apiKey: name, in
• http: scheme, bearerFormat
• oauth2: flows
• openIdConnect: openIdConnectUrl

There is no native way to model and serialize oauth2MetadataUrl other than vendor extensions.

Expected Behavior

When Type == SecuritySchemeType.OAuth2 and the target spec version is OpenAPI 3.2+, the library should allow setting and serializing:

components:
  securitySchemes:
    oauth:
      type: oauth2
      oauth2MetadataUrl: https://idp.example.com/.well-known/oauth-authorization-server
      flows:
        clientCredentials:
          tokenUrl: https://idp.example.com/oauth/token
          scopes: {}

Proposed API Change

Add a nullable Uri property to OpenApiSecurityScheme:

public Uri? OAuth2MetadataUrl { get; set; }

Serialization (OpenAPI 3.2+ only)

In SerializeInternal(...), under case SecuritySchemeType.OAuth2: write the property before/after flows:

if (version >= OpenApiSpecVersion.OpenApi3_2)
{
    writer.WriteProperty("oauth2MetadataUrl", OAuth2MetadataUrl?.ToString());
}
writer.WriteOptionalObject(OpenApiConstants.Flows, Flows, callback);

Parsing / Reading

If the library includes readers/deserializers for security schemes, they should also recognize oauth2MetadataUrl when parsing OpenAPI 3.2 documents into OpenApiSecurityScheme.

Why This Matters

OAuth2 Authorization Server Metadata (RFC 8414) is widely used to publish endpoints and capabilities. OpenAPI 3.2 explicitly supports linking to that metadata; without this field, OpenAPI 3.2 documents generated with Microsoft.OpenApi cannot fully represent the spec-defined OAuth2 security scheme information. citeturn0search5turn0search7

Workarounds Today

• Use Extensions["x-oauth2MetadataUrl"] = ... (non-standard)
• Put the URL in description (lossy / not machine-readable)

Request

Please add first-class support for oauth2MetadataUrl to OpenApiSecurityScheme and include it in OpenAPI 3.2 serialization/parsing for OAuth2 security schemes.

Thank you!