spring_boot_starter_flutter_security
spring_boot_starter_flutter_security logs the user of a Flutter app in, with OAuth 2.0 and OpenID Connect (Keycloak, Google, Apple, Okta, Auth0, ...), and keeps secrets on the device. It brings the platform code an app needs for that: the secure storage of each platform (the Keychain, the Android Keystore, DPAPI, the Secret Service), the system's login window, and a key for DPoP. On top come a template for the app's own secrets, widgets that follow the logged-in user, ready login screens, and guards for the screens of the navigation starter.
Why
An app that logs its user in needs a safe place for tokens, the system's login window (so the app never sees the password and single sign-on works), PKCE, checks of every answer, refresh at startup and a logout that revokes. In a browser it needs something else entirely: no token should reach the page. Written by hand, that is weeks of platform code and security reviews. Here it is one service with three calls, login, restore and logout, the same on a phone, a desktop and in a browser, on the registrations of Spring's OAuth2 client.
It lives in its own package, not in the Flutter starter: the platform code (Swift, Kotlin, two Android activities) is carried only by apps that log in. As in Spring Boot, an app adds security when it needs it.
Setup
# pubspec.yaml
dependencies:
flutter:
sdk: flutter
spring_boot_starter_flutter_security: ^0.9.0
dev_dependencies:
build_runner: ^2.17.0
spring_core_dart_generator: ^0.9.0
One package, one import. It depends on and re-exports spring_boot_starter_flutter, spring_boot_starter_flutter_navigation, the OAuth2 client (spring_boot_starter_oauth2_client: the registrations and authorized clients) and spring_security_core (SecurityContextHolder, @PreAuthorize). List this package instead of the Flutter starter:
import 'package:spring_boot_starter_flutter_security/spring_boot_starter_flutter_security.dart';
An app with Feign clients lists and imports spring_boot_starter_feign itself.
The starter needs Flutter 3.50 or later (Dart 3.14). Its Android part builds with the Android Gradle Plugin 9.3.1, the version of Flutter 3.50's template, and its Kotlin is compiled by the plugin's built-in Kotlin support. An app on Flutter 3.50 needs AGP 9.1.1 or later anyway (Flutter refuses less), and Flutter recommends Gradle 9.5.0.
The login screens import no design library: in an app of type material or cupertino they take the look of its design starter (see Login screens).
Example
// The account of the app: who is logged in, and the three calls.
@Service()
class Account {
Account(this._login);
final OAuth2LoginService _login;
Future<void> start() => _login.restore(); // logged in from last time?
Future<void> signIn() => _login.login('keycloak'); // the system's login window
Future<void> signOut() => _login.logout(); // revoke, forget
}
// Builds again on every login and logout.
class Header extends StatelessWidget {
const Header({super.key});
@override
Widget build(BuildContext context) =>
Text('Hello, ${context.principal?.name ?? 'guest'}');
}
# lib/resources/application.yml
spring:
security:
oauth2:
client:
registration:
keycloak:
client-id: neon-app # a public client: no secret
scope: openid,profile,email
redirect-uri: dev.neon.books:/oauth2/callback
provider:
keycloak:
issuer-uri: https://id.neon.books/realms/neon
# lib/resources/application-web.yml: in a browser the app's server logs in
spring:
flutter:
security:
web:
server-url: https://api.neon.books
user-endpoint: /api/me
Running it
- On iOS and macOS,
login('keycloak')opens the provider's page in a Safari sheet; on Android in a Chrome Custom Tab (declare the redirect activity, see Tokens and the login window); on Windows and Linux in the default browser, with the redirect caught on127.0.0.1. - The tokens go to the platform's secure storage; at the next start
restore()brings the user back and refreshes the tokens. - In a browser,
loginsends the page to the server's login (oauth2Login()of spring_boot_starter_security); the page keeps only anHttpOnlysession cookie.
What is inside
- The app login:
OAuth2LoginServiceon phones and desktops:login,restore,logout, the checks, the beans. - The web: the server logs in: the backend-for-frontend login, the user endpoint, cookies and CSRF.
- The web without a server: spa mode: the browser logs in, tokens in the tab's memory, silent login, the Content Security Policy.
- Tokens and the login window:
SecretStore,AuthorizationWindow, the setup of each platform,httpsredirects. - Providers: Google and Apple: what each provider needs, Sign in with Apple's sheet.
- DPoP: tokens bound to a key in the Secure Enclave or the Keystore.
- SecretTemplate: the app's own secrets as objects.
- Widgets that follow the user:
context.principal,PrincipalBuilder,PrincipalView. - Login screens:
LoginForm,OAuth2LoginButtonand the Google, Apple, Microsoft and GitHub buttons. - Guarded screens:
@PreAuthorizeon the screens of the navigation. - Testing: code that runs as a user, fakes of the login.
- All properties: every key the starter reads, and the OAuth2 client's.
- Differences from Spring
In Spring (Java)
Spring Security logs browsers in on a server (oauth2Login(), a confidential client with the tokens in the session). Java has no apps, so the app's side has no counterpart; the checks are those of Spring's OAuth2LoginAuthenticationFilter, OidcAuthorizationCodeAuthenticationProvider and OidcUserService, and the server mode in a browser is oauth2Login() itself.