Bearer Token Auth not working with Swashbuckle and ASPNetZero / ABP - asp.net-core-mvc

Question

I am trying to include security header information in my Swagger specifications and SwaggerUI, as I would like 3rd party systems to easily consume my API, as well as to be able to use CodeGen tools like Swagger CodeGen and NSwag to generate client libraries from it.
I am using Swashbuckle / SwaggerGen to generate the documentation automatically during runtime.
My API makes use of bearer token authentication, and I want my SwaggerDocs to reflect my authentication scheme. I would also be able to see the required security header information in my SwaggerDocs, and have the ability for clients to test out authentication via SwaggerUI when trying out API calls.
However, I have been unable to successfully have my security header information appear on my own solution.
This is what my I currently see when I view my SwaggerDocs through my local SwaggerUI during debugging:
Note that the generated OAS3 markup is correctly rendered when running it through https://editor.swagger.io/
Here is the actual markup that gets produced by Swashbuckle / SwaggerGen:
{
"openapi": "3.0.1",
"info": {
"title": "MyDemo Host API v1",
"version": "v1"
},
"paths": {
"/api/services/app/Tenant/CreateTenant": {
"post": {
"tags": [
"Tenant"
],
"operationId": "ApiServicesAppTenantCreatetenantPost",
"requestBody": {
"content": {
"application/json-patch+json": {
"schema": {
"allOf": [
{
"$ref": "#/components/schemas/CreateTenantInput"
}
]
}
},
"application/json": {
"schema": {
"allOf": [
{
"$ref": "#/components/schemas/CreateTenantInput"
}
]
}
},
"text/json": {
"schema": {
"allOf": [
{
"$ref": "#/components/schemas/CreateTenantInput"
}
]
}
},
"application/*+json": {
"schema": {
"allOf": [
{
"$ref": "#/components/schemas/CreateTenantInput"
}
]
}
}
}
},
"responses": {
"200": {
"description": "Success",
"content": {
"text/plain": {
"schema": {
"$ref": "#/components/schemas/SwaggerDocResponseWrapper"
}
},
"application/json": {
"schema": {
"$ref": "#/components/schemas/SwaggerDocResponseWrapper"
}
},
"text/json": {
"schema": {
"$ref": "#/components/schemas/SwaggerDocResponseWrapper"
}
}
}
}
},
"security": [
{
"bearer": []
}
]
}
}
},
"components": {
"schemas": {
"CreateTenantInput": {
"required": [
"adminEmailAddress",
"name",
"tenancyName"
],
"type": "object",
"properties": {
"tenancyName": {
"maxLength": 64,
"minLength": 0,
"pattern": "^[a-zA-Z][a-zA-Z0-9_-]{1,}$",
"type": "string"
},
"name": {
"maxLength": 128,
"minLength": 0,
"type": "string"
},
"adminEmailAddress": {
"maxLength": 256,
"minLength": 0,
"type": "string",
"format": "email"
},
"adminPassword": {
"maxLength": 128,
"minLength": 0,
"type": "string",
"nullable": true
},
"connectionString": {
"maxLength": 1024,
"type": "string",
"nullable": true
},
"shouldChangePasswordOnNextLogin": {
"type": "boolean"
},
"sendActivationEmail": {
"type": "boolean"
},
"editionId": {
"type": "integer",
"format": "int32",
"nullable": true
},
"isActive": {
"type": "boolean"
},
"subscriptionEndDateUtc": {
"type": "string",
"format": "date-time",
"nullable": true
},
"isInTrialPeriod": {
"type": "boolean"
},
"onSellingPartnerId": {
"type": "integer",
"format": "int32",
"nullable": true
},
"onSellingPartner": {
"allOf": [
{
"$ref": "#/components/schemas/OnSellingPartnerDto"
}
],
"nullable": true
},
"contactPersonFirstName": {
"maxLength": 32,
"type": "string",
"nullable": true
},
"contactPersonLastName": {
"maxLength": 32,
"type": "string",
"nullable": true
},
"contactNumber": {
"maxLength": 24,
"type": "string",
"nullable": true
},
"contactEmail": {
"maxLength": 256,
"type": "string",
"nullable": true
},
"taxNumber": {
"maxLength": 24,
"type": "string",
"nullable": true
},
"registeredName": {
"maxLength": 256,
"type": "string",
"nullable": true
},
"tenantBillingAddress": {
"allOf": [
{
"$ref": "#/components/schemas/TenantBillingAddressInput"
}
],
"nullable": true
}
},
"additionalProperties": false
},
"ValidationError": {
"type": "object",
"properties": {
"message": {
"type": "string",
"nullable": true
},
"members": {
"type": "array",
"items": {
"type": "string"
},
"nullable": true
}
},
"additionalProperties": false
},
"SwaggerDocResponseWrapper": {
"type": "object",
"properties": {
"result": {
"type": "string",
"nullable": true
},
"targetUrl": {
"type": "string",
"nullable": true
},
"success": {
"type": "boolean"
},
"error": {
"allOf": [
{
"$ref": "#/components/schemas/ResponseError"
}
],
"nullable": true
},
"unauthorizedRequest": {
"type": "boolean"
},
"__Abp": {
"type": "boolean"
}
},
"additionalProperties": false
},
"OnSellingPartnerDto": {
"type": "object",
"properties": {
"name": {
"type": "string",
"nullable": true
},
"isActive": {
"type": "boolean"
},
"registeredName": {
"type": "string",
"nullable": true
},
"taxNumber": {
"type": "string",
"nullable": true
},
"contactNumber": {
"type": "string",
"nullable": true
},
"contactPersonFirstName": {
"type": "string",
"nullable": true
},
"contactPersonLastName": {
"type": "string",
"nullable": true
},
"contactEmail": {
"type": "string",
"nullable": true
},
"id": {
"type": "integer",
"format": "int32"
}
},
"additionalProperties": false
},
"TenantBillingAddressInput": {
"type": "object",
"properties": {
"streetAddress": {
"maxLength": 256,
"minLength": 0,
"type": "string",
"nullable": true
},
"region": {
"maxLength": 64,
"minLength": 0,
"type": "string",
"nullable": true
},
"city": {
"maxLength": 64,
"minLength": 0,
"type": "string",
"nullable": true
},
"countryId": {
"type": "integer",
"format": "int32",
"nullable": true
},
"regionCode": {
"maxLength": 6,
"minLength": 0,
"type": "string",
"nullable": true
}
},
"additionalProperties": false
},
"ResponseError": {
"type": "object",
"properties": {
"code": {
"type": "integer",
"format": "int32"
},
"message": {
"type": "string",
"nullable": true
},
"details": {
"type": "string",
"nullable": true
},
"validationErrors": {
"type": "array",
"items": {
"$ref": "#/components/schemas/ValidationError"
},
"nullable": true
}
},
"additionalProperties": false
}
},
"securitySchemes": {
"bearer": {
"type": "http",
"description": "Specify the authorization token.",
"scheme": "bearer",
"bearerFormat": "JWT"
}
}
},
"security": [
{}
]
}
Environment:
AspNetZero Core MVC & JQuery v10.3.0 (.Net 5)
Abp (6.2.0)
Swashbuckle.AspNetCore (5.6.3) & Swashbuckle.AspNetCore.NewtonSoft (6.1.4)
The following code gets called from the ConfiguredServices method in Startup.cs:
public override void InstallServices(IHostEnvironment hostEnvironment, IServiceCollection services, IConfiguration configuration)
{
if (WebConsts.SwaggerUiEnabled)
{
//Swagger - Enable this line and the related lines in Configure method to enable swagger UI
services.AddSwaggerGen(options =>
{
options.SwaggerDoc(ApiNames.HostApiv1, new OpenApiInfo { Title = ApiTitles.HostApiv1, Version = "v1" });
options.SwaggerDoc(ApiNames.PartnerApiv1, new OpenApiInfo { Title = ApiTitles.PartnerApiv1, Version = "v1" });
options.SwaggerDoc(ApiNames.TenantApiv1, new OpenApiInfo { Title = ApiTitles.TenantApiv1, Version = "v1" });
OpenApiSecurityScheme securityDefinition = new OpenApiSecurityScheme()
{
Name = "Bearer",
BearerFormat = "JWT",
Scheme = "bearer",
Description = "Specify the authorization token.",
In = ParameterLocation.Header,
Type = SecuritySchemeType.Http,
};
OpenApiSecurityRequirement securityRequirements = new OpenApiSecurityRequirement()
{
{securityDefinition, new string[] { }},
};
options.AddSecurityDefinition("bearer", securityDefinition);
// Make sure swagger UI requires a Bearer token to be specified
options.AddSecurityRequirement(securityRequirements);
options.DocInclusionPredicate((docName, apiDesc) =>
{
if (!apiDesc.ActionDescriptor.IsControllerAction())
{
return false;
}
apiDesc.TryGetMethodInfo(out MethodInfo methodInfo);
var actionDocs = methodInfo.GetCustomAttributes<SwaggerDocAttribute>()
.SelectMany(a => a.IncludeInDocuments);
var controllerDocs = methodInfo.DeclaringType.GetCustomAttributes<SwaggerDocAttribute>()
.SelectMany(a => a.IncludeInDocuments);
switch (docName)
{
case ApiNames.HostApiv1:
return apiDesc.GroupName == null ||
actionDocs.Contains(ApiNames.HostApiv1) ||
controllerDocs.Contains(ApiNames.HostApiv1);
case ApiNames.PartnerApiv1:
return apiDesc.GroupName == null ||
actionDocs.Contains(ApiNames.PartnerApiv1) ||
controllerDocs.Contains(ApiNames.PartnerApiv1);
case ApiNames.TenantApiv1:
return apiDesc.GroupName == null ||
actionDocs.Contains(ApiNames.TenantApiv1) ||
controllerDocs.Contains(ApiNames.TenantApiv1);
default:
return true;
}
});
options.IgnoreObsoleteActions();
options.IgnoreObsoleteProperties();
options.OrderActionsBy((apiDesc) => $"{apiDesc.RelativePath}");
options.ParameterFilter<SwaggerEnumParameterFilter>();
options.SchemaFilter<SwaggerEnumSchemaFilter>();
options.OperationFilter<SwaggerOperationIdFilter>();
options.OperationFilter<SwaggerOperationFilter>();
options.CustomDefaultSchemaIdSelector();
options.UseAllOfToExtendReferenceSchemas();
var xmlFile = $"{Assembly.GetExecutingAssembly().GetName().Name}.xml";
var xmlPath = Path.Combine(AppContext.BaseDirectory, xmlFile);
options.IncludeXmlComments(xmlPath);
}).AddSwaggerGenNewtonsoftSupport();
}
}
More background information:
I am generating my API documentation into separate SwaggerDocs, for the different types of consumers of my API (Internal / Host applications; Partner applications; Normal tenant / client applications). TI decorate my ApplicationServices (which are dynamically served up as REST-like services during runtime by ABP/AspNetZero) with SwaggerDocsAttribute, which is used to delineate to which one-or-more Swagger docs should include it in its documentation.
[AttributeUsage(AttributeTargets.Class | AttributeTargets.Method, AllowMultiple = true)]
public class SwaggerDocAttribute: Attribute
{
public SwaggerDocAttribute(params string[] includeInDocuments)
{
IncludeInDocuments = includeInDocuments;
}
public string[] IncludeInDocuments { get; }
}
Example usage:
[SwaggerDoc(ApiNames.HostApiv1, ApiNames.PartnerApiv1, ApiNames.TenantApiv1)]
public class SystemStatusAppService: MyDemoAppServiceBase, ISystemStatusAppService
{
[ProducesResponseType(200, Type = typeof(SwaggerDocResponseWrapper))]
public async Task Ping()
{
//Do nothing - will return status code 200
}
[AbpAuthorize()]
[ProducesResponseType(200, Type = typeof(SwaggerDocResponseWrapper))]
public async Task PingWithAuth()
{
//Do nothing - will return status code 200
}
}

Answer 1

You might need to add a reference to your definition in your requirement.
OpenApiSecurityScheme securityDefinition = new OpenApiSecurityScheme()
{
BearerFormat = "JWT",
Scheme = "bearer",
Description = "Specify the authorization token.",
Type = SecuritySchemeType.Http,
};
options.AddSecurityDefinition("Bearer", securityDefinition);
OpenApiSecurityRequirement securityRequirements = new OpenApiSecurityRequirement
{
{
new OpenApiSecurityScheme
{
Reference = new OpenApiReference { Type = ReferenceType.SecurityScheme, Id = "Bearer" }
},
new string[] {}
}
};
options.AddSecurityRequirement(securityRequirements);