How to configure oAuth2 with password flow with Swagger ui in spring boot rest application

oAuth2

Swagger UI

Spring Boot

REST API

Authentication

How to configure oAuth2 with password flow with Swagger ui in spring boot rest application

Master System Design with Codemia

Enhance your system design skills with over 120 practice problems, detailed solutions, and hands-on exercises.

Start Practicing Learn More

Introduction

If you want Swagger UI to request tokens by OAuth2 password flow in a Spring Boot REST application, the usual job is to describe an existing token endpoint in your OpenAPI configuration. The important caveat is that the password grant is a legacy flow, so this setup is mainly for maintaining older systems rather than designing a new OAuth architecture.

Understand What Swagger UI Is Actually Doing

Swagger UI is not your authorization server. It is only a client that knows how to show an authorization dialog, send the username and password to a token endpoint, and attach the returned bearer token to protected API calls.

That means you normally need two things:

a Spring Boot API that exposes protected endpoints
an OAuth2 token endpoint that accepts the password grant

In many legacy systems, that token endpoint lives in the same platform, but it can also be external.

Declare the Password Flow in OpenAPI

With springdoc-openapi, you can describe the password flow directly in your OpenAPI bean.

java

1import io.swagger.v3.oas.models.OpenAPI;
2import io.swagger.v3.oas.models.Components;
3import io.swagger.v3.oas.models.security.SecurityRequirement;
4import io.swagger.v3.oas.models.security.SecurityScheme;
5import org.springframework.context.annotation.Bean;
6import org.springframework.context.annotation.Configuration;
7
8import java.util.Map;
9
10@Configuration
11public class OpenApiConfig {
12
13    @Bean
14    public OpenAPI api() {
15        SecurityScheme oauthScheme = new SecurityScheme()
16                .type(SecurityScheme.Type.OAUTH2)
17                .flows(new io.swagger.v3.oas.models.security.OAuthFlows()
18                        .password(new io.swagger.v3.oas.models.security.OAuthFlow()
19                                .tokenUrl("http://localhost:8080/oauth/token")
20                                .scopes(new io.swagger.v3.oas.models.security.Scopes()
21                                        .addString("read", "read access")
22                                        .addString("write", "write access"))));
23
24        return new OpenAPI()
25                .components(new Components().addSecuritySchemes("oauth2Password", oauthScheme))
26                .addSecurityItem(new SecurityRequirement().addList("oauth2Password"));
27    }
28}

The key setting is the password flow with a valid tokenUrl. Once Swagger UI sees that scheme, it can render the Authorize button with the fields needed for this flow.

Mark Protected Endpoints

You can then apply the scheme to your controllers or operations.

java

1import io.swagger.v3.oas.annotations.Operation;
2import io.swagger.v3.oas.annotations.security.SecurityRequirement;
3import org.springframework.web.bind.annotation.GetMapping;
4import org.springframework.web.bind.annotation.RestController;
5
6@RestController
7public class ProfileController {
8
9    @Operation(security = @SecurityRequirement(name = "oauth2Password"))
10    @GetMapping("/api/profile")
11    public String profile() {
12        return "secured profile";
13    }
14}

That tells the generated OpenAPI document that the endpoint expects the configured security scheme.

Configure Swagger UI Client Values

If your token endpoint expects client credentials, configure Swagger UI accordingly in application properties.

yaml

1springdoc:
2  swagger-ui:
3    oauth:
4      client-id: swagger-ui-client
5      client-secret: swagger-ui-secret

Those values are for the OAuth client that Swagger UI behaves as. They are not the resource owner username and password.

Secure the API Side Separately

Your Spring Security configuration still needs to validate bearer tokens for API requests. A simple resource server setup looks like this:

java

1import org.springframework.context.annotation.Bean;
2import org.springframework.context.annotation.Configuration;
3import org.springframework.security.config.Customizer;
4import org.springframework.security.config.annotation.web.builders.HttpSecurity;
5import org.springframework.security.web.SecurityFilterChain;
6
7@Configuration
8public class SecurityConfig {
9
10    @Bean
11    SecurityFilterChain filterChain(HttpSecurity http) throws Exception {
12        http
13            .authorizeHttpRequests(auth -> auth
14                .requestMatchers("/v3/api-docs/**", "/swagger-ui/**").permitAll()
15                .anyRequest().authenticated())
16            .oauth2ResourceServer(oauth2 -> oauth2.jwt(Customizer.withDefaults()));
17
18        return http.build();
19    }
20}

This protects the API while still leaving Swagger UI reachable.

Common Pitfalls

Swagger UI can describe and use the password flow, but it does not implement the token endpoint for you.
The password grant is a legacy OAuth2 flow, so treat this as maintenance guidance rather than a best-practice design for new systems.
Mixing up client credentials with the end user's username and password is a common configuration mistake.
Protect the API endpoints and permit only the documentation endpoints needed for Swagger UI itself.

Summary

Configure the password OAuth2 flow in your OpenAPI security scheme with a real tokenUrl.
Let Swagger UI act as an OAuth client for an existing token endpoint.
Mark secured endpoints with the configured security requirement.
Use this setup mainly for legacy password-grant systems, not as a default choice for new OAuth implementations.