.auth

Authentication Module is responsible for all authentication functionality. Supported authentication mechanisms are:

  • Simple (Username/email & password).

  • Pin (quick login) using username & pin.

  • SMS (OTP) using mobile number & OTP.

Things to know

On change of the session, i.e: user logs in or logs out, sessionStatus, a BehaviorSubject, is updated. For instance:

getFrappeAuthController()
.sessionStatus
.listen((session) => print('Session updated!'));

It is recommended for better support of types by code assistance in IDEs to usegetFrappeAuthController()in order to get the instance of FrappeAuthController instead of renovation.auth which is AuthControllerif the backend is Frappè, for instance.

In this guide we will use Frappé as an example and use getFrappeAuthController()

Methods

.login() ☆

To login using username/email and password. This method returns a SessionStatusInfo object.

On successful authentication, the sessionStatus is updated with the current user.

Input

property

type

required

description

email

String

yes

The email or username of the user

password

String

yes

The password of the user

Output

class

return

AuthController

SessionStatusInfo (abstract)

FrappeAuthController

FrappeSessionStatusInfo

Example

final loginResponse = await getFrappeAuthController().login(
'test@abc.com', 'supercomplexpassword');
if (loginResponse.isSuccess) {
print('Yaay! we are logged in');
}

Possible Errors

Incorrect credentials

HTTP code: 401

type: AuthenticationError

cause: Incorrect Password

suggestion: Enter the correct credentials

Non-existing user

HTTP code: 404

type: NotFoundError

cause: User disabled or missing

suggestion: Enter the correct credentials

.pinLogin() ★

This method is mostly used to quickly login, for instance POS. As with .login(), it returns SessionStatusInfo.

On successful verification, the sessionStatus is updated with the current user.

Input

property

type

required

description

username

String

yes

The username of the user

pin

String

yes

The pin of the user (all digits)

Output

class

return

AuthController

SessionStatusInfo (abstract)

FrappeAuthController

FrappeSessionStatusInfo

Example

final pinLoginResponse =
await getFrappeAuthController().pinLogin('user1', '123456');
if (pinLoginResponse.isSuccess) {
print('Yaay! we are logged in');
}

Possible Errors

Wrong PIN

HTTP code: 401

type: AuthenticationError

cause: Wrong PIN is entered

suggestion: Re-enter the PIN correctly

.sendOTP() ★

To get OTP using mobile number through SMS, this method can be used.

The SMS settings should be configured correctly in the backend before using this method.

This method does not authenticate the user. The next method .verifyOTP() will provide the option to authenticate the user and create/update a session.

Input

property

type

required

description

mobile

String

yes

The mobile number of the user

newOTP

bool

no

Whether to generate a new OTP or reuse the existing one. Defaults to false

Output

SendOTPResponse

Example

final sendOTPResponse =
await getFrappeAuthController().sendOTP('+971000000000', newOTP: true);
if (sendOTPResponse.isSuccess) {
print('SMS was sent to ${sendOTPResponse.data.mobile}');
}

Possible Errors

The errors depends mostly on the SMS provider setup in the backend and would be propagated through this method (API).

.verifyOTP() ★

To be used for verifying the OTP received after invoking .sendOTP().

On successful verification, the SessionStatus is updated with the current user provided the optional param loginToUser is set totrue.

Although this method can potentially change sessionStatus, it return VerifyOTPResponse unlike .login(), for instance.

Input

property

type

required

description

mobileNo

String

yes

The mobile number of the user

otp

String

yes

The OTP received through SMS

loginToUser

bool

yes

Whether to generate a new OTP or reuse the existing one

If loginToUser is set to false, the user is not logged in and SessionStatus is not updated. This can be useful in some applications.

Output

VerifyOTPResponse

Example

final verifyOTPResponse = await getFrappeAuthController()
.verifyOTP('+971000000000', '123456', false);
if (verifyOTPResponse.isSuccess) {
print('User verified as ${verifyOTPResponse.data.mobile}');
}

Possible Errors

Invalid Pin

HTTP code: 401

type: AuthenticationError

cause: Wrong OTP entered

suggestion: Enter correct OTP received by SMS or generate a new OTP

User not found / No Linked User

HTTP code: 404

type: AuthenticationError

cause: User is either not registered or does not have a mobile number

suggestion: Create user or add a mobile number

.checkLogin()

Checks the status of the login and verifies with the backend. By default, it will update sessionStatus.

Input

property

type

required

description

shouldUpdateSession

bool

yes

Whether to update the session held by sessionStatus. Defaults to false

Output

class

type

AuthController

SessionStatusInfo (abstract)

FrappeAuthController

FrappeSessionStatusInfo

Example

final session =
await getFrappeAuthController().checkLogin(shouldUpdateSession: false);
if (session.isSuccess) {
print('Logged In: ${session.data.loggedIn}');
}

.getCurrentUserRoles() ★

Gets the roles of the current user logged in.

If the user is not logged in, the roles of Guest are loaded by default.

Output

List<String>

Example

final userRoles = await getFrappeAuthController().getCurrentUserRoles();
if (userRoles.isSuccess) {
print('Users roles are: ${userRoles.data.toString()}');
}

.logout()

Logs out the user locally followed by ending the session in the backend.

Output

dynamic

Even if the server's response is a failure, the user will need to re-login since the user is logged out in the front-end.

Reference

SessionStatusInfo (Abstract)

property

type

description

loggedIn

bool

Whether the user is logged in

timestamp

number

The timestamp when the sessionStatusInfo was updated

currentUser

String

The current user logged in, if any