How to authorize Basic Auth requests in Spring Boot Swagger UI

featured image

We’re going to apply Basic Auth on API calls made from Swagger UI. OpenAPI allows us to provide security configuration for calling our documented endpoints and offers a few security schemes. Once we have our Spring Security configured and endpoints secured, we can show a project documentation to everyone, and allow visitors to provide credentials if they want to call a protected endpoint.

Prerequisites

swagger ui without basic authentication

Add Spring Security

Right now, the endpoints are available for everyone. We’re going to secure them.

Add Maven dependencies

First, we need to include the Maven dependencies for Spring Boot Starter Security and Spring security support module for springdoc-openapi in our pom.xml file:

Next, we’re going to specify default credentials in our application.properties file:

If we were to start the application now, we would only have the default security configuration. It means that we would get the Spring Boot login page when calling any existing url:

default Spring Boot login page

Therefore, the Swagger UI page would be available only for a successfully authenticated user and all API endpoints would be protected. However, we want to show the API docs to everyone and only require authentication when someone wants to call the protected endpoints.

Allow anyone to see Swagger docs

We’re going to provide a custom configuration for the application security. We have to add the SecurityConfig.java file to our project and use the @Configuration annotation on it. What’s more, make sure that the class extends the WebSecurityConfigurerAdapter class so that we can override the configure(HttpSecurity http) method. Additionally, we’re going to add CorsFilter and exclude Swagger resources from the security:

As a result, anyone can view the documentation, but calling a secured endpoint will require providing valid credentials in a popup login form:

default authentication when calling secured endpoint with Swagger UI

Add Basic Auth to Swagger UI

Our current OpenAPI configuration (details in the Easy OpenAPI 3 specification for your Spring Boot REST API post) looks like this:

Apart from providing the usual API details (title, description, license, etc.) we’re going to configure security. As we can read in the Swagger documentation:

Security is described using the securitySchemes and security keywords. You use securitySchemes to define all security schemes your API supports, then use security to apply specific schemes to the whole API or individual operations.

Authentication and Authorization: Describing Security

To understand what we want to achieve we need to take a look on the Swagger documentation for Basic Auth:

swagger docs for basic auth

As we can see, we need to add the basic security scheme to the components and apply it to the entire API by listing it in the security. Let’s translate this to java code (and keep basicAuth as the arbitrary scheme name in our example as well):

Consequently, we can start the application and see the Authorize option on our Swagger UI page:

secured swagger ui

We have to click it and provide the correct credentials (spring:spring, as defined in my application.properties file) in order to call our secured endpoints:

basic auth in swagger ui

Finally, we can call the API! Swagger will append the Authorization header to our requests as we can see in the curl section (and in the Headers view):

Authorization header added to API call

To sum up, the work done in this article is contained in the a7543dd30d12e23e10bb4fcb9e2deffc145e8b2e commit.

Learn more on securing Swagger UI

Photo by Artem Podrez from Pexels

Leave a Reply

Your email address will not be published. Required fields are marked *