Autoryzacja żądań w Swagger

Jakiś czas temu pisałem o tym, że gdy tworzymy API, warto dodać narzędzie Swagger. Umożliwia ono w szybki i prosty sposób przetestować nasze API (tutaj). Zdarza się jednak tak, że aby móc korzystać z naszego API, dane żądanie (request) musi być zautoryzowane, czyli np. posiadać odpowiedni token.

Swagger umożliwia autoryzację żądań na wiele sposobów. W tym poście opiszę jak to zrobić, gdy potrzebujemy Bearer token.

Konfiguracja

Jeśli nie autoryzujemy naszych żądań, to rejestracja Swagger może wyglądać następująco:

services.AddSwaggerGen(c =>
{
    c.SwaggerDoc("v1", new OpenApiInfo { Title = "My API" });
});

Aby dodać autoryzację, będziemy musieli dodać dwie metody: AddSecurityDefinition i AddSecurityRequirement. Całość może wyglądać następująco:

services.AddSwaggerGen(c =>
{
    c.SwaggerDoc("v1", new OpenApiInfo { Title = "My API" });
    c.AddSecurityDefinition("AuthorizationBearer", new OpenApiSecurityScheme
    {
        Description = @"JWT Authorization header using the Bearer scheme.
          <br/> Enter your token in the text input below.
          <br/> You don't have to add prefix 'Bearer'.
          <br/> Example: 'this_is_my_token'",
        Type = SecuritySchemeType.Http,
        Scheme = "Bearer"
    });
    c.AddSecurityRequirement(new OpenApiSecurityRequirement
    {
        {
            new OpenApiSecurityScheme
            {
                Reference = new OpenApiReference
                {
                    Type = ReferenceType.SecurityScheme,
                    Id = "AuthorizationBearer"
                },
                Scheme = "oauth2",
                Name = "Bearer"
            },
            new List<string>()
        }
    });
});

W metodzie AddSecurityDefinition definiujemy jakie typy i schematy autoryzacji wspieramy. W naszym przypadku będzie to typ Http i schemat Bearer. Pełną listę wszystkich wspieranych typów oraz schematów możemy znaleźć tutaj. Jeśli istnieje taka potrzeba, możemy zdefiniować wiele SecurityDefinition, gdzie każdy będzie wspierał inny typ lub schemat. Dodanie tej sekcji powoduje pojawienie się przycisku Authorize na naszej stronie ze Swagger (więcej o tym poniżej).

Jeśli chodzi o metodę AddSecurityRequirement, odpowiada ona za połączenie danego sposobu autoryzacji z naszymi punktami końcowymi (endpoints). W tym przypadku dla wszystkich żądań będziemy dodawali nasz Bearer token (o ile zostanie wcześniej podany).

Interfejs użytkownika

Jak wcześniej wspomniałem, dodanie metody AddSecurityDefinition powoduje pojawienie się przycisku Authorize:

Gdy w niego klikniemy, pojawi nam się następujące okno:

W tym oknie widzimy zdefiniowaną przez nas nazwę AuthorizationBearer oraz opis. Jeśli mielibyśmy więcej SecurityDefinition, w tym miejscu widzielibyśmy kilka możliwości autoryzacji.

Jeśli podamy token i naciśniemy Authorize, okienko zmienia nam się na:

Od teraz do każdego żądania, jakie wykonamy przy pomocy Swagger, zostanie dodany podany przez nas token. Ponadto to okno pojawi się również wtedy, gdy ponownie naciśniemy przycisk Authorize na głównej stronie. Umożliwia nam ono wylogowanie (logout), czyli w tym przypadku usunięcie podanego przez nas token i możliwość podania nowego.

Po podaniu token, przycisk Autorize wygląda następująco:

Można zauważyć, że kłódka jest teraz zamknięta, a wcześniej była otwarta.

Podsumowanie

I to tyle. Dzięki dodaniu dwóch metod do naszej definicji Swagger możemy sprawić, że nasze żądania będą zautoryzowane i będziemy mogli testować również te punkty końcowe, które wymagają podania token.