Expand Authors Top

If you have a few years of experience in the Java ecosystem and you’d like to share that with the community, have a look at our Contribution Guidelines.

November Discount Launch 2022 – Top
We’re finally running a Black Friday launch. All Courses are 30% off until next Friday:

>> GET ACCESS NOW

Expanded Audience – Frontegg – Security (partner)
announcement - icon User management is very complex, when implemented properly. No surprise here.

Not having to roll all of that out manually, but instead integrating a mature, fully-fledged solution - yeah, that makes a lot of sense.
That's basically what Frontegg is - User Management for your application. It's focused on making your app scalable, secure and enjoyable for your users.
From signup to authentication, it supports simple scenarios all the way to complex and custom application logic.

Have a look:

>> Elegant User Management, Tailor-made for B2B SaaS

NPI – Lightrun – Spring (partner)

We rely on other people’s code in our own work. Every day. It might be the language you’re writing in, the framework you’re building on, or some esoteric piece of software that does one thing so well you never found the need to implement it yourself.

The problem is, of course, when things fall apart in production - debugging the implementation of a 3rd party library you have no intimate knowledge of is, to say the least, tricky. It’s difficult to understand what talks to what and, specifically, which part of the underlying library is at fault.

Lightrun is a new kind of debugger.

It's one geared specifically towards real-life production environments. Using Lightrun, you can drill down into running applications, including 3rd party dependencies, with real-time logs, snapshots, and metrics. No hotfixes, redeployments, or restarts required.

Learn more in this quick, 5-minute Lightrun tutorial:

>> The Essential List of Spring Boot Annotations and Their Use Cases

1. Overview

In this tutorial, we'll learn how to configure a default global security scheme and apply it as the default security requirement of the API using the springdoc-openapi library in a Spring MVC web application. Further, we'll discuss how we can override these default security requirements.

The OpenAPI specification lets us define a set of security schemes for the API. We can configure the security requirements of the API globally or apply/remove them per endpoint.

2. Setup

As we are building a Maven project using Spring Boot, let's explore the setup of the project. At the end of this section, we'll have a simple web app.

2.1. Dependencies

The example has two dependencies. The first dependency is the spring-boot-starter-web. This is the main dependency to build the web app:

<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-web</artifactId>
    <version>2.7.1</version>
</dependency>

The other dependency is the springdoc-openapi-ui, which is the library that will render the documentation of the API in HTML, JSON, or YAML:

<dependency>
    <groupId>org.springdoc</groupId>
    <artifactId>springdoc-openapi-ui</artifactId>
    <version>1.6.9</version>
</dependency>

2.2. Application Entry Point

Once the dependencies are ready, let's define the entry point for the application.

We'll use the @SpringBootApplication annotation to bootstrap the app and the SpringApplication helper class to launch it:

@SpringBootApplication
public class DefaultGlobalSecuritySchemeApplication {
    public static void main(String[] args) {
        SpringApplication.run(DefaultGlobalSecuritySchemeApplication.class, args);
    }
}

3. springdoc-openapi Base Configuration

Once we have the Spring MVC configured, let's look at the API semantic information.

We'll define the default global security scheme and the API metadata by adding springdoc-openapi annotations to the DefaultGlobalSecuritySchemeApplication class. To define the global security scheme, we'll use the @SecurityScheme annotation:

@SecurityScheme(type = SecuritySchemeType.APIKEY, name = "api_key", in = SecuritySchemeIn.HEADER)

We've chosen an APIKEY security scheme type, but we could configure other security schemes, for instance, JWT. After defining the security scheme, we'll add the metadata and establish the default security requirement for the API. We do this using the @OpenApiDefinition annotation:

@OpenAPIDefinition(info = @Info(title = "Apply Default Global SecurityScheme in springdoc-openapi", version = "1.0.0"), security = { @SecurityRequirement(name = "api_key") })

Here, the info attribute defines the API metadata. Furthermore, the security attribute determines the default global security requirements.

Let's see what the HTML documentation will look like with the annotations. We'll see the metadata and a security button that will apply to the whole API:

Default global security requirement

4. Controllers

Now that we have configured the Spring framework and the springdoc-openapi library, let's add one REST controller to the context base path. To achieve this, we'll use the @RestController and @RequestMapping annotations:

@RestController
@RequestMapping("/")
public class DefaultGlobalSecuritySchemeOpenApiController {
    ...
}

After that, we'll define two endpoints or paths.

The first endpoint will be the /login endpoint. It'll receive the user credentials and authenticate the user. If the authentication succeeds, the endpoint will return a token.

