Login screens
Ready parts of a login screen: LoginForm (a user name and password on the AuthenticationManager), OAuth2LoginButton for any registration of the properties, and the buttons of Google, Apple, Microsoft and GitHub in the look their owners prescribe. They only start a login; what happens then is the AuthenticationManager's or OAuth2LoginService's.
Why
Every app writes the same form (autofill hints, an obscured password with a show control, the same error for a wrong name and a wrong password) and the same branded buttons (whose colors, logos and sizes are fixed by their owners, and checked by App Review). These parts do it once, and follow the app's design: Material, Cupertino or a plain WidgetsApp.
Example
// A login screen with a form and two providers.
Scaffold(
appBar: AppBar(title: const Text('Log in')),
body: Padding(
padding: const EdgeInsets.all(16),
child: Column(
children: [
LoginForm(onSuccess: (_) => Navigator.of(context).pop()),
const SizedBox(height: 24),
GoogleLoginButton(onSuccess: (_) => Navigator.of(context).pop()),
OAuth2LoginButton(
'keycloak',
icon: const Icon(Icons.key),
onSuccess: (_) => Navigator.of(context).pop(),
),
],
),
),
)
Their design follows the app
LoginForm and OAuth2LoginButton import neither Material nor Cupertino. They draw their fields and their button with the controls of the app's design library (DesignControls of the Flutter starter), which the design starter gives:
| App | The form and OAuth2LoginButton |
|---|---|
spring.flutter.app.type: material, with spring_boot_starter_flutter_material |
Material text fields and a FilledButton styled by the app's ThemeData (and so by spring.flutter.theme.components.input.* and button.*) |
spring.flutter.app.type: cupertino, with spring_boot_starter_flutter_cupertino |
CupertinoTextField and CupertinoButton.filled styled by the CupertinoTheme |
Without a design library (widgets) |
Plain fields and a button in the colors of the SpringTheme |
They find the controls of a design below a MaterialApp or a CupertinoApp the app builds itself too, when the application has that design's starter. design: chooses: LoginDesign.app (the controls of the app's design library, the plain widgets where there is none) or LoginDesign.widgets (always the plain widgets). Without design: the widgets find the design from above them. The brand buttons look the same everywhere: the brand decides their look.
The example above is of an app of type material: Scaffold, AppBar and Icons come from material_ui.
LoginForm
On submit (the button, or Enter in the password field) it checks that both fields are filled, trims the user name and asks the application's AuthenticationManager bean with a UsernamePasswordAuthenticationToken. Meanwhile the button shows progress and the fields are locked.
- A success puts the user into the
SecurityContextHolder, publishes anInteractiveAuthenticationSuccessEvent, tells the password manager to save the login and callsonSuccess. - A failure clears the password, shows an error and calls
onError. A wrong name or password, an unknown user and a refused account show the same text, so nobody learns which part was wrong; anything else says the login could not be checked. - The fields carry the
usernameandpasswordautofill hints; the password is obscured with a show/hide control; nothing is logged. authenticate:replaces the manager for an app whose own service logs in;authenticationManager:names another manager.- Builders customize it after the theme:
fieldBuilder(aLoginFormField),submitButtonBuilder(aLoginFormSubmitButton),errorBuilder, anderrorMessagefor the texts of failures.
The texts come from the app's message files, with these English defaults, or from usernameLabel, passwordLabel and submitLabel:
# lib/resources/messages.properties
login-form.username=User name
login-form.password=Password
login-form.submit=Log in
login-form.show-password=Show password
login-form.hide-password=Hide password
login-form.username-required=Enter your user name
login-form.password-required=Enter your password
login-form.bad-credentials=Wrong user name or password
login-form.service-error=The login could not be checked. Try again later.
OAuth2LoginButton
OAuth2LoginButton(
'keycloak',
icon: const Icon(Icons.key),
additionalParameters: const {'prompt': 'login'},
onSuccess: (_) => Navigator.of(context).pop(),
onError: (error) => setState(() => _error = '$error'),
)
It calls OAuth2LoginService.login(registrationId), shows progress while the login runs, and calls onSuccess with the user (null in a browser, where the page leaves for the login). The user closing the login window is no error: the button is ready again. Any other failure goes to onError, or to FlutterError.reportError without one. Its text is "Sign in with client name" (message login-button.oauth2, Sign in with {0}): the registration's client-name, else a known provider's name, else the registration id. label: replaces the text, login: the call, builder: the look.
The providers' buttons
| Button | Registration id (default) | What the app chooses |
|---|---|---|
GoogleLoginButton |
google |
theme (light, dark, neutral), shape (rectangular, pill), text (sign in, sign up, continue), iconOnly |
AppleLoginButton |
apple |
style (black, white, white with outline), text, iconOnly with circular, height (30 and up, 44 by default), cornerRadius; the logo from the app's assets |
MicrosoftLoginButton |
microsoft |
theme (light, dark), text ("Sign in with Microsoft", "Sign in") |
GitHubLoginButton |
github |
theme (dark, light), shape, text, iconOnly |
Each is an OAuth2LoginButton underneath: the same onSuccess, onError, additionalParameters, loginService and login, and a registrationId that may be any id of the properties. Colors, logos, fonts, sizes and texts are not parameters: they are their owners' marks, and the owners publish what may change (Google's branding guidelines, Apple's Human Interface Guidelines checked by App Review, Microsoft's and GitHub's logo rules). A design the rules do not cover belongs to OAuth2LoginButton(builder: ...), without the brand's logo.
Apple's logo comes from the app. Apple's Developer Artwork License lets members use the logo in their own apps only, never redistribute it, so a library cannot ship it. Download "Sign in with Apple Logo" from Apple Design Resources, add the files to the app's assets and pass them as logo:
AppleLoginButton(
logo: (context, artwork) => Image.asset(
'assets/apple/${artwork.logoOnly ? 'logo-only' : 'left-aligned'}-'
'${artwork.color.name}.png',
height: artwork.height,
),
onSuccess: (_) => Navigator.of(context).pop(),
)
On iOS and macOS, login('apple') opens Apple's native sheet: the button just calls the login service, which chooses.
Fonts. Google Sans and Segoe UI belong to Google and Microsoft and are not shipped: add them as fonts of your own if you may use them; otherwise the buttons fall back to Roboto, the app's font or the system font.
The texts may be translated in the app's messages (keep the meaning, never "Google" alone):
login-button.google.sign-in=Sign in with Google
login-button.google.sign-up=Sign up with Google
login-button.google.continue=Continue with Google
login-button.apple.sign-in=Sign in with Apple
login-button.apple.sign-up=Sign up with Apple
login-button.apple.continue=Continue with Apple
login-button.microsoft.sign-in-with=Sign in with Microsoft
login-button.microsoft.sign-in=Sign in
login-button.github.sign-in=Sign in with GitHub
login-button.github.sign-up=Sign up with GitHub
login-button.github.continue=Continue with GitHub
In Spring (Java)
The nearest is Spring Security's default login page (formLogin() and oauth2Login()), a server page with a form and one link per registration, labelled with its client name.