diff --git a/docs/06-concepts/04-authentication/05-providers/03-google/02-customizations.md b/docs/06-concepts/04-authentication/05-providers/03-google/02-customizations.md
index b5911ff8..a14ac080 100644
--- a/docs/06-concepts/04-authentication/05-providers/03-google/02-customizations.md
+++ b/docs/06-concepts/04-authentication/05-providers/03-google/02-customizations.md
@@ -203,7 +203,7 @@ flutter run \
This approach is useful when you need to:
-- Manage separate client IDs for different platforms (Android, iOS, Web) in a centralized way
+- Manage separate client IDs for different platforms (Android, iOS, web) in a centralized way
- Avoid committing client IDs to version control
- Configure different credentials for different build environments (development, staging, production)
diff --git a/docs/06-concepts/04-authentication/05-providers/03-google/03-troubleshooting.md b/docs/06-concepts/04-authentication/05-providers/03-google/03-troubleshooting.md
index 16e76cba..817aa773 100644
--- a/docs/06-concepts/04-authentication/05-providers/03-google/03-troubleshooting.md
+++ b/docs/06-concepts/04-authentication/05-providers/03-google/03-troubleshooting.md
@@ -33,7 +33,7 @@ Go through this before investigating a specific error. Most problems come from a
- [ ] Surface Google sign-in in the UI with `SignInWidget` or `GoogleSignInWidget` (see [Present the authentication UI](./setup#present-the-authentication-ui)).
- [ ] Create an **iOS** OAuth client in the **same** Google Cloud project as the Web client, using the same **Bundle ID** as the app. Set `GIDClientID` from the iOS client, `GIDServerClientID` to the **Web** client's ID, and add the reversed-client-ID **URL scheme** in `Info.plist` (*iOS only*).
- [ ] Create an **Android** OAuth client in the **same** project, with the same **package name** and **SHA-1** as the build you run (*Android only*).
-- [ ] Set up the web callback (*Web only*). Pick one:
+- [ ] Set up the web callback (*web only*). Pick one:
- **Standard:** Register `FlutterWebAuth2CallbackRoute` on `pod.webServer` in `server.dart` before `pod.start()` per [Web setup](./setup#web).
- **Separately-hosted fallback:** Create `web/auth.html` in your Flutter project as described in [Web callback page (`auth.html`)](../../setup#web-callback-page-authhtml) and run Flutter on a **fixed** `--web-port` so the origin does not change every run. See [separately-hosted Flutter web](./customizations#separately-hosted-flutter-web).
diff --git a/docs/06-concepts/04-authentication/05-providers/04-apple/01-setup.md b/docs/06-concepts/04-authentication/05-providers/04-apple/01-setup.md
index fed52f10..067a136b 100644
--- a/docs/06-concepts/04-authentication/05-providers/04-apple/01-setup.md
+++ b/docs/06-concepts/04-authentication/05-providers/04-apple/01-setup.md
@@ -1,6 +1,6 @@
---
sidebar_label: Setup
-description: Sign in with Apple requires Apple credentials and platform setup. Register them and add the provider to your Serverpod app across iOS, macOS, Android, and Web.
+description: Sign in with Apple requires Apple credentials and platform setup. Register them and add the provider to your Serverpod app across iOS, macOS, Android, and web.
---
# Set up Apple sign-in
@@ -237,7 +237,7 @@ This intent filter is required. Without it, the OAuth callback never returns to
### Web
-Sign in with Apple on Web requires the Apple JS SDK. Add the following script to your Flutter app's `web/index.html` inside the `` tag:
+Sign in with Apple on web requires the Apple JS SDK. Add the following script to your Flutter app's `web/index.html` inside the `` tag:
```html
@@ -301,7 +301,7 @@ This renders a Sign in with Apple button like this:
The widget automatically handles:
-- Sign in with Apple flow for iOS, macOS, Android, and Web.
+- Sign in with Apple flow for iOS, macOS, Android, and web.
- Token management.
- Underlying `sign_in_with_apple` package error handling.
diff --git a/docs/06-concepts/04-authentication/05-providers/04-apple/02-customizations.md b/docs/06-concepts/04-authentication/05-providers/04-apple/02-customizations.md
index 55693ac3..45571d61 100644
--- a/docs/06-concepts/04-authentication/05-providers/04-apple/02-customizations.md
+++ b/docs/06-concepts/04-authentication/05-providers/04-apple/02-customizations.md
@@ -103,7 +103,7 @@ When a user revokes access from their Apple ID settings, Apple sends a notificat
| `teamId` | `String` | Yes | `appleTeamId` | The 10-character Team ID from your Apple Developer account. Used to sign the client secret JWT. |
| `keyId` | `String` | Yes | `appleKeyId` | The Key ID of the Sign in with Apple private key. |
| `key` | `String` | Yes | `appleKey` | The raw contents of the `.p8` private key file, including the `-----BEGIN PRIVATE KEY-----` header and footer. Do not pre-generate the JWT yourself. |
-| `webRedirectUri` | `String?` | Web only | `appleWebRedirectUri` | The web app URL the browser is redirected to after the server receives Apple's callback. |
+| `webRedirectUri` | `String?` | web only | `appleWebRedirectUri` | The web app URL the browser is redirected to after the server receives Apple's callback. |
| `androidPackageIdentifier` | `String?` | Android only | `appleAndroidPackageIdentifier` | The Android package name (e.g. `com.example.app`). When set, the callback route redirects Android sign-ins back to the app via an intent URI. |
## App configuration
@@ -144,7 +144,7 @@ flutter run \
This approach is useful when you need to:
-- Manage configuration separately for different platforms (Android, Web) in a centralized way
+- Manage configuration separately for different platforms (Android, web) in a centralized way
- Avoid committing sensitive configuration to version control
- Configure different credentials for different build environments (development, staging, production)
diff --git a/docs/06-concepts/04-authentication/05-providers/04-apple/03-troubleshooting.md b/docs/06-concepts/04-authentication/05-providers/04-apple/03-troubleshooting.md
index d3ceb2b7..010a679d 100644
--- a/docs/06-concepts/04-authentication/05-providers/04-apple/03-troubleshooting.md
+++ b/docs/06-concepts/04-authentication/05-providers/04-apple/03-troubleshooting.md
@@ -35,7 +35,7 @@ Go through this before investigating a specific error. Most problems come from a
* [ ] Add `serverpod_auth_idp_flutter` to your Flutter app's `pubspec.yaml`.
* [ ] Add `client.auth.initializeAppleSignIn()` after `client.auth.initialize()` in your Flutter app's `main.dart`.
* [ ] Add **Sign in with Apple** under Signing & Capabilities in Xcode (*iOS/macOS only*).
-* [ ] Add the **Apple JS SDK** script to `web/index.html` (*Web only*).
+* [ ] Add the **Apple JS SDK** script to `web/index.html` (*web only*).
* [ ] Pass **`APPLE_SERVICE_IDENTIFIER`** and **`APPLE_REDIRECT_URI`** via `--dart-define`. Initialization throws an `ArgumentError` without them, on every platform.
* [ ] Add the **`signinwithapple`** intent filter to `AndroidManifest.xml` (*Android only*).
* [ ] Add **Apple's mail servers** to your SPF record if you email users who might use Hide My Email.
@@ -81,7 +81,7 @@ Alternatively, set `appleKey` via the `SERVERPOD_PASSWORD_appleKey` environment
## Wrong identifier passed for web or Android sign-in
-**Problem:** Sign-in on Android or Web fails immediately, or Apple returns `invalid_client` / `invalid_request` even though credentials look correct.
+**Problem:** Sign-in on Android or web fails immediately, or Apple returns `invalid_client` / `invalid_request` even though credentials look correct.
**Cause:** There are two separate identifiers in Apple's system and they are easy to mix up:
@@ -173,7 +173,7 @@ If you use `--dart-define`, confirm `APPLE_SERVICE_IDENTIFIER` is the Services I
## Web sign-in fails with `TypeError: type ... is not a subtype of type 'JSObject'`
-**Problem:** Clicking the Apple button on Web throws a `TypeError` mentioning `JSObject` or a minified type like `minified:CM`.
+**Problem:** Clicking the Apple button on web throws a `TypeError` mentioning `JSObject` or a minified type like `minified:CM`.
**Cause:** The Apple JS SDK is not loaded. The `sign_in_with_apple` package calls `AppleID.auth.init()` on the page, but that function only exists after Apple's script is loaded in the HTML.
diff --git a/docs/06-concepts/04-authentication/05-providers/06-firebase/01-setup.md b/docs/06-concepts/04-authentication/05-providers/06-firebase/01-setup.md
index e0308a93..10d6a8d6 100644
--- a/docs/06-concepts/04-authentication/05-providers/06-firebase/01-setup.md
+++ b/docs/06-concepts/04-authentication/05-providers/06-firebase/01-setup.md
@@ -127,7 +127,7 @@ pod.initializeAuthServices(
);
```
-The `FirebaseIdpConfigFromPasswords()` constructor automatically loads the service account key from the `firebaseServiceAccountKey` key in `config/passwords.yaml` (or the `SERVERPOD_PASSWORD_firebaseServiceAccountKey` environment variable). For loading credentials from other sources (file, JSON map, project ID only), see the [Customizations](./customizations) page.
+The `FirebaseIdpConfigFromPasswords()` constructor automatically loads the service account key from the `firebaseServiceAccountKey` key in `config/passwords.yaml` (or the `SERVERPOD_PASSWORD_firebaseServiceAccountKey` environment variable). For loading credentials from other sources (file, JSON map, project ID only), see the [Configuration](./configuration) page.
### 2. Create the endpoint
diff --git a/docs/06-concepts/04-authentication/05-providers/06-firebase/02-customizations.md b/docs/06-concepts/04-authentication/05-providers/06-firebase/02-configuration.md
similarity index 99%
rename from docs/06-concepts/04-authentication/05-providers/06-firebase/02-customizations.md
rename to docs/06-concepts/04-authentication/05-providers/06-firebase/02-configuration.md
index 415bf877..340af20e 100644
--- a/docs/06-concepts/04-authentication/05-providers/06-firebase/02-customizations.md
+++ b/docs/06-concepts/04-authentication/05-providers/06-firebase/02-configuration.md
@@ -1,9 +1,9 @@
---
-sidebar_label: Customizations
+sidebar_label: Configuration
description: Firebase identity provider credentials can be loaded from different sources with FirebaseIdpConfig. Configure the provider beyond the basic setup.
---
-# Customize Firebase authentication
+# Configure Firebase authentication
This page covers additional configuration options for the Firebase identity provider beyond the basic setup.
diff --git a/docs/06-concepts/04-authentication/05-providers/06-firebase/05-troubleshooting.md b/docs/06-concepts/04-authentication/05-providers/06-firebase/05-troubleshooting.md
index 77066490..e8a63f1e 100644
--- a/docs/06-concepts/04-authentication/05-providers/06-firebase/05-troubleshooting.md
+++ b/docs/06-concepts/04-authentication/05-providers/06-firebase/05-troubleshooting.md
@@ -14,7 +14,7 @@ Go through this before investigating a specific error. Most problems come from a
#### Firebase Console
- [ ] Create a **Firebase project** in the [Firebase Console](https://console.firebase.google.com/).
-- [ ] Add an app for **every platform you support** (iOS, Android, Web) inside the Firebase project. Each platform needs its own registration.
+- [ ] Add an app for **every platform you support** (iOS, Android, web) inside the Firebase project. Each platform needs its own registration.
- [ ] Generate a **service account key** from **Project settings** > **Service accounts**.
- [ ] Enable the **authentication methods** you want to use under **Security** > **Authentication** > **Sign-in method**.
- [ ] Confirm **Firebase App Check** is **disabled** (enable it later only after the client integration is in place).
diff --git a/docs/06-concepts/04-authentication/05-providers/07-github/03-troubleshooting.md b/docs/06-concepts/04-authentication/05-providers/07-github/03-troubleshooting.md
index d57c053e..f64cd0be 100644
--- a/docs/06-concepts/04-authentication/05-providers/07-github/03-troubleshooting.md
+++ b/docs/06-concepts/04-authentication/05-providers/07-github/03-troubleshooting.md
@@ -33,7 +33,7 @@ Go through this before investigating a specific error. Most problems come from a
- [ ] Both `clientId` and `redirectUri` match values registered on the GitHub App.
- [ ] On **Android**, added the `flutter_web_auth_2` `CallbackActivity` to `AndroidManifest.xml` with the **exact** scheme used in your callback URL.
- [ ] On **Web (Serverpod-hosted Flutter)**, registered `FlutterWebAuth2CallbackRoute` via `pod.webServer.addRoute(...)` in `server.dart` before `pod.start()`. On **Web (separately-hosted Flutter)**, created `web/auth.html` in your Flutter project. See [Web](./setup#web) for both flows.
-- [ ] On **Web**, ran Flutter on a fixed `--web-port` matching the port registered in the GitHub App's callback URL.
+- [ ] On **web**, ran Flutter on a fixed `--web-port` matching the port registered in the GitHub App's callback URL.
## Sign-in fails with redirect_uri_mismatch
diff --git a/docs/06-concepts/04-authentication/05-providers/08-microsoft/02-customizations.md b/docs/06-concepts/04-authentication/05-providers/08-microsoft/02-customizations.md
index 8a9e39e4..f8f81b61 100644
--- a/docs/06-concepts/04-authentication/05-providers/08-microsoft/02-customizations.md
+++ b/docs/06-concepts/04-authentication/05-providers/08-microsoft/02-customizations.md
@@ -211,7 +211,7 @@ The tenant has no environment variable. Pass it as an argument when you initiali
This approach is useful when you need to:
-- Manage separate client IDs for different platforms (Android, iOS, Web, macOS) in a centralized way
+- Manage separate client IDs for different platforms (Android, iOS, web, macOS) in a centralized way
- Avoid committing client IDs to version control
- Configure different credentials for different build environments (development, staging, production)
diff --git a/docs/06-concepts/04-authentication/05-providers/08-microsoft/03-troubleshooting.md b/docs/06-concepts/04-authentication/05-providers/08-microsoft/03-troubleshooting.md
index 0b0ecdb6..0d850f52 100644
--- a/docs/06-concepts/04-authentication/05-providers/08-microsoft/03-troubleshooting.md
+++ b/docs/06-concepts/04-authentication/05-providers/08-microsoft/03-troubleshooting.md
@@ -32,7 +32,7 @@ Go through this before investigating a specific error. Most problems come from a
- [ ] The `tenant` passed on initialization matches the server's `tenant` setting. Both default to `common`.
- [ ] On **Android**, added the `flutter_web_auth_2` `CallbackActivity` to `AndroidManifest.xml` with the **exact** scheme and host used in your callback URL.
- [ ] On **Web**, created `web/auth.html` in your Flutter project with the callback script from [Web callback page (`auth.html`)](../../setup#web-callback-page-authhtml).
-- [ ] On **Web**, ran Flutter on a fixed `--web-port` matching the port in the registered redirect URI.
+- [ ] On **web**, ran Flutter on a fixed `--web-port` matching the port in the registered redirect URI.
## Sign-in fails with a redirect URI error
diff --git a/docs/06-concepts/04-authentication/11-legacy/01-setup.md b/docs/06-concepts/04-authentication/11-legacy/01-setup.md
index c9ca40e2..8cf9c6a4 100644
--- a/docs/06-concepts/04-authentication/11-legacy/01-setup.md
+++ b/docs/06-concepts/04-authentication/11-legacy/01-setup.md
@@ -1,19 +1,17 @@
---
sidebar_label: Setup
-description: The legacy serverpod_auth module adds email and social sign-in to older Serverpod projects. Install and configure it on the server and client.
+description: The legacy serverpod_auth module adds email and social sign-in to existing Serverpod projects. Install and configure it on the server and client.
---
# Set up the legacy auth module
-Serverpod comes with built-in user management and authentication. It is possible to build a [custom authentication implementation](custom-overrides), but the recommended way to authenticate users is to use the `serverpod_auth` module. The module makes it easy to authenticate with email or social sign-ins and currently supports signing in with email, Google, Apple, and Firebase.
-
-Future versions of the authentication module will include more options. If you write another authentication module, please consider [contributing](/contribute) your code.
+The legacy `serverpod_auth` module adds user management and sign-in with email, Google, Apple, and Firebase to existing Serverpod projects. New projects should use the [current authentication module](../setup) instead. To move an existing app off this module, see [Migrate from legacy auth](../../../upgrading/migrate-from-legacy-auth). It is also possible to build a [custom authentication implementation](custom-overrides).
## Installing the auth module
-Serverpod's auth module makes it easy to authenticate users through email or 3rd parties. The authentication module also handles basic user information, such as user names and profile pictures. Make sure to use the same version numbers as for Serverpod itself for all dependencies.
+Install the module on the server, client, and app as shown in the sections below. Beyond sign-in, the module handles basic user information, such as user names and profile pictures. Make sure to use the same version numbers as for Serverpod itself for all dependencies.
## Server setup
@@ -78,10 +76,10 @@ The full migration instructions can be found in the [migration guide](../../data
### Configure Authentication
-Serverpod's auth module comes with a default Authentication Configuration. To customize it, go to your main `server.dart` file, import the `serverpod_auth_server` module and set up the authentication configuration:
+The module comes with a default authentication configuration. To customize it, go to your main `server.dart` file, import the `serverpod_auth_server` module and set up the authentication configuration:
```dart
-import 'package:serverpod_auth_server/module.dart' as auth;
+import 'package:serverpod_auth_server/serverpod_auth_server.dart' as auth;
void run(List args) async {
@@ -95,35 +93,34 @@ void run(List args) async {
```
-| **Property** | **Description** | **Default** |
-| :----------------------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :------------------------: |
-| **allowUnsecureRandom** | True if unsecure random number generation is allowed. If set to false, an error will be thrown if the platform does not support secure random number generation. | false |
-| **emailSignInFailureResetTime** | The reset period for email sign in attempts. Defaults to 5 minutes. | 5min |
-| **enableUserImages** | True if user images are enabled. | true |
-| **extraSaltyHash** | True if the server should use the accounts email address as part of the salt when storing password hashes (strongly recommended). | true |
-| **firebaseServiceAccountKeyJson** | Firebase service account key JSON file. Generate and download from the Firebase console. | - |
-| **importUserImagesFromGoogleSignIn** | True if user images should be imported when signing in with Google. | true |
-| **legacyUserSignOutBehavior** | Defines the default behavior for the deprecated `signOut` method used in the status endpoint. This setting controls whether users are signed out from all active devices (`SignOutOption.allDevices`) or just the current device (`SignOutOption.currentDevice`). | `SignOutOption.allDevices` |
-| **maxAllowedEmailSignInAttempts** | Max allowed failed email sign in attempts within the reset period. | 5 |
-| **maxPasswordLength** | The maximum length of passwords when signing up with email. | 128 |
-| **minPasswordLength** | The minimum length of passwords when signing up with email. | 8 |
-| **onUserCreated** | Called after a user has been created. Listen to this callback if you need to do additional setup. | - |
-| **onUserUpdated** | Called whenever a user has been updated. This can be when the user name is changed or if the user uploads a new profile picture. | - |
-| **onUserWillBeCreated** | Called when a user is about to be created, gives a chance to abort the creation by returning false. | - |
-| **passwordResetExpirationTime** | The time for password resets to be valid. | 24h |
-| **sendPasswordResetEmail** | Called when a user should be sent a reset code by email. | - |
-| **sendValidationEmail** | Called when a user should be sent a validation code on account setup. | - |
-| **userCanEditFullName** | True if users can edit their full name. | false |
-| **userCanEditUserImage** | True if users can update their profile images. | true |
-| **userCanEditUserName** | True if users can edit their user names. | true |
-| **userCanSeeFullName** | True if users can view their full name. | true |
-| **userCanSeeUserName** | True if users can view their user name. | true |
-| **userImageFormat** | The format used to store user images. | jpg |
-| **userImageGenerator** | Generator used to produce default user images. | - |
-| **userImageQuality** | The quality setting for images if JPG format is used. | 70 |
-| **userImageSize** | The size of user images. | 256 |
-| **userInfoCacheLifetime** | The duration which user infos are cached locally in the server. | 1min |
-| **validationCodeLength** | The length of the validation code used in the authentication process. This value determines the number of digits in the validation code. Setting this value to less than 3 reduces security. | 8 |
+| **Property** | **Description** | **Default** |
+| :----------------------------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :----------------------------------------: |
+| **allowUnsecureRandom** | True if unsecure random number generation is allowed. If set to false, an error will be thrown if the platform does not support secure random number generation. | false |
+| **emailSignInFailureResetTime** | The reset period for email sign in attempts. Defaults to 5 minutes. | 5min |
+| **enableUserImages** | True if user images are enabled. | true |
+| **extraSaltyHash** | True if the server should use the accounts email address as part of the salt when storing password hashes (strongly recommended). | true |
+| **firebaseServiceAccountKeyJson** | Path to the Firebase service account key JSON file. Generate and download from the Firebase console. | `config/firebase_service_account_key.json` |
+| **importUserImagesFromGoogleSignIn** | True if user images should be imported when signing in with Google. | true |
+| **maxAllowedEmailSignInAttempts** | Max allowed failed email sign in attempts within the reset period. | 5 |
+| **maxPasswordLength** | The maximum length of passwords when signing up with email. | 128 |
+| **minPasswordLength** | The minimum length of passwords when signing up with email. | 8 |
+| **onUserCreated** | Called after a user has been created. Listen to this callback if you need to do additional setup. | - |
+| **onUserUpdated** | Called whenever a user has been updated. This can be when the user name is changed or if the user uploads a new profile picture. | - |
+| **onUserWillBeCreated** | Called when a user is about to be created, gives a chance to abort the creation by returning false. | - |
+| **passwordResetExpirationTime** | The time for password resets to be valid. | 15min |
+| **sendPasswordResetEmail** | Called when a user should be sent a reset code by email. | - |
+| **sendValidationEmail** | Called when a user should be sent a validation code on account setup. | - |
+| **userCanEditFullName** | True if users can edit their full name. | false |
+| **userCanEditUserImage** | True if users can update their profile images. | true |
+| **userCanEditUserName** | True if users can edit their user names. | true |
+| **userCanSeeFullName** | True if users can view their full name. | true |
+| **userCanSeeUserName** | True if users can view their user name. | true |
+| **userImageFormat** | The format used to store user images. | jpg |
+| **userImageGenerator** | Generator used to produce default user images. | `defaultUserImageGenerator` |
+| **userImageQuality** | The quality setting for images if JPG format is used. | 70 |
+| **userImageSize** | The size of user images. | 256 |
+| **userInfoCacheLifetime** | The duration which user infos are cached locally in the server. | 1min |
+| **validationCodeLength** | The length of the validation code used in the authentication process. This value determines the number of digits in the validation code. Values below 8 log a security warning, and values below 4 throw an `ArgumentError`. | 8 |
## Client setup
@@ -132,7 +129,7 @@ Add the auth client in your client project's `pubspec.yaml`.
```yaml
dependencies:
...
- serverpod_auth_client: ^1.x.x
+ serverpod_auth_client: 4.0.0-beta.1
```
## App setup
@@ -143,11 +140,11 @@ First, add dependencies to your app's `pubspec.yaml` file for the methods of sig
dependencies:
flutter:
sdk: flutter
- serverpod_flutter: ^1.x.x
+ serverpod_flutter: 4.0.0-beta.1
auth_example_client:
path: ../auth_example_client
- serverpod_auth_shared_flutter: ^1.x.x
+ serverpod_auth_shared_flutter: 4.0.0-beta.1
```
Next, you need to set up a `SessionManager`, which keeps track of the user's state. It will also handle the authentication keys passed to the client from the server, upload user profile images, etc.
@@ -171,10 +168,9 @@ void main() async {
// The client is set up to connect to a Serverpod running on a local server on
// the default port. You will need to modify this to connect to staging or
// production servers.
- client = Client(
- 'http://$ipAddress:8080/',
- authenticationKeyManager: FlutterAuthenticationKeyManager(),
- )..connectivityMonitor = FlutterConnectivityMonitor();
+ client = Client('http://$ipAddress:8080/')
+ ..authKeyProvider = FlutterAuthenticationKeyManager()
+ ..connectivityMonitor = FlutterConnectivityMonitor();
// The session manager keeps track of the signed-in state of the user. You
// can query it to see if the user is currently signed in and get information
@@ -222,7 +218,7 @@ await sessionManager.registerSignedInUser(
);
```
-This will persist the user information and refresh any open streaming connection, see [Custom Providers - Client Setup](providers/custom-providers#client-setup) for more details.
+This will persist the user information and store the auth key in the client's key manager. For more details, see [Custom Providers - Client Setup](providers/custom-providers#client-setup).
#### Monitor authentication changes
@@ -263,11 +259,5 @@ await sessionManager.signOutAllDevices();
Returns `true` if the user is successfully signed out from all devices, or `false` if it fails.
:::info
-
-The `signOut` method is deprecated. This method calls the deprecated `signOut` status endpoint. For additional details, see the [deprecated signout endpoint](basics#sign-out-all-devices) section. Use `signOutDevice` or `signOutAllDevices` instead.
-
-```dart
-await sessionManager.signOut(); // Deprecated
-```
-
+The `signOut` method was removed in the 3.0 release of the module. Use `signOutDevice` or `signOutAllDevices` instead.
:::
diff --git a/docs/06-concepts/04-authentication/11-legacy/02-basics.md b/docs/06-concepts/04-authentication/11-legacy/02-basics.md
index 477ba2e5..16407a9f 100644
--- a/docs/06-concepts/04-authentication/11-legacy/02-basics.md
+++ b/docs/06-concepts/04-authentication/11-legacy/02-basics.md
@@ -5,13 +5,17 @@ description: Authentication tokens in the legacy serverpod_auth module are handl
# Legacy authentication basics
+:::info
+This page documents the legacy `serverpod_auth` module. To move an existing app to the current authentication framework, see [Migrate from legacy auth](../../../upgrading/migrate-from-legacy-auth).
+:::
+
Serverpod automatically checks if the user is logged in and if the user has the right privileges to access the endpoint. When using the `serverpod_auth` module you will not have to worry about keeping track of tokens, refreshing them or, even including them in requests as this all happens automatically under the hood.
-The `Session` object provides information about the current user. A unique `userIdentifier` identifies a user. You should use this id whenever you a referring to a user. Access the id of a signed-in user through the `authenticated` asynchronous getter of the `Session` object. Since the default implementation of `serverpod_auth` uses numeric IDs for the users, there is a convenience getter `userId` on the `AuthenticationInfo`, which returns the integer value.
+The `Session` object provides information about the current user. A unique `userIdentifier` identifies a user. You should use this id whenever you are referring to a user. Access the id of a signed-in user through the `authenticated` getter of the `Session` object. Since the default implementation of `serverpod_auth` uses numeric IDs for the users, there is a convenience getter `userId` on the `AuthenticationInfo`, which returns the integer value.
```dart
Future myMethod(Session session) async {
- final authenticationInfo = await session.authenticated;
+ final authenticationInfo = session.authenticated;
final userIdentifier = authenticationInfo?.userIdentifier;
final userId = authenticationInfo?.userId;
...
@@ -22,7 +26,7 @@ You can also use the Session object to check if a user is authenticated:
```dart
Future myMethod(Session session) async {
- var isSignedIn = await session.isUserSignedIn;
+ var isSignedIn = session.isUserSignedIn;
...
}
```
@@ -68,7 +72,7 @@ class UnauthenticatedEndpoint extends Endpoint {
}
Stream someStream(Session session) async* {
- yield await session.isUserSignedIn; // Will always return false
+ yield session.isUserSignedIn; // Will always return false
}
}
```
@@ -188,11 +192,5 @@ await client.modules.auth.status.signOutAllDevices();
This status endpoint retrieves the user ID from session's authentication information, then revokes all authentication keys related to that user.
:::info
-The `signOut` status endpoint is deprecated. Use `signOutDevice` or `signOutAllDevices` instead.
-
-```dart
-await client.modules.auth.status.signOut(); // Deprecated
-```
-
-The behavior of `signOut` is controlled by `legacyUserSignOutBehavior`, which you can adjust in the [configure authentication](setup#configure-authentication) section. This allows you to control the signout behaviour of already shipped clients.
+The `signOut` status endpoint was removed in the 3.0 release of the module. Use `signOutDevice` or `signOutAllDevices` instead.
:::
diff --git a/docs/06-concepts/04-authentication/11-legacy/03-working-with-users.md b/docs/06-concepts/04-authentication/11-legacy/03-working-with-users.md
index cf1b998c..0ad584b5 100644
--- a/docs/06-concepts/04-authentication/11-legacy/03-working-with-users.md
+++ b/docs/06-concepts/04-authentication/11-legacy/03-working-with-users.md
@@ -4,10 +4,14 @@ description: User information in the legacy serverpod_auth module is read and up
# Working with users
+:::info
+This page documents the legacy `serverpod_auth` module. To move an existing app to the current authentication framework, see [Migrate from legacy auth](../../../upgrading/migrate-from-legacy-auth).
+:::
+
It's a common task to read or update user information on your server. You can always retrieve the id of a signed-in user through the session object.
```dart
-var userId = (await session.authenticated)?.userId;
+var userId = session.authenticated?.userId;
```
If you sign in users through the auth module, you will be able to retrieve more information through the static methods of the `Users` class.
diff --git a/docs/06-concepts/04-authentication/11-legacy/04-providers/01-email.md b/docs/06-concepts/04-authentication/11-legacy/04-providers/01-email.md
index 3a833998..a78949cd 100644
--- a/docs/06-concepts/04-authentication/11-legacy/04-providers/01-email.md
+++ b/docs/06-concepts/04-authentication/11-legacy/04-providers/01-email.md
@@ -5,6 +5,10 @@ description: Sign in with Email in the legacy serverpod_auth module connects Ser
# Email sign-in
+:::info
+This page documents the legacy `serverpod_auth` module. To move an existing app to the current authentication framework, see [Migrate from legacy auth](../../../../upgrading/migrate-from-legacy-auth).
+:::
+
To properly configure Sign in with Email, you must connect your Serverpod to an external service that can send the emails. One convenient option is the [mailer](https://pub.dev/packages/mailer) package, which can send emails through any SMTP service. Most email providers, such as Sendgrid or Mandrill, support SMTP.
A comprehensive tutorial covering email/password sign-in complete with sending the validation code via email is available [here](https://medium.com/serverpod/getting-started-with-serverpod-authentication-part-1-72c25280e6e9).
@@ -18,7 +22,7 @@ You need to install the auth module before you continue, see [Setup](../setup).
In your main `server.dart` file, import the `serverpod_auth_server` module, and set up the authentication configuration:
```dart
-import 'package:serverpod_auth_server/module.dart' as auth;
+import 'package:serverpod_auth_server/serverpod_auth_server.dart' as auth;
auth.AuthConfig.set(auth.AuthConfig(
sendValidationEmail: (session, email, validationCode) async {
@@ -50,7 +54,7 @@ Add the dependencies to your `pubspec.yaml` in your **client** project.
```yaml
dependencies:
...
- serverpod_auth_client: ^1.x.x
+ serverpod_auth_client: 4.0.0-beta.1
```
Add the dependencies to your `pubspec.yaml` in your **Flutter** project.
@@ -58,8 +62,8 @@ Add the dependencies to your `pubspec.yaml` in your **Flutter** project.
```yaml
dependencies:
...
- serverpod_auth_email_flutter: ^1.x.x
- serverpod_auth_shared_flutter: ^1.x.x
+ serverpod_auth_email_flutter: 4.0.0-beta.1
+ serverpod_auth_shared_flutter: 4.0.0-beta.1
```
### Prebuilt sign in button
@@ -99,7 +103,7 @@ To let a user signup first call the `createAccountRequest` method which will tri
await authController.createAccountRequest(userName, email, password);
```
-Then let the user type in the code and send it to the backend with the `validateAccount` method. This method will create the user and sign them in if the code is valid.
+Then let the user type in the code and send it to the backend with the `validateAccount` method. This method creates the user and returns the new `UserInfo` if the code is valid. Call `signIn` afterwards to sign the user in.
```dart
await authController.validateAccount(email, verificationCode);
@@ -123,7 +127,7 @@ Let the user type in the verification code along with the new password and send
await authController.resetPassword(email, verificationCode, password);
```
-After the password has been reset you have to call the `signIn` method to log in. This can be achieved by either letting the user type in the details again or simply chaining the `resetPassword` method and the `singIn` method for a seamless UX.
+After the password has been reset you have to call the `signIn` method to log in. This can be achieved by either letting the user type in the details again or chaining the `resetPassword` and `signIn` methods for a seamless UX.
## Password storage security
@@ -156,37 +160,36 @@ If the pepper is changed, all passwords in the database will need to be re-hashe
### Secure random
-Serverpod uses the `dart:math` library to generate random salts for password hashing. By default, if no secure random number generator is available, a cryptographically unsecure random number is used.
+Serverpod uses the `dart:math` library to generate random salts for password hashing. By default, the server throws an exception if no secure random number generator is available (the `allowUnsecureRandom` property in the `AuthConfig` defaults to `false`).
-It is possible to prevent this fallback by setting the `allowUnsecureRandom` property in the `AuthConfig` to `false`. If the `allowUnsecureRandom` property is false, the server will throw an exception if a secure random number generator is unavailable.
+To fall back to a cryptographically unsecure random number instead, set the `allowUnsecureRandom` property to `true`.
```dart
auth.AuthConfig.set(auth.AuthConfig(
- allowUnsecureRandom: false,
+ allowUnsecureRandom: true,
));
```
## Custom password hash generator
-It is possible to override the default password hash generator. The `AuthConfig` class allows you to provide a custom hash generator using the field `passwordHashGenerator` and a custom hash validator through the field `passwordHashValidator`.
+It is possible to override the default password hash generator. The `AuthConfig` class allows you to provide a custom hash generator using the field `passwordHashGenerator` and a custom hash validator through the field `passwordHashValidator`. The validator receives named parameters and must return a `PasswordValidationResult`, either `PasswordValidationSuccess` or `PasswordValidationFailed`.
```dart
AuthConfig(
- passwordHashValidator: (
- password,
- email,
- hash, {
- onError,
- onValidationFailure,
- },
- ) {
- // Custom hash validator.
+ passwordHashValidator: ({
+ required password,
+ required email,
+ required hash,
+ }) async {
+ // Custom hash validation. Return PasswordValidationSuccess() if the
+ // password matches the hash.
+ return const PasswordValidationSuccess();
},
- passwordHashGenerator: (password) {
- // Custom hash generator.
+ passwordHashGenerator: (password) async {
+ // Custom hash generation. Return the generated hash.
+ return myHashFunction(password);
},
)
-
```
It could be useful if you already have stored passwords that should be preserved or migrated.
diff --git a/docs/06-concepts/04-authentication/11-legacy/04-providers/02-google.md b/docs/06-concepts/04-authentication/11-legacy/04-providers/02-google.md
index ca89ccd7..eb3a0cd3 100644
--- a/docs/06-concepts/04-authentication/11-legacy/04-providers/02-google.md
+++ b/docs/06-concepts/04-authentication/11-legacy/04-providers/02-google.md
@@ -1,16 +1,20 @@
---
sidebar_label: Google
-description: Sign in with Google in the legacy serverpod_auth module uses Google credentials added to your app and server across iOS, Android, and Web.
+description: Sign in with Google in the legacy serverpod_auth module uses Google credentials added to your app and server across iOS, Android, and web.
---
# Google sign-in
+:::info
+This page documents the legacy `serverpod_auth` module. To move an existing app to the current authentication framework, see [Migrate from legacy auth](../../../../upgrading/migrate-from-legacy-auth).
+:::
+
To set up Sign in with Google, you will need a Google account for your organization and set up a new project. For the project, you need to set up _Credentials_ and _Oauth consent screen_. You will also need to add the `serverpod_auth_google_flutter` package to your app and do some additional setup depending on each platform.
A comprehensive tutorial covering everything about google sign in is available [here](https://medium.com/serverpod/integrating-google-sign-in-with-serverpod-authentication-part-2-6fade3099baf).
:::note
-Right now, we have official support for iOS, Android, and Web for Google Sign In.
+Right now, we have official support for iOS, Android, and web for Google Sign In.
:::
:::caution
@@ -159,7 +163,7 @@ For development inside `Authorized redirect URIs` add `http://localhost:8082/goo
Register the Google Sign In route inside `server.dart`.
```dart
-import 'package:serverpod_auth_server/module.dart' as auth
+import 'package:serverpod_auth_server/serverpod_auth_server.dart' as auth;
void run(List args) async {
@@ -231,7 +235,7 @@ SignInWithGoogleButton(
On the server, you can utilize the [googleapis](https://pub.dev/packages/googleapis) package to access the Youtube API by first creating a client, then calling the API.
```dart
-import 'package:serverpod_auth_server/module.dart';
+import 'package:serverpod_auth_server/serverpod_auth_server.dart';
import 'package:googleapis/youtube/v3.dart';
diff --git a/docs/06-concepts/04-authentication/11-legacy/04-providers/03-apple.md b/docs/06-concepts/04-authentication/11-legacy/04-providers/03-apple.md
index d0cfff9e..eff62e0a 100644
--- a/docs/06-concepts/04-authentication/11-legacy/04-providers/03-apple.md
+++ b/docs/06-concepts/04-authentication/11-legacy/04-providers/03-apple.md
@@ -5,6 +5,10 @@ description: Sign in with Apple in the legacy serverpod_auth module is supported
# Apple sign-in
+:::info
+This page documents the legacy `serverpod_auth` module. To move an existing app to the current authentication framework, see [Migrate from legacy auth](../../../../upgrading/migrate-from-legacy-auth).
+:::
+
Sign-in with Apple, requires that you have a subscription to the [Apple developer program](https://developer.apple.com/programs/), even if you only want to test the feature in development mode.
A comprehensive tutorial covering Sign in with Apple is available [here](https://medium.com/serverpod/integrating-apple-sign-in-with-serverpod-authentication-part-3-f5a49d006800).
@@ -28,7 +32,7 @@ Add the dependency to your `pubspec.yaml` in your flutter project.
```yaml
dependencies:
...
- serverpod_auth_apple_flutter: ^1.x.x
+ serverpod_auth_apple_flutter: 4.0.0-beta.1
```
### Config
@@ -44,7 +48,7 @@ Enable the sign-in with Apple capability in your Xcode project, this is the same
`serverpod_auth_apple_flutter` package comes with the widget `SignInWithAppleButton` that renders a nice Sign in with Apple button and triggers the native sign-in UI.
```dart
-import 'package:serverpod_auth_email_flutter/serverpod_auth_email_flutter.dart';
+import 'package:serverpod_auth_apple_flutter/serverpod_auth_apple_flutter.dart';
SignInWithAppleButton(
caller: client.modules.auth,
diff --git a/docs/06-concepts/04-authentication/11-legacy/04-providers/05-firebase.md b/docs/06-concepts/04-authentication/11-legacy/04-providers/05-firebase.md
index b7de50a3..c6da2241 100644
--- a/docs/06-concepts/04-authentication/11-legacy/04-providers/05-firebase.md
+++ b/docs/06-concepts/04-authentication/11-legacy/04-providers/05-firebase.md
@@ -5,6 +5,10 @@ description: Firebase authentication in the legacy serverpod_auth module uses Fi
# Firebase authentication
+:::info
+This page documents the legacy `serverpod_auth` module. To move an existing app to the current authentication framework, see [Migrate from legacy auth](../../../../upgrading/migrate-from-legacy-auth).
+:::
+
Serverpod uses [Firebase UI auth](https://pub.dev/packages/firebase_ui_auth) to handle authentication through Firebase. It allows you to add social sign-in types that Serverpod doesn't directly support.
:::warning
diff --git a/docs/06-concepts/04-authentication/11-legacy/04-providers/06-custom-providers.md b/docs/06-concepts/04-authentication/11-legacy/04-providers/06-custom-providers.md
index 4293c3f4..b325c2a8 100644
--- a/docs/06-concepts/04-authentication/11-legacy/04-providers/06-custom-providers.md
+++ b/docs/06-concepts/04-authentication/11-legacy/04-providers/06-custom-providers.md
@@ -4,11 +4,15 @@ description: Custom providers in the legacy serverpod_auth module let you implem
# Custom providers
-Serverpod's authentication module makes it easy to implement custom authentication providers. This allows you to leverage all the existing providers supplied by the module along with the specific providers your project requires.
+:::info
+This page documents the legacy `serverpod_auth` module. To move an existing app to the current authentication framework, see [Migrate from legacy auth](../../../../upgrading/migrate-from-legacy-auth).
+:::
+
+The legacy `serverpod_auth` module makes it easy to implement custom authentication providers. This allows you to leverage all the existing providers supplied by the module along with the specific providers your project requires.
## Server setup
-After successfully authenticating a user through a customer provider, an auth token can be created and connected to the user to preserve the authenticated user's permissions. This token is used to identify the user and facilitate endpoint authorization validation. The token can be removed when the user signs out to prevent further access.
+After successfully authenticating a user through a custom provider, an auth token can be created and connected to the user to preserve the authenticated user's permissions. This token is used to identify the user and facilitate endpoint authorization validation. The token can be removed when the user signs out to prevent further access.
### Connect user
@@ -63,7 +67,7 @@ To create an auth token, call the `signInUser` method in the `UserAuthentication
The `signInUser` method takes four arguments: the first is the session object, the second is the user ID, the third is information about the method of authentication, and the fourth is a set of scopes granted to the auth token.
```dart
-var authToken = await UserAuthentication.signInUser(userInfo.id, 'myAuthMethod', scopes: {
+var authToken = await UserAuthentication.signInUser(session, userInfo.id!, 'myAuthMethod', scopes: {
Scope('delete'),
Scope('create'),
});
@@ -140,7 +144,7 @@ To revoke a specific authentication key for the current session, you can directl
```dart
// Fetch the authentication information for the current session
-var authId = (await session.authenticated)?.authId;
+var authId = session.authenticated?.authId;
// Revoke the authentication key if the session is authenticated and has an authId
if (authId != null) {
diff --git a/docs/06-concepts/04-authentication/11-legacy/05-custom-overrides.md b/docs/06-concepts/04-authentication/11-legacy/05-custom-overrides.md
index fdf7b9c9..a929ec20 100644
--- a/docs/06-concepts/04-authentication/11-legacy/05-custom-overrides.md
+++ b/docs/06-concepts/04-authentication/11-legacy/05-custom-overrides.md
@@ -5,7 +5,11 @@ description: Custom authentication overrides in the legacy serverpod_auth module
# Custom authentication overrides
-It is recommended to use the `serverpod_auth` package but if you have special requirements not fulfilled by it, you can implement your authentication module. Serverpod is designed to make it easy to add custom authentication overrides.
+:::info
+This page documents the legacy `serverpod_auth` module. To move an existing app to the current authentication framework, see [Migrate from legacy auth](../../../upgrading/migrate-from-legacy-auth).
+:::
+
+If the legacy `serverpod_auth` module does not fulfill your requirements, you can implement your own authentication handling. Serverpod is designed to make it easy to add custom authentication overrides.
## Server setup
@@ -25,15 +29,15 @@ final pod = Serverpod(
/// Custom validation handler
if (token != 'valid') return null;
- return AuthenticationInfo(1, {});
+ return AuthenticationInfo('1', {}, authId: 'valid');
},
);
```
-In the above example, the `authenticationHandler` callback is overridden with a custom validation method. The method returns an `AuthenticationInfo` object with `userIdentifier` `"1"` and no scopes if the token is the literal "valid", otherwise `null`.
+In the above example, the `authenticationHandler` callback is overridden with a custom validation method. The method returns an `AuthenticationInfo` object with `userIdentifier` `"1"`, no scopes, and `authId` `"valid"` if the token is the literal "valid", otherwise `null`.
:::note
-The `userIdentifier` passed to the `AuthenticationInfo` constructor, as the first parameter, will always be converted to a `String` and thus stored internally. Since the default implementation of `serverpod_auth` uses numeric IDs for the users, there is a convenience getter `userId`, which returns the integer value.
+The `userIdentifier` passed to the `AuthenticationInfo` constructor, as the first parameter, is a `String` and must not be empty. Since the default implementation of `serverpod_auth` uses numeric IDs for the users, the legacy module provides a convenience getter `userId`, which parses the identifier and returns the integer value.
:::
:::note
@@ -41,7 +45,7 @@ In the authenticationHandler callback the `authenticated` field on the session w
:::
:::info
-By specifying the optional `authId` field in the `AuthenticationInfo` object you can link the user to a specific authentication id. This is useful when revoking authentication for a specific device.
+The required `authId` field in the `AuthenticationInfo` object links the user to a specific authentication id, for example a device session. It is what `RevokedAuthenticationAuthId` matches against when revoking authentication for a specific device.
:::
#### Scopes
@@ -60,21 +64,21 @@ Set userScopes = scopes.map((scope) => Scope(scope)).toSet();
When a user's authentication is revoked, the server must be notified to respect the changes (e.g. to close method streams). Invoke the `session.messages.authenticationRevoked` method and raise the appropriate event to notify the server.
```dart
-var userId = 1;
+var userIdentifier = '1';
var revokedScopes = ['write'];
var message = RevokedAuthenticationScope(
scopes: revokedScopes,
);
await session.messages.authenticationRevoked(
- userId,
+ userIdentifier,
message,
);
```
##### Parameters
-- `userId` - The user id belonging to the `AuthenticationInfo` object to be revoked.
+- `userIdentifier` - The `userIdentifier` of the `AuthenticationInfo` object to be revoked.
- `message` - The revoked authentication event message. See below for the different type of messages.
#### Revoked authentication messages
@@ -95,7 +99,7 @@ You are responsible for implementing the endpoints to authenticate/authorize the
```dart
class UserEndpoint extends Endpoint {
- Future login(
+ Future login(
Session session,
String username,
String password,
@@ -116,7 +120,7 @@ Enabling authentication in the client is as simple as configuring a key manager
### Configure key manager
-Key managers need to implement the `AuthenticationKeyManager` interface. The key manager is configured when creating the client by passing it as the named parameter `authenticationKeyManager`. If no key manager is configured, the client will not include tokens in requests to the server.
+Key managers need to implement the `AuthenticationKeyManager` interface. The interface's abstract `toHeaderValue` method formats the token for the HTTP authorization header. The class is deprecated in favor of `ClientAuthKeyProvider`, so the analyzer warns on it. It keeps working with the legacy module. The key manager is assigned to the client's `authKeyProvider` field. If no key manager is configured, the client will not include tokens in requests to the server.
```dart
class SimpleAuthKeyManager extends AuthenticationKeyManager {
@@ -136,11 +140,19 @@ class SimpleAuthKeyManager extends AuthenticationKeyManager {
Future remove() async {
_key = null;
}
+
+ @override
+ Future toHeaderValue(String? key) async {
+ if (key == null) return null;
+ return wrapAsBasicAuthHeaderValue(key);
+ }
}
-var client = Client('http://$localhost:8080/',
- authenticationKeyManager: SimpleAuthKeyManager())
+var keyManager = SimpleAuthKeyManager();
+
+var client = Client('http://localhost:8080/')
+ ..authKeyProvider = keyManager
..connectivityMonitor = FlutterConnectivityMonitor();
```
@@ -152,18 +164,14 @@ The `SimpleAuthKeyManager` is not practical and should only be used for testing.
:::
-The key manager is then available through the client's `authenticationKeyManager` field.
-
-```dart
-var keyManager = client.authenticationKeyManager;
-```
+The sections below use the `keyManager` reference created above to interact with the stored token.
### Store token
When the client receives a token from the server, it is responsible for storing it in the key manager using the `put` method. The key manager will then include the token in all requests to the server.
```dart
-await client.authenticationKeyManager?.put(token);
+await keyManager.put(token);
```
In the above example, the `token` is placed in the key manager. It will now be included in communication with the server.
@@ -173,7 +181,7 @@ In the above example, the `token` is placed in the key manager. It will now be i
To remove the token from the key manager, call the `remove` method.
```dart
-await client.authenticationKeyManager?.remove();
+await keyManager.remove();
```
The above example removes any token from the key manager.
@@ -183,26 +191,26 @@ The above example removes any token from the key manager.
To retrieve the token from the key manager, call the `get` method.
```dart
-var token = await client.authenticationKeyManager?.get();
+var token = await keyManager.get();
```
The above example retrieves the token from the key manager and stores it in the `token` variable.
## Authentication schemes
-By default Serverpod will pass the authentication token from client to server in accordance with the HTTP `authorization` header standard with the `basic` scheme name and encoding. This is securely transferred as the connection is TLS encrypted.
+The module's shipped key manager, `FlutterAuthenticationKeyManager`, passes the authentication token from client to server in accordance with the HTTP `authorization` header standard, with the `basic` scheme name and encoding. This is securely transferred as the connection is TLS encrypted.
-The default implementation encodes and wraps the user-provided token in a `basic` scheme which is automatically unwrapped on the server side before being handed to the user-provided authentication handler described above.
+The legacy module's `FlutterAuthenticationKeyManager` encodes and wraps the user-provided token in a `basic` scheme with the `wrapAsBasicAuthHeaderValue` helper. The value is automatically unwrapped on the server side before being handed to the user-provided authentication handler described above.
-In other words the default transport implementation is "invisible" to user code.
+For apps using `FlutterAuthenticationKeyManager`, this wrapping and unwrapping is invisible to application code.
### Implementing your own authentication scheme
If you are implementing your own authentication and are using the `basic` scheme, note that this is supported but will be automatically unwrapped i.e. decoded on the server side before being handed to your `AuthenticationHandler` implementation. It will in this case receive the decoded auth key value after the `basic` scheme name.
-If you are implementing a different authentication scheme, for example OAuth 2 using bearer tokens, you should override the default method `toHeaderValue` of `AuthenticationKeyManager`. This client-side method converts the authentication key to the format that shall be sent as a transport header to the server.
+If you are implementing a different authentication scheme, for example OAuth 2 using bearer tokens, implement the `toHeaderValue` method of your key manager accordingly. This client-side method converts the authentication key to the format that is sent as a transport header to the server.
-You will also need to implement the `AuthenticationHandler` accordingly, in order to process that header value server-side.
+On the server side, both `basic` and `bearer` values are automatically unwrapped before the `AuthenticationHandler` is invoked. The handler receives the bare token without the scheme prefix. Other schemes are passed through unchanged and need manual parsing in the handler.
The header value must be compliant with the HTTP header format defined in RFC 9110 HTTP Semantics, 11.6.2. Authorization.
See:
@@ -241,8 +249,8 @@ class MyOAuthKeyManager extends AuthenticationKeyManager {
}
-var client = Client('http://$localhost:8080/',
- authenticationKeyManager: SimpleAuthKeyManager())
+var client = Client('http://localhost:8080/')
+ ..authKeyProvider = MyOAuthKeyManager()
..connectivityMonitor = FlutterConnectivityMonitor();
```
@@ -256,10 +264,10 @@ final pod = Serverpod(
Endpoints(),
authenticationHandler: (Session session, String token) async {
/// Bearer token validation handler
- var (uid, scopes) = myBearerTokenValidator(token)
+ var (uid, scopes, authId) = myBearerTokenValidator(token);
if (uid == null) return null;
- return AuthenticationInfo(uid, scopes);
+ return AuthenticationInfo(uid, scopes, authId: authId);
},
);
```
diff --git a/docs/11-upgrading/01-upgrade-to-four.md b/docs/11-upgrading/01-upgrade-to-four.md
index ef0b93f2..43cdcc5b 100644
--- a/docs/11-upgrading/01-upgrade-to-four.md
+++ b/docs/11-upgrading/01-upgrade-to-four.md
@@ -22,7 +22,7 @@ This guide walks through the upgrade and should take about 15 minutes.
Install the 4.0 CLI:
```bash
-$ dart install serverpod_cli 4.0.0-beta.0
+$ dart install serverpod_cli 4.0.0-beta.1
```
Verify the version:
@@ -37,9 +37,9 @@ In each package's `pubspec.yaml` (`_server`, `_client`, `_server/pubspec.yaml` to match the 4.0 minimum:
@@ -49,6 +49,27 @@ environment:
sdk: '^3.10.3'
```
+### If you use the legacy auth module
+
+The legacy `serverpod_auth` packages ship 4.0 releases. Bump every `serverpod_auth` package your project uses to the same version as Serverpod itself, in the same `pubspec.yaml` files:
+
+```yaml
+dependencies:
+ serverpod_auth_server: 4.0.0-beta.1 # in the server package
+ serverpod_auth_client: 4.0.0-beta.1 # in the client package
+ serverpod_auth_shared_flutter: 4.0.0-beta.1 # in the Flutter package
+```
+
+The `authenticationKeyManager` parameter on the generated `Client` is deprecated in 4.0 and will be removed in an upcoming release. Assign the key manager to the `authKeyProvider` field instead:
+
+```dart
+client = Client('http://$ipAddress:8080/')
+ ..authKeyProvider = FlutterAuthenticationKeyManager()
+ ..connectivityMonitor = FlutterConnectivityMonitor();
+```
+
+The module keeps working on 4.0, so this can be done independently of moving to the new authentication framework. To make that move, see [Migrate from legacy auth](./migrate-from-legacy-auth) after completing this upgrade.
+
From the project's root folder, refresh dependencies. Dart workspaces (used by projects created with the 3.3+ scaffold) resolve all sub-packages in one command:
```bash
diff --git a/docs/11-upgrading/03-migrate-from-legacy-auth.md b/docs/11-upgrading/03-migrate-from-legacy-auth.md
index 3ba28f33..efa30554 100644
--- a/docs/11-upgrading/03-migrate-from-legacy-auth.md
+++ b/docs/11-upgrading/03-migrate-from-legacy-auth.md
@@ -10,10 +10,10 @@ This guide is for apps still running `serverpod_auth_server` on Serverpod 3.4 or
## Before you start
- A Serverpod 4.0.x project. If you are on an earlier version, follow [Upgrade to 4.0](./upgrade-to-four) first.
-- Dart SDK 3.8.0 or later.
-- Flutter SDK 3.32.0 or later (only if you are migrating the Flutter app).
+- Dart SDK 3.10.3 or later.
+- Flutter SDK 3.38.4 or later (only if you are migrating the Flutter app).
- Postgres 14 or later, or SQLite3.
-- The four new auth packages at `4.0.0-beta.0`: `serverpod_auth_core`, `serverpod_auth_idp`, `serverpod_auth_bridge`, and `serverpod_auth_migration`.
+- The four new auth packages at `4.0.0-beta.1`: `serverpod_auth_core`, `serverpod_auth_idp`, `serverpod_auth_bridge`, and `serverpod_auth_migration`.
- Back up your production database.
- Commit your current state on a clean branch.
- Restore a copy of production data into a staging environment and rehearse this guide against it before running it for real.
@@ -26,32 +26,32 @@ In `_server/pubspec.yaml`:
```yaml
dependencies:
- serverpod: 4.0.0-beta.0
- serverpod_auth_server: 4.0.0-beta.0 # legacy, keep during migration
- serverpod_auth_core_server: 4.0.0-beta.0
- serverpod_auth_idp_server: 4.0.0-beta.0
- serverpod_auth_bridge_server: 4.0.0-beta.0
- serverpod_auth_migration_server: 4.0.0-beta.0
+ serverpod: 4.0.0-beta.1
+ serverpod_auth_server: 4.0.0-beta.1 # legacy, keep during migration
+ serverpod_auth_core_server: 4.0.0-beta.1
+ serverpod_auth_idp_server: 4.0.0-beta.1
+ serverpod_auth_bridge_server: 4.0.0-beta.1
+ serverpod_auth_migration_server: 4.0.0-beta.1
```
In `_client/pubspec.yaml`:
```yaml
dependencies:
- serverpod_client: 4.0.0-beta.0
- serverpod_auth_core_client: 4.0.0-beta.0
- serverpod_auth_idp_client: 4.0.0-beta.0
- serverpod_auth_bridge_client: 4.0.0-beta.0
+ serverpod_client: 4.0.0-beta.1
+ serverpod_auth_core_client: 4.0.0-beta.1
+ serverpod_auth_idp_client: 4.0.0-beta.1
+ serverpod_auth_bridge_client: 4.0.0-beta.1
```
In `_flutter/pubspec.yaml`:
```yaml
dependencies:
- serverpod_flutter: 4.0.0-beta.0
- serverpod_auth_core_flutter: 4.0.0-beta.0
- serverpod_auth_idp_flutter: 4.0.0-beta.0
- serverpod_auth_bridge_flutter: 4.0.0-beta.0
+ serverpod_flutter: 4.0.0-beta.1
+ serverpod_auth_core_flutter: 4.0.0-beta.1
+ serverpod_auth_idp_flutter: 4.0.0-beta.1
+ serverpod_auth_bridge_flutter: 4.0.0-beta.1
```
`serverpod_auth_bridge_client` and `serverpod_auth_bridge_flutter` are required for the session import covered later under [Update the Flutter app](#update-the-flutter-app).