Add an authorization header to your swagger-ui with Swashbuckle (revisited)

Just over a year ago I blogged a simple way to add an authorization header to your swagger-ui with Swashbuckle. Although that works, Swagger-UI and Swashbuckle support a better way, which I’ll describe below.

Before starting I assume you’ve already got OAuth2 setup correctly on your application (using bearer tokens), and you have decorated your controllers and actions with [Authorize] attributes. If you haven’t, that is beyond the scope of this blog post. Here all I’m doing is explaining how to configure Swashbuckle.

First, you need to tell Swashbuckle what security your API has:

services.AddSwaggerGen(options =>
{
    options.AddSecurityDefinition("oauth2", new ApiKeyScheme
    {
        Description = "Standard Authorization header using the Bearer scheme. Example: \"bearer {token}\"",
        In = "header",
        Name = "Authorization",
        Type = "apiKey"
    });

This adds a securityDefinition to the bottom of the Swagger document, which Swagger-UI renders as an “Authorize” button:

Clicking that brings up a dialog box where you can put your bearer token:

The next thing we need to do is tell Swashbuckle which of our actions require Authorization. To do that you can use the SecurityRequirementsOperationFilter:

services.AddSwaggerGen(options =>
{
    options.AddSecurityDefinition("oauth2", new ApiKeyScheme
    {
        Description = "Standard Authorization header using the Bearer scheme. Example: \"bearer {token}\"",
        In = "header",
        Name = "Authorization",
        Type = "apiKey"
    });

    options.OperationFilter<SecurityRequirementsOperationFilter>();

You can either download the SecurityRequirementsOperationFilter from here, or, if you’re using ASP.NET Core you can install my Swashbuckle.AspNetCore.Filters package from NuGet, which includes it (and other filters).

The SecurityRequirementsOperationFilter adds a security property to each operation in the Swagger document, which renders in Swagger-UI as a padlock next to the operation:

Once you’ve done that, when you “Try it out” using the Swagger-UI, the authorization header with your bearer token should be sent to your API.

Advertisements

9 thoughts on “Add an authorization header to your swagger-ui with Swashbuckle (revisited)

  1. I am getting “Fetch error Internal Server Error v1/swagger.json” after adding options.OperationFilter(); Is there anything special that needs to be added anywhere else in the application? Do you perhaps have a working example project?

  2. In my case , I need to store the bearer token returned after authenication(oAuth) and then pass on the same for further requests from Swagger UI. Any Ideas on how to store and process the bearer token, I have already followed all steps mentioned on your blog post

    • I don’t understand your question, sorry.

      Where does the bearer token come from? Normally in web apis the bearer token will come from an external identity system.

      Where do you want to store the bearer token? In swagger-ui somewhere? The swagger-ui javascript can be customised via Swashbuckle, but I’m not sure if that will help you.

  3. Hello Matt,

    I end up on your post while looking for a solution to what I’m trying to sort out which I believe it’s similar but not precisely the same:
    On my back end, I haven’t implemented or used OAuth2. It’s not what I’m interested into right now but I want to make my clients send a key to the back-end as a sort of security mechanism. It’s still in development phase.
    I just need to be able to send a key-value pair on the headers with the Swagger interface, as I would do it with Postman for instance. How can I achieve this?

  4. Thanks a lot for your help. Now, it works perfectly fine :)

    Yes, I’m developing on ASP.NET Core. I have a very simple Middleware that now is able to check that a Key is being sent. In the future, I might add OAuth2 but for the current phase, this is just fine.

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out /  Change )

Google+ photo

You are commenting using your Google+ account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s