Renovation
Search…
.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:
1
getFrappeAuthController()
2
.sessionStatus
3
.listen((session) => print('Session updated!'));
Copied!
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

1
final loginResponse = await getFrappeAuthController().login(
2
'[email protected]', 'supercomplexpassword');
3
4
if (loginResponse.isSuccess) {
5
print('Yaay! we are logged in');
6
}
Copied!

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

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

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

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

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

1
final verifyOTPResponse = await getFrappeAuthController()
2
.verifyOTP('+971000000000', '123456', false);
3
if (verifyOTPResponse.isSuccess) {
4
print('User verified as ${verifyOTPResponse.data.mobile}');
5
}
Copied!

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

1
final session =
2
await getFrappeAuthController().checkLogin(shouldUpdateSession: false);
3
4
if (session.isSuccess) {
5
print('Logged In: ${session.data.loggedIn}');
6
}
Copied!

.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

1
final userRoles = await getFrappeAuthController().getCurrentUserRoles();
2
3
if (userRoles.isSuccess) {
4
print('Users roles are: ${userRoles.data.toString()}');
5
}
Copied!

.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
Last modified 1yr ago