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

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.

See also