Authentication

In Serverpod, authentication is managed through the serverpod_auth module. It makes it easy to authenticate users through email or 3rd parties. Currently supported is Signing in with email, Google, and Apple. Future versions of the authentication module will include more options. Using this module requires some setup with Google and Apple for things to work.

The authentication module also handles basic user information, such as user names and profile pictures.

Installing the module

To install the auth module in your Serverpod server, you need to include it in your server's pubspec.yaml. The serverpod_auth module is released with the same version numbers as serverpod itself, so make sure to use a matching version number in your pubspec file.

dependencies:
  serverpod_auth_server: ^0.9.5

In addition, you will need to add the module to the config/generator.yaml file.

modules:
  serverpod_auth:
    nickname: auth

This will tell Serverpod to include the module when it generates the client and server code. The nickname defines which name the client is using to reference the module.

To finalize the installation you will need to run pub get and serverpod generate from your server's directory.

flutter pub get
serverpod generate

Setting up Sign in with Google

To set up Sign in with Google, you will need a Google account for your organization and setup a new project. For the project you need to setup Credentials and Oauth consent screen. You will need a OAuth 2.0 Client id of type Web application.

1. Follow the instructions in the google_sign_in plug-in for iOS and Android.
   • For iOS, make sure that you obtain the GoogleService-Info.plist and add it to your Xcode project.
   • For Android, there are other setup steps you need to take.
2. In Google cloud, you need to do some additional setup.
   • Activate the People API on your project.
   • Set up the OAuth consent screen. You will need to add the ../auth/userinfo.email and ../auth/userinfo.profile scopes. You can also setup additional scopes and access them through Google's APIs on the client or server side.
3. Finally, you need to set up the Google client secret so your server can authenticate the user with Google. In GCP's APIs & Services, select the Credentials tab. Download the json from your OAuth 2.0 Client IDs. Rename it to google_client_secret.json and place it in the config directory of your server.

Setting up Sign in with Apple

To configure Sign in with Apple, you will need an Apple developer account. Follow the instructions in sign_in_with_apple.

Note that Sign in with Apple may not work on some versions of the Simulator (iOS 13.5 works). This issue doesn't affect real devices.

Setting up Sign in with Firebase

Serverpod uses FlutterFire UI to handle authentication through Firebase. It allows you to add social sign-in types that Serverpod doesn't directly support.

To add authentication with Firebase, you must first install and initialize the Firebase CLI tools and Flutter fire. Follow the instructions here for your Flutter project. In the Firebase console, configure the different social sign-ins you plan to use. Then pass your provider configurations to either the signInWithFirebase method or the SignInWithFirebaseButton of the serverpod_auth_firebase_flutter package.

Server-side, you need to create a set of authentication keys in the Firebase console, download the JSON file, rename it to firebase_service_account_key.json and place it in the config folder.

warning

Serverpod automatically merges accounts that are using the same email addresses, so make sure only to allow sign-ins where the email has been verified.

Add sign-in buttons in your code

First, you need to add dependencies to your app's pubspec.yaml file for the methods of signing in that you want to support. Make sure to use the same version numbers as for serverpod itself.

dependencies:
  flutter:
    sdk: flutter
  example_client:
    path: ../example_client
  serverpod_auth_google_flutter: ^0.9.5
  serverpod_auth_apple_flutter: ^0.9.5

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.

void main() async {
  // Need to call this as we are using Flutter bindings before runApp is called.
  WidgetsFlutterBinding.ensureInitialized();

  // Sets up a singleton client object that can be used to talk to the server
  // from anywhere in our app. The client is generated from your server code.
  // 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://localhost:8080/',
    authenticationKeyManager: FlutterAuthenticationKeyManager(),
  );

  // 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
  // about the user.
  sessionManager = SessionManager(
    caller: client.modules.auth,
  );
  await sessionManager.initialize();

  runApp(MyApp());
}

Now, you can simply add the sign-in buttons to your code.

SignInWithGoogleButton(
  caller: client.modules.auth,
  onSignedIn: () { ... handle sign in here ... },
  onFailure: () { ... handle fail to sign in here ... },
)

This is a complete example of a sign-in dialog: sign_in_dialog.dart.

Displaying or editing user images

The module has built-in methods for handling a user's basic settings, including uploading new profile pictures.

To display a user's profile picture, use the CircularUserImage widget and pass a UserInfo retrieved from the SessionManager.

To edit a user profile image, use the UserImageButton widget. It will automatically fetch the signed-in user's profile picture and communicate with the server.

Full example code

Check out the Serverpod example for a complete example of how to wire everything up.

info

Currently, sign in with Google, Apple, and email is supported, if you write another authentication module please consider contributing your code.