The other endpoint of the API is the /ping endpoint and requires the token generated by the /login method. Before performing the request, the method validates the token and checks if the user is authorized.

In summary, the /login endpoint authenticates the user and provides a token. The /ping endpoint receives the token returned by the /login endpoint and checks that it's valid and that the user can perform the operation.

4.1. login() Method

This method won't have any security requirements. Therefore, we need to override the default security requirement configuration.

First of all, we need to tell Spring that this is an endpoint of our API, so we'll add the annotation @RequestMapping to configure the endpoint:

@RequestMapping(method = RequestMethod.POST, value = "/login", produces = { "application/json" }, consumes = { "application/json" })

After that, we need to add semantic information to the endpoint. So we'll use the @Operation and @SecurityRequirements annotations. The @Operation will define the endpoint and the @SecurityRequirements will define the specific set of security requirements that applies to the endpoint:

@Operation(operationId = "login", responses = {
    @ApiResponse(responseCode = "200", description = "api_key to be used in the secured-ping endpoint", content = { @Content(mediaType = "application/json", schema = @Schema(implementation = TokenDto.class)) }),
    @ApiResponse(responseCode = "401", description = "Unauthorized request", content = { @Content(mediaType = "application/json", schema = @Schema(implementation = ApplicationExceptionDto.class)) }) })
@SecurityRequirements()

For instance, here's the HTML documentation for the response with status code 200:

login r

Finally, let's see the login() method's signature:

public ResponseEntity login(@Parameter(name = "LoginDto", description = "Login") @Valid @RequestBody(required = true) LoginDto loginDto) {
    ...
}

As we can see, the body of the API request receives a LoginDto instance. We also must decorate the DTOs with semantic information to display the information in the documentation:

public class LoginDto {
    private String user;
    private String pass;

    ...

    @Schema(name = "user", required = true)
    public String getUser() {
        return user;
    }

    @Schema(name = "pass", required = true)
    public String getPass() {
        return pass;
    }
}

Here we can see what the /login endpoint HTML documentation will look like:

login execute

4.2. ping() Method

At this point, we'll define the ping() method. The ping() method will use the default global security scheme:

@Operation(operationId = "ping", responses = {
    @ApiResponse(responseCode = "200", description = "Ping that needs an api_key attribute in the header", content = {
        @Content(mediaType = "application/json", schema = @Schema(implementation = PingResponseDto.class), examples = { @ExampleObject(value = "{ pong: '2022-06-17T18:30:33.465+02:00' }") }) }),
    @ApiResponse(responseCode = "401", description = "Unauthorized request", content = { @Content(mediaType = "application/json", schema = @Schema(implementation = ApplicationExceptionDto.class)) }),
    @ApiResponse(responseCode = "403", description = "Forbidden request", content = { @Content(mediaType = "application/json", schema = @Schema(implementation = ApplicationExceptionDto.class)) }) })
@RequestMapping(method = RequestMethod.GET, value = "/ping", produces = { "application/json" })
public ResponseEntity ping(@RequestHeader(name = "api_key", required = false) String api_key) {
    ...
}

The main difference between the login() and ping() methods is in the security requirement that will be applied. The login() won't have any security requirement at all, but the ping() method will have the security defined at the API level. So, the HTML documentation will represent the situation showing a lock only for the /ping endpoint:

Ping endpoint

5. REST API Documentation URLs

At this point, we have the Spring MVC web app ready, and we can start the server:

mvn spring-boot:run -Dstart-class="com.baeldung.defaultglobalsecurityscheme.DefaultGlobalSecuritySchemeApplication"

Once the server is ready, we can see the HTML documentation, as shown in the previous examples, at the http://localhost:8080/swagger-ui-custom.html URL.

The JSON version of the API definition is found at http://localhost:8080/api-docs and the YAML version at http://localhost:8080/api-docs.yaml.

These outputs can be used to build clients or servers of the API in different languages using the swagger-codegen-maven-plugin.

6. Conclusion

In this article, we've learned how to use the springdoc-openapi library to define a default global security scheme. Also, we saw how to apply it as the default security requirement to the API. Furthermore, we've learned how to change the default security requirement for a particular endpoint.

Another thing we've discovered is that we can automate code generation using the JSON and YAML outputs from the springdoc-openapi.

As usual, the complete source code for this article is available over on GitHub.

November Discount Launch 2022 – Bottom
We’re finally running a Black Friday launch. All Courses are 30% off until next Friday:

>> GET ACCESS NOW

Generic footer banner
Comments are closed on this article!