spring_boot_starter_oauth2_client
spring_boot_starter_oauth2_client is the OAuth 2.0 and OpenID Connect client of Spring for Dart: Spring Security's OAuth2 client with Spring Boot's auto-configuration. A service calls another service with its own (client credentials) token; a server logs its users in with Keycloak, Google, Auth0 or Okta through the security starter's oauth2Login(); a Flutter app logs its user in through spring_boot_starter_flutter_security. All of them use the registrations, token endpoint clients and authorized clients of this starter.
Why
Calling an API with an access token is more protocol than it looks: the provider's endpoints (discovered from its issuer), the token endpoint with the right client authentication, the refresh before the token expires (once, even when ten calls ask at the same time), the token renewed after the API rejects it, and for logins PKCE, state, nonce and the checks of the ID token. This starter does all of it from Spring Boot's spring.security.oauth2.client.* properties, and the application's Feign clients just work. It is pure Dart and runs wherever spring_boot_dart runs: the VM, Flutter, the web.
Setup
# pubspec.yaml
dependencies:
spring_boot_starter_oauth2_client: ^0.9.0
spring_boot_starter_feign: ^0.9.0 # only for Feign clients that carry the token
dev_dependencies:
build_runner: ^2.17.0
spring_core_dart_generator: ^0.9.0
One import: package:spring_boot_starter_oauth2_client/spring_boot_starter_oauth2_client.dart re-exports spring_security_core and spring_web_dart (and through them spring_boot_dart and logging). It does not re-export the Feign starter: import that where you declare the clients.
A server that logs users in lists spring_boot_starter_security instead: it depends on this package, re-exports it, and adds oauth2Login().
Example
A service calls a partner's API with its own token:
# lib/resources/application.properties
spring.security.oauth2.client.registration.partner.client-id=shop
spring.security.oauth2.client.registration.partner.client-secret=${PARTNER_SECRET}
spring.security.oauth2.client.registration.partner.authorization-grant-type=client_credentials
spring.security.oauth2.client.registration.partner.scope=orders.read
spring.security.oauth2.client.provider.partner.token-uri=https://id.partner.example/oauth2/token
# Every Feign call carries the token.
spring.feign.oauth2.enabled=true
spring.feign.oauth2.client-registration-id=partner
import 'package:spring_boot_starter_feign/spring_boot_starter_feign.dart';
import 'package:spring_boot_starter_oauth2_client/spring_boot_starter_oauth2_client.dart';
@FeignClient('orders', url: r'${partner.url}')
abstract interface class OrdersClient {
@GetMapping('/orders')
Future<List<Order>> orders(); // Authorization: Bearer <token>, refreshed before it expires
}
Which flow where
| Client | Flow | Package |
|---|---|---|
| Server to server | client credentials, OAuth2AuthorizedClientManager |
this one |
| Server pages, Flutter web | oauth2Login(): the server is a confidential client, the tokens stay in its session; the browser has only the HttpOnly session cookie |
spring_boot_starter_security |
| Flutter iOS, Android, macOS, Windows, Linux | the app login: authorization code with PKCE, a public client (RFC 8252), the system's login window, the tokens in secure storage | spring_boot_starter_flutter_security |
What starts
Each bean backs off when the application declares one of its type:
| Bean type | Default |
|---|---|
ClientRegistrationRepository |
An in-memory repository of the registration.* properties. |
OAuth2AuthorizedClientService |
InMemoryOAuth2AuthorizedClientService: tokens forgotten when the program stops. |
OAuth2AuthorizedClientManager |
AuthorizedClientServiceOAuth2AuthorizedClientManager with authorization code, refresh token and client credentials. |
OAuth2AccessTokenResponseClient<...> (three) |
DefaultAuthorizationCodeTokenResponseClient, DefaultRefreshTokenTokenResponseClient, DefaultClientCredentialsTokenResponseClient, on the HttpTransport. |
OidcIdTokenDecoder |
TokenEndpointOidcIdTokenDecoder (the security starter replaces it with a signature-checking one). |
OAuth2UserService<...> (two) |
DefaultOAuth2UserService, OidcUserService. |
OAuth2AccessTokenInterceptor, ErrorDecoder |
With spring.feign.oauth2.enabled=true. |
DPoPKey |
A SoftwareDPoPKey made in memory for each run. |
clientSecretResolver |
A JwtClientSecretResolver for client-secret-jwt.*. |
Another auto-configuration replaces them the same way when its module is registered first (@AutoConfigurationModule(before: ['springBootStarterOauth2ClientAutoConfiguration'])), with its beans guarded by @ConditionalOnMissingBean. The security starter does so for the OidcIdTokenDecoder, the Flutter security package for the OAuth2AuthorizedClientService and the DPoPKey.
Nothing in the starter logs a token, a code, a verifier, a key or a secret.
What is inside
- Registrations: clients and providers, common providers, discovery, redirect URIs, Apple.
- Authorized clients: the manager, refresh, client credentials, tokens anywhere.
- Tokens on Feign calls:
spring.feign.oauth2.*, the interceptor and the error decoder. - OpenID Connect: users, ID tokens and their checks.
- DPoP: tokens bound to the client's key.
- All properties: every key of the starter.
- Differences from Spring: what works differently than in Spring Security.
In Spring (Java)
spring:
security:
oauth2:
client:
registration:
partner:
client-id: shop
authorization-grant-type: client_credentials
The properties are Spring Boot's. In Spring, spring-boot-starter-oauth2-client brings web security and oauth2Login() too; here this package is the client only, because it must also run in Flutter apps and browsers. Discovery happens at the first use, not at startup. The full list is on Differences from Spring.