Working with users

The authentication module provides convenient ways to work with your authenticated users and their related profile data.

Authenticated users

All authenticated users have an authentication identifier, that uniquely identifies them across the server. This can be retrieved from the session object as a String through the userIdentifier property or as a UuidValue from the authUserId extension provided by the authentication module.

var userIdString = session.authenticated?.userIdentifier;
// requires `import 'package:serverpod_auth_idp_server/serverpod_auth_idp_server.dart';`
var userIdUuidValue = session.authenticated?.authUserId;

Further operations on the authenticated user can be performed using the AuthUsers class which is provide by the AuthServices instance.

await AuthServices.instance.authUsers.delete(session, userIdUuidValue);

For the full list of operations, see the AuthUsers class documentation.

Blocking users

You can block users to prevent them from signing in to your application. When a blocked user attempts to authenticate, an AuthUserBlockedException will be thrown, and the authentication will fail.

Blocking or unblocking a user

To block/unblock a user, use the update method of the AuthUsers class:

await AuthServices.instance.authUsers.update(
  session,
  authUserId: authUserId,
  blocked: true, // or false to unblock
);

Users can also be created with the blocked status set from the start:

await AuthServices.instance.authUsers.create(
  session,
  blocked: true,
);

note

When a user is blocked, they will not be able to sign in until they are unblocked. However, blocking a user does not automatically revoke their existing sessions. Be sure to revoke existing sessions for a complete block operation. See Revoking tokens for more details.

User profiles

By default, all authenticated users have a UserProfile object that contains information about the signed-in user. To access the UserProfile object, you can use the userProfile extension on the AuthenticationInfo object.

var userProfile = await session.authenticated?.userProfile(session);

The UserProfile contains a basic set of information about the user, such as their full name, email address, and profile picture.

This information is automatically populated when the user signs in. Based on the authentication method used, different data may be available.

It's a common task to read or update user information on your server. The UserProfiles class provides many convenient methods for working with user profiles and is accessible through the AuthServices instance.

await AuthServices.instance.userProfiles.changeFullName(session, authUserId, 'my name');

For the full list of operations, see the UserProfiles class documentation.

Setting a default user image

When logging in from some providers, the user image is automatically fetched and set as the user's profile picture - such as with Google Sign In. However, when an image is not found or the provider does not expose the picture, it is possible to set a default user image using the UserProfileConfig object.

  pod.initializeAuthServices(
    userProfileConfig: UserProfileConfig(
      // NOTE: The `userImageGenerator` parameter is optional and defaults to
      // the value below - which generates Gmail-style images. You can change
      // this parameter to generate any kind of placeholder image. The function
      // will be called when invoking the `setDefaultUserImage` method.
      userImageGenerator: defaultUserImageGenerator,
      onAfterUserProfileCreated:
          (session, userProfile, {required transaction}) async {
            await AuthServices.instance.userProfiles.setDefaultUserImage(
              session,
              userProfile.authUserId,
              transaction: transaction,
            );
          },
    ),
  ...
  );

Attaching additional information

The recommended way to attach additional information to an authenticated user is to use a relation in the Database. This makes it easy to query the data later based on the user's authentication identifier.

class: MyDomainData
table: my_domain_data
fields:
  ### The [AuthUser] this profile belongs to
  authUser: module:serverpod_auth_core:AuthUser?, relation(onDelete=Cascade)
  additionalInfo: String

indexes:
  auth_user_id_unique_idx:
    fields: authUserId
    unique: true

note

Note that the AuthUser model is declared in the serverpod_auth_core module, which is automatically included in your project as a dependency of the serverpod_auth_idp module. If you are not ignoring the generated files in your analysis_options.yaml, you might need to explicitly add the serverpod_auth_core module to your project to prevent depend_on_referenced_packages lint errors. The general recommendation, however, is to ignore linting on generated files:

# analysis_options.yaml
analyzer:
  exclude:
    - lib/src/generated/**

tip

When referencing module classes in your model files, you can use a nickname for the module instead of the full module name. See the modules documentation for more information.

The model above creates a relation to the AuthUser table and ensures that each user can only have one MyDomainData object. The onDelete=Cascade ensures that when the AuthUser is deleted, the MyDomainData object is also deleted.

This makes it easy to query the additional information later based on the user's authId.

final authUserId = session.authenticated?.authUserId;
final additionalInfo = await MyDomainData.db.findFirstRow(
    session,
    where: (t) => t.authUserId.equals(authUserId!),
);