Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
10 changes: 5 additions & 5 deletions docs/06-concepts/10-modules.md
Original file line number Diff line number Diff line change
Expand Up @@ -29,20 +29,20 @@ modules:
nickname: auth
```

Then run `pub get` and `serverpod generate` from your server's directory (e.g., `mypod_server`) to add the module to your project's deserializer.
Then run `pub get` from your server's directory (e.g., `mypod_server`):

```bash
$ dart pub get
$ serverpod generate
```

Finally, since modules might include modifications to the database schema, you should create a new database migration and apply it by running `serverpod create-migration` then `dart bin/main.dart --apply-migrations` from your server's directory.
Start the server to wire up the module:

```bash
$ serverpod create-migration
$ dart bin/main.dart --apply-migrations
$ serverpod start
```

The module adds tables to your database, so create and apply a migration: in the `serverpod start` terminal, press **M** to create the migration, then **A** to apply it.

### Client setup

In your client's `pubspec.yaml`, you will need to add the generated client code from the module.
Expand Down
17 changes: 3 additions & 14 deletions docs/06-concepts/11-authentication/01-setup.md
Original file line number Diff line number Diff line change
Expand Up @@ -112,24 +112,13 @@ By default, endpoints for all providers are disabled. To enable a provider, it i
class EmailIdpEndpoint extends EmailIdpBaseEndpoint {}
```

3. Run `serverpod generate` to generate the client code and endpoint methods for the provider.
3. Start the server with `serverpod start`. It generates the client code and endpoint methods for the provider, then runs the server with hot reload.

```bash
$ serverpod generate
$ serverpod start
```

4. Create a migration to initialize the database for the provider.

```bash
# Create the migration
$ serverpod create-migration

# Start the database container
$ docker compose up --build --detach

# Apply the migration
$ dart run bin/main.dart --role maintenance --apply-migrations
```
4. Create and apply the migration that initializes the database for the provider. In the `serverpod start` terminal, press **M** to create the migration, then **A** to apply it.

:::info
If this is the first time creating migrations after adding the module, besides the provider tables, all auth module tables will also be created. More detailed migration instructions can be found in the [migration guide](../database/migrations).
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -48,7 +48,7 @@ import 'package:serverpod_auth_idp_server/providers/anonymous.dart';
class AnonymousIdpEndpoint extends AnonymousIdpBaseEndpoint {}
```

Then, run `serverpod generate` to generate the client code and create a migration to initialize the database for the provider. More detailed instructions can be found in the general [identity providers setup section](../../setup#identity-providers-configuration).
Then, start the server with `serverpod start` to generate the client code, then create and apply the migration that initializes the database for the provider (in the `serverpod start` terminal, press **M**, then **A**). More detailed instructions can be found in the general [identity providers setup section](../../setup#identity-providers-configuration).

### Basic configuration options

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -76,7 +76,7 @@ import 'package:serverpod_auth_idp_server/providers/email.dart';
class EmailIdpEndpoint extends EmailIdpBaseEndpoint {}
```

