To replace HTTP Basic authentication on a Spring servlet API, configure the API as an OAuth2 Resource Server and have clients send an access token in Authorization: Bearer <token>. Spring Security can validate JWT access tokens or introspect opaque access tokens. It does not issue tokens for you: token issuance belongs to an authorization server or another trusted issuer.
OAuth2 and JWT are not competing alternatives. OAuth2 defines roles and flows for clients, resource servers, and authorization servers; JWT is one format an access token can use. The right migration therefore changes both the API’s authentication configuration and the way its clients obtain credentials.
Understand what is changing
With HTTP Basic, a client sends a username and password as credentials for authentication. In Spring Security, BasicAuthenticationFilter processes those credentials. With bearer authentication, a client sends an access token, and BearerTokenAuthenticationFilter extracts it and passes it for authentication. A valid token establishes the request’s authentication; an invalid token causes authentication to fail and the bearer entry point to respond. An unauthenticated request can receive a WWW-Authenticate: Bearer challenge.
A Resource Server protects an API by validating incoming access tokens. It is not automatically a login service, an OAuth2 client, or an authorization server. If your application also needs to obtain tokens to call another API, use Spring Security’s OAuth2 Client support for that role. If it needs to issue tokens, arrange an authorization server or another trusted issuer separately.
Recommended Free Tools
#1 Best Overall
Choose the token validation approach
| Option | How validation works | Considerations |
|---|---|---|
| JWT access token | The resource server verifies the token locally using trusted signing keys and checks its claims. | Issuer metadata and a JWK set can support key discovery and rotation. Local verification avoids an introspection request for each validation, but revocation and claim requirements still need to be addressed in the system design. |
| Opaque access token | The resource server asks the authorization server to validate the token through introspection. | Centralized validation may suit an issuer or deployment that requires it, but validation depends on the introspection service being available. |
Spring Security supports both, through JWT decoding and opaque-token introspection. There is no universally better choice: use the issuer’s capabilities and your requirements for revocation, central control, and operational dependencies to decide. Prefer a supported issuer and its metadata or JWK source where available. If you configure trust directly for a custom JWT, you take responsibility for secure key distribution and validation.
Add Resource Server support
For a Spring Boot application, the documented starter is spring-boot-starter-oauth2-resource-server. JWT processing also requires spring-security-oauth2-jose, which provides JWT decoding and signature-verification support. Align the dependencies and configuration with the Spring Boot and Spring Security versions already used by the application; the exact APIs can vary across versions.
For JWTs, configure an issuer URI so Spring can discover issuer metadata and signing keys, or configure an appropriate trusted public-key/JWK source for your issuer. For opaque tokens, configure the introspection details required by the issuer. Do not configure the resource server to trust an arbitrary key or token merely because it can be decoded.
Configure a bearer-protected API
A typical servlet application uses a SecurityFilterChain to specify which routes are public, which require authentication, and how bearer tokens are processed. This illustrative configuration protects API routes and permits a health-check route; replace the paths and authorization rules with the application’s actual requirements.
@Bean
SecurityFilterChain securityFilterChain(HttpSecurity http) throws Exception {
http
.authorizeHttpRequests(authorize -> authorize
.requestMatchers("/health").permitAll()
.requestMatchers("/api/**").authenticated()
.anyRequest().denyAll()
)
.oauth2ResourceServer(oauth2 -> oauth2.jwt());
return http.build();
}For opaque access tokens, configure the resource server’s opaque-token support rather than the JWT configuration shown above. If the application provides its own servlet security configuration, HTTP Basic is not necessarily enabled automatically; it must be explicitly enabled. Remove that configuration for routes where Basic authentication should no longer work. Check for other authentication filters as well, since a custom filter can preserve an old login path even after the main chain changes.
Validate JWTs and map authorization deliberately
Spring Security’s documented JWT defaults validate the signature and the exp, nbf, and iss claims. They do not eliminate the need to decide what the API trusts. Confirm that the issuer is the intended authorization server and that the signing keys and accepted algorithms match the issuer’s configuration. If the deployment requires an audience check or domain-specific claim validation, add those checks with suitable token validators.
Rank #4
By default, Spring Security maps JWT scopes to authorities prefixed with SCOPE_. A token scope such as orders.read is therefore represented as SCOPE_orders.read for authorization. Make your access rules match the issuer’s scope conventions, or deliberately customize authority conversion if the application relies on roles or different claim names. Authentication only establishes who or what presented a valid token; endpoint authorization still determines which operations it may perform.
Keep browser and API security boundaries clear
Changing an API from Basic credentials to bearer tokens does not automatically remove browser sessions or make CSRF protection unnecessary. Spring Security’s CSRF filter checks submitted tokens on protected requests and, by default, stores the CSRF token in the HTTP session. Review the actual credential transport and route behavior: browser flows using cookies or sessions may have different CSRF needs from machine clients that explicitly attach bearer tokens.
Quick wins for a faster PC:
Repair Windows errors before they cause bigger problemsFix Now →Fix the driver behind crashes, sound loss and screen glitchesFind Drivers →Clear out junk files and repair common Windows errorsFree Scan →Best Value
If the application serves both a browser interface and a bearer-protected API, decide whether their authentication and CSRF requirements warrant separate SecurityFilterChains. The route boundaries and client behavior determine the design; neither “JWT” nor “stateless” alone settles the CSRF question.
Quick Recap
Migrate clients and retire Basic safely
- Inventory existing behavior. Record route authorization, Basic users and credentials, browser and machine clients, session usage, CSRF behavior, and custom authentication filters. Decide which routes should change and which, if any, must retain their existing login model.
- Choose the issuer and token type. Confirm how clients obtain tokens, whether the API receives JWTs or opaque tokens, and which issuer, keys, scopes, and claims the API must trust.
- Configure the resource server. Add the required dependencies, token validation settings, route rules, and authority mapping for the application’s Spring versions and issuer.
- Update clients. Have each client obtain an access token from the issuer and send it in the
Authorizationheader using the Bearer scheme. Do not send a reusable username and password as the API credential after that client has migrated. - Roll out and remove Basic intentionally. Coordinate the API change with client releases. Decide how to handle clients that have not migrated and how to restore service if rollout fails; compatibility and rollback choices depend on your routes and clients.
Common migration mistakes
- Expecting JWT support to create a login endpoint. Resource Server validates incoming tokens; it does not mint them. Provide an issuer separately.
- Confusing a decodable token with a trusted token. Token validation must use trusted signing keys and the intended issuer, with required audience or application-specific checks.
- Keeping authorization rules tied to the old identity model. Verify how scopes and claims map to Spring authorities before changing access rules.
- Disabling CSRF solely because the API uses JWTs. Review cookies, sessions, browser flows, and API route boundaries before changing CSRF settings.
- Assuming all Spring versions use identical configuration. Check the reference for the project’s actual Spring Security and Spring Boot versions before applying an example.
Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.
