
# 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

```yaml
# 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](../spring-boot-starter-security/index.md) instead: it depends on this package, re-exports it, and adds `oauth2Login()`.

## Example

A service calls a partner's API with its own token:

```properties
# 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
```

```dart
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](../spring-boot-starter-security/index.md) |
| 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](registrations.md): clients and providers, common providers, discovery, redirect URIs, Apple.
- [Authorized clients](authorized-clients.md): the manager, refresh, client credentials, tokens anywhere.
- [Tokens on Feign calls](feign.md): `spring.feign.oauth2.*`, the interceptor and the error decoder.
- [OpenID Connect](openid-connect.md): users, ID tokens and their checks.
- [DPoP](dpop.md): tokens bound to the client's key.
- [All properties](properties.md): every key of the starter.
- [Differences from Spring](differences.md): what works differently than in Spring Security.

## In Spring (Java)

```yaml
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](differences.md).

## See also

- [spring_boot_starter_security](../spring-boot-starter-security/index.md)
- [Single sign-on](../spring-boot-starter-security/oauth2-login.md)
- [spring_boot_starter_feign](../spring-boot-starter-feign/index.md)
- [What a build contains](optimizations.md)
