
# 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

```dart
// 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 an `InteractiveAuthenticationSuccessEvent`, tells the password manager to save the login and calls `onSuccess`.
- 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 `username` and `password` autofill 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` (a `LoginFormField`), `submitButtonBuilder` (a `LoginFormSubmitButton`), `errorBuilder`, and `errorMessage` for the texts of failures.

The texts come from the app's message files, with these English defaults, or from `usernameLabel`, `passwordLabel` and `submitLabel`:

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

```dart
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`:

```dart
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):

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

## See also

- [Widgets that follow the user](principal-widgets.md)
- [Providers: Google and Apple](providers.md)
- [Themes](../spring-boot-starter-flutter/themes/index.md)
- [Design libraries](../spring-boot-starter-flutter/design-libraries.md)