Then, run `serverpod generate` to generate the client code and create a migration to initialize the database for the provider. More detailed instructions can be found in the general [identity providers setup section](../../setup#identity-providers-configuration).
Then, start the server with `serverpod start` to generate the client code, then create and apply the migration that initializes the database for the provider (in the `serverpod start` terminal, press **M**, then **A**). More detailed instructions can be found in the general [identity providers setup section](../../setup#identity-providers-configuration).

### Basic configuration options

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -145,16 +145,16 @@ import 'package:serverpod_auth_idp_server/providers/google.dart';
class GoogleIdpEndpoint extends GoogleIdpBaseEndpoint {}
```

### Generate code and apply migrations
### Start the server

Run the following commands from your server project directory (e.g., `my_project_server/`) to generate client code and apply the database migration:
Start the server from your server project directory (e.g., `my_project_server/`):

```bash
serverpod generate
serverpod create-migration
dart run bin/main.dart --apply-migrations
serverpod start
```

Then create and apply the migration for the provider's tables: in the `serverpod start` terminal, press **M** to create the migration, then **A** to apply it.

:::warning
Skipping the migration will cause the server to crash at runtime when the Google provider tries to read or write user data. More detailed instructions can be found in the general [identity providers setup section](../../setup#identity-providers-configuration).
:::
Expand Down Expand Up @@ -244,7 +244,7 @@ On web, Google completes sign-in by redirecting the browser to a callback URL yo

```bash
flutter build web --output ../my_project_server/web/app # from your Flutter project
dart run bin/main.dart # from your server project
serverpod start # from your server project
```

Open `http://localhost:8082/app` to test. `flutter run -d chrome` won't work here because Flutter's dev server runs on a different port from Serverpod — for hot-reload workflows, use the [separately-hosted Flutter web](./customizations#separately-hosted-flutter-web) flow instead.
Expand Down Expand Up @@ -322,7 +322,7 @@ Swap the redirect URI for your production URL when deploying. See [Configuring t

### Show the Google sign-in button

The Serverpod template ships with a `SignInScreen` widget at `lib/screens/sign_in_screen.dart`. It listens to `client.auth.authInfoListenable` and swaps between `SignInWidget` while the user is signed out and the `child` you pass it once they sign in. `SignInWidget` auto-detects which identity provider endpoints are registered on the server, so once `GoogleIdpEndpoint` is exposed and `serverpod generate` has run, the Google button appears inside it.
The Serverpod template ships with a `SignInScreen` widget at `lib/screens/sign_in_screen.dart`. It listens to `client.auth.authInfoListenable` and swaps between `SignInWidget` while the user is signed out and the `child` you pass it once they sign in. `SignInWidget` auto-detects which identity provider endpoints are registered on the server, so once `GoogleIdpEndpoint` is exposed and the client code has been regenerated, the Google button appears inside it.

```dart
import 'package:flutter/material.dart';
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -21,7 +21,7 @@ Go through this before investigating a specific error. Most problems come from a
- [ ] For new or customized servers, confirm auth services and JWT are configured per [Authentication setup](../../setup#identity-providers-configuration) before adding Google.
- [ ] Add `GoogleIdpConfigFromPasswords()` to `identityProviderBuilders` in `server.dart`.
- [ ] Create a `GoogleIdpEndpoint` file in `lib/src/auth/`.
- [ ] Run `serverpod generate`, then `serverpod create-migration`, then apply migrations using `--apply-migrations`.
- [ ] Start the server with `serverpod start`, then create and apply the migration (press **M**, then **A**).

#### Client

Expand Down Expand Up @@ -167,15 +167,9 @@ Every line of the JSON must be indented by at least one level more than `googleC

**Problem:** The server builds and starts, but crashes when a user tries Google sign-in. The error cites a missing table (like `serverpod_auth_idp_google_account`).

**Cause:** `serverpod generate` has been run, but you didn't create or apply the accompanying database migration.
**Cause:** The database migration that creates the provider's tables was never created or applied.

**Resolution:** Create and apply the migration:

```bash
serverpod generate
serverpod create-migration
dart run bin/main.dart --apply-migrations
```
**Resolution:** In the running `serverpod start` terminal, press **M** to create the migration, then **A** to apply it.

## Lightweight sign-in (One Tap) not appearing

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -166,16 +166,16 @@ import 'package:serverpod_auth_idp_server/providers/apple.dart';
class AppleIdpEndpoint extends AppleIdpBaseEndpoint {}
```

### Generate code and apply migrations
### Start the server

Run the following commands from your server project directory (e.g., `my_project_server/`) to generate client code and apply the database migration:
Start the server from your server project directory (e.g., `my_project_server/`):

```bash
serverpod generate
serverpod create-migration
dart run bin/main.dart --apply-migrations
serverpod start
```

Then create and apply the migration for the provider's tables: in the `serverpod start` terminal, press **M** to create the migration, then **A** to apply it.

:::note
Skipping the migration will cause the server to crash at runtime when the Apple provider tries to read or write user data. More detailed instructions can be found in the general [identity providers setup section](../../setup#identity-providers-configuration).
:::
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -23,7 +23,7 @@ Go through this before investigating a specific error. Most problems come from a
* [ ] Add `AppleIdpConfigFromPasswords()` to `identityProviderBuilders` in `server.dart`.
* [ ] Call **`pod.configureAppleIdpRoutes(...)`** on the server before the pod starts.
* [ ] Create an `AppleIdpEndpoint` file in `lib/src/auth/`.
* [ ] Run **`serverpod generate`**, then apply migrations using `--apply-migrations`.
* [ ] Start the server with `serverpod start`, then create and apply the migration (press **M**, then **A**).

#### Client

Expand Down Expand Up @@ -119,15 +119,9 @@ If you use `--dart-define`, confirm `APPLE_SERVICE_IDENTIFIER` is the Services I

**Problem:** The server builds and starts, but crashes when a user tries Apple sign-in. The error cites a missing table (like `serverpod_auth_idp_apple_account`).

**Cause:** `serverpod generate` has been run, but you didn't create or apply the accompanying database migration.
**Cause:** The database migration that creates the provider's tables was never created or applied.

**Resolution:** Create and apply the migration:

```bash
serverpod generate
serverpod create-migration
dart run bin/main.dart --apply-migrations
```
**Resolution:** In the running `serverpod start` terminal, press **M** to create the migration, then **A** to apply it.

## Apple rejects the redirect URI with `invalid_request`

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -141,7 +141,7 @@ class FacebookIdpEndpoint extends FacebookIdpBaseEndpoint {}

### Generate and migrate

Finally, run `serverpod generate` to generate the client code and create a migration to initialize the database for the provider. More detailed instructions can be found in the general [identity providers setup section](../../setup#identity-providers-configuration).
Finally, start the server with `serverpod start` to generate the client code, then create and apply the migration that initializes the database for the provider (in the `serverpod start` terminal, press **M**, then **A**). More detailed instructions can be found in the general [identity providers setup section](../../setup#identity-providers-configuration).

### Basic configuration options

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -134,16 +134,16 @@ import 'package:serverpod_auth_idp_server/providers/firebase.dart';
class FirebaseIdpEndpoint extends FirebaseIdpBaseEndpoint {}
```

### 3. Generate code and apply migrations
### 3. Start the server

Run the following commands from your server project directory (e.g., `my_project_server/`) to generate client code and apply the database migration:
Start the server from your server project directory (e.g., `my_project_server/`):

```bash
serverpod generate
serverpod create-migration
dart run bin/main.dart --apply-migrations
serverpod start
```

Then create and apply the migration for the provider's tables: in the `serverpod start` terminal, press **M** to create the migration, then **A** to apply it.

:::note
Skipping the migration will cause the server to crash at runtime when the Firebase provider tries to read or write user data. More detailed instructions can be found in the general [identity providers setup section](../../setup#identity-providers-configuration).
:::
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -21,7 +21,7 @@ Go through this before investigating a specific error. Most problems come from a
- [ ] Confirm the `project_id` inside `firebaseServiceAccountKey` matches the Firebase project the client is using.
- [ ] Add `FirebaseIdpConfigFromPasswords()` to `identityProviderBuilders` in `server.dart`.
- [ ] Create a `FirebaseIdpEndpoint` file in `lib/src/auth/` extending `FirebaseIdpBaseEndpoint`.
- [ ] Run **`serverpod generate`**, then **`serverpod create-migration`**, then apply migrations with `dart run bin/main.dart --apply-migrations`.
- [ ] Start the server with `serverpod start`, then create and apply the migration (press **M**, then **A**).

#### Client

Expand All @@ -36,15 +36,9 @@ Go through this before investigating a specific error. Most problems come from a

**Problem:** The server builds and starts, but crashes when a user tries Firebase sign-in. The error cites a missing table (like `serverpod_auth_idp_firebase_account`).

**Cause:** `serverpod generate` has been run, but you didn't create or apply the accompanying database migration.
**Cause:** The database migration that creates the provider's tables was never created or applied.

**Resolution:** Create and apply the migration:

```bash
serverpod generate
serverpod create-migration
dart run bin/main.dart --apply-migrations
```
**Resolution:** In the running `serverpod start` terminal, press **M** to create the migration, then **A** to apply it.

## Token verification fails with "invalid signature"

Expand Down Expand Up @@ -109,7 +103,7 @@ If you haven't run `flutterfire configure`, do so to generate the `firebase_opti

1. **Missing service account key:** The `firebaseServiceAccountKey` is not present in `passwords.yaml`, or the JSON is invalid.
2. **Missing endpoint:** You did not create the endpoint class extending `FirebaseIdpBaseEndpoint`. Without it, the client has no endpoint to call.
3. **Missing migration:** The provider's database tables don't exist yet. Apply migrations with `dart run bin/main.dart --apply-migrations`.
3. **Missing migration:** The provider's database tables don't exist yet. In the `serverpod start` terminal, press **M** to create the migration, then **A** to apply it.
4. **Project mismatch:** The service account key belongs to a different Firebase project than the one configured in your Flutter app. Compare `project_id` in `firebaseServiceAccountKey` against the project in `firebase_options.dart`.
5. **App Check enabled prematurely:** If you enabled Firebase App Check before the client integration is in place, every request will be rejected with an App Check assertion error. Disable App Check until the client is wired up.

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -140,16 +140,16 @@ import 'package:serverpod_auth_idp_server/providers/github.dart';
class GitHubIdpEndpoint extends GitHubIdpBaseEndpoint {}
```

### Generate code and apply migrations
### Start the server

Run the following commands from your server project directory (e.g., `my_project_server/`) to generate client code and apply the database migration:
Start the server from your server project directory (e.g., `my_project_server/`):

```bash
serverpod generate
serverpod create-migration
dart run bin/main.dart --apply-migrations
serverpod start
```

Then create and apply the migration for the provider's tables: in the `serverpod start` terminal, press **M** to create the migration, then **A** to apply it.

:::warning
Skipping the migration will cause the server to crash at runtime when the GitHub provider tries to read or write user data. More detailed instructions can be found in the general [identity providers setup section](../../setup#identity-providers-configuration).
:::
Expand Down Expand Up @@ -271,7 +271,7 @@ To keep these values out of `main.dart` and vary them per build, read them from

### Show the GitHub sign-in button

The Serverpod template ships with a `SignInScreen` widget at `lib/screens/sign_in_screen.dart`. It listens to `client.auth.authInfoListenable` and swaps between `SignInWidget` while the user is signed out and the `child` you pass it once they sign in. `SignInWidget` auto-detects which identity provider endpoints are registered on the server, so once `GitHubIdpEndpoint` is exposed and `serverpod generate` has run, the GitHub button appears inside it.
The Serverpod template ships with a `SignInScreen` widget at `lib/screens/sign_in_screen.dart`. It listens to `client.auth.authInfoListenable` and swaps between `SignInWidget` while the user is signed out and the `child` you pass it once they sign in. `SignInWidget` auto-detects which identity provider endpoints are registered on the server, so once `GitHubIdpEndpoint` is exposed and the client code has been regenerated, the GitHub button appears inside it.

To customize the GitHub button or build a fully custom UI, see [Customizing the UI](./customizing-the-ui).

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -20,7 +20,7 @@ Go through this before investigating a specific error. Most problems come from a
- [ ] Added `githubClientId` and `githubClientSecret` to `config/passwords.yaml` under the matching environment (`development:` for local, `production:` for prod), or set the matching `SERVERPOD_PASSWORD_githubClientId` and `SERVERPOD_PASSWORD_githubClientSecret` environment variables.
- [ ] Added `GitHubIdpConfigFromPasswords()` to `identityProviderBuilders` in `server.dart`.
- [ ] Created a `GitHubIdpEndpoint` file in `lib/src/auth/`.
- [ ] Ran `serverpod generate`, then `serverpod create-migration`, then applied migrations with `--apply-migrations`.
- [ ] Started the server with `serverpod start`, then created and applied the migration (pressed **M**, then **A**).

#### Client

Expand Down Expand Up @@ -161,7 +161,7 @@ See [Configuring client IDs on the app](./customizations#configuring-client-ids-

**Cause:** The keys are missing from `config/passwords.yaml`, are spelled differently, or are not present under the active environment section.

**Resolution:** Confirm both keys exist under the section matching your run mode (`development:` for `dart run bin/main.dart`, `production:` when deployed):
**Resolution:** Confirm both keys exist under the section matching your run mode (`development:` when running locally with `serverpod start`, `production:` when deployed):

```yaml
development:
Expand All @@ -175,15 +175,9 @@ Quotes are required because the values are strings; YAML interprets unquoted val

**Problem:** The server builds and starts, but crashes when a user tries to sign in with GitHub. The error cites a missing table such as `serverpod_auth_idp_github_account`.

**Cause:** `serverpod generate` has been run, but the accompanying database migration was not created or applied.
**Cause:** The database migration that creates the provider's tables was never created or applied.

**Resolution:** Create and apply the migration:

```bash
serverpod generate
serverpod create-migration
dart run bin/main.dart --apply-migrations
```
**Resolution:** In the running `serverpod start` terminal, press **M** to create the migration, then **A** to apply it.

## Android sign-in opens GitHub but the callback never fires

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -182,7 +182,7 @@ class MicrosoftIdpEndpoint extends MicrosoftIdpBaseEndpoint {}

### Generate and migrate

Finally, run `serverpod generate` to generate the client code and create a migration to initialize the database for the provider. More detailed instructions can be found in the general [identity providers setup section](../../setup#identity-providers-configuration).
Finally, start the server with `serverpod start` to generate the client code, then create and apply the migration that initializes the database for the provider (in the `serverpod start` terminal, press **M**, then **A**). More detailed instructions can be found in the general [identity providers setup section](../../setup#identity-providers-configuration).

### Basic configuration options

Expand Down
Loading
Loading