OpenAPI: OpenApiSecuritySchemeReference is not resolved

[vchirikov]

Is there an existing issue for this?

• I have searched the existing issues

Describe the bug

Microsoft.AspNetCore.OpenApi 10.0.0 / Microsoft.OpenApi 2.3.10

I have document transformer:

opt.AddDocumentTransformer((document, _, _) => {
  document.Components ??= new OpenApiComponents();
  document.Components.SecuritySchemes ??=
    new Dictionary<string, IOpenApiSecurityScheme>(StringComparer.Ordinal);
  document.Components.SecuritySchemes.TryAdd("bearer", new OpenApiSecurityScheme {
    Name = "Authorization",
    Description = "Put here **ONLY** Json Web Token",
    Type = SecuritySchemeType.Http,
    Scheme = "bearer",
    BearerFormat = "JWT",
    In = ParameterLocation.Header,
  });
  return Task.CompletedTask;
});
  

which correctly adds the security schema in schema json:

 "securitySchemes": {
      "bearer": {
        "type": "http",
        "description": "Put here **ONLY** Json Web Token",
        "scheme": "bearer",
        "bearerFormat": "JWT"
      },
// ...

But I can't use the OpenApiSecuritySchemeReference to it (it's unresolved):
e.g.

opt.AddOperationTransformer((operation, context, _) => {
  if (context.Description.ActionDescriptor.EndpointMetadata.OfType<IAuthorizeData>().Any()) {
    operation.Security ??= new List<OpenApiSecurityRequirement>();
    operation.Security.Add(new OpenApiSecurityRequirement() {
      { new OpenApiSecuritySchemeReference("bearer"), [] },
    });
  }
});

result json:

"security": [
  { }
]

I also tried add securityschema in operation transformer (which is earlier in pipeline) with no success, the OpenApiSecuritySchemeReference is always unresolved. IDK maybe the bug inside https://github.com/microsoft/OpenAPI.NET

@captainsafia

[vchirikov]

found workaround: explicit reference hostDocument and then ref resolved correctly, but by signature it can be null and looks like it should use the current document as host by default

public OpenApiSecuritySchemeReference(string referenceId, OpenApiDocument? hostDocument = null, string? externalResource = null)

[desjoerd]

I think you need to call document.AddComponent(securityScheme) in your document transformer instead of adding it manually in the components section. That will register it in the workspace and let the resolver work.

I think this is incorrect in the docs at the moment.

Sorry for brevity, from my phone 😅.

[vchirikov]

@desjoerd I tried document.AddComponent("bearer", new OpenApiSecurityScheme {/*...*/}) +

operation.Security ??= new List<OpenApiSecurityRequirement>();
operation.Security.Add(new() { { new("bearer"), [] } });

it doesn't resolve. I also tried full reference id like #/components/securitySchemes/bearer doesn't resolve either

[desjoerd]

I did some digging and I traced it back to this line:

https://github.com/microsoft/OpenAPI.NET/blob/5ebf4793506e5c54ed3e19a9da6b4b846df4d96f/src/Microsoft.OpenApi/Models/OpenApiSecurityRequirement.cs#L86

It checks if the "Target" exists, but that only works when it can Resolve the reference. For reference resolving it needs to have the openapi document.

I totally agree that the nullable hostDocument argument is super confusing. I had the same thoughts, "when not specified, the current document will be used". But it's just not the case.

So for reference, the way OpenApiSecurityReference will work is the following:

operation.Security.Add(new OpenApiSecurityRequirement
{
    { new OpenApiSecuritySchemeReference("bearer", context.Document), ["scope1"] }
});

Related issues:
microsoft/OpenAPI.NET#2300