GAM - One Time Password for mobile

In this article, you will find the steps to use One Time Password (OTP) authentication in a mobile application:

First, you must configure an OTP Authentication type.

After completing the configuration for OTP authentication, you need to consider the following:

OTP runs two core events. The first event validates the user's existence, and the second event verifies the user code. All the Events described below are in the same Panel.

Step 1: Verify user event

The logic inside this event will include a call to a method of the Actions external object named LoginExternal.

The first parameter is based on the GAMAuthenticationTypes domain and its value should be OTP.

The &password parameter is ignored in this case.

The &LoginExternalAdditionalParameters has an AuthenticationTypeName property where you can set the name of the Authentication Type. This is because more than one OTP Authentication Type can be defined in the Repository.

Also, the &LoginExternalAdditionalParameters has the OTPStep which has the value "1" if it is validating the user, and "2" if it is validating the OTP code that the user inserted.

If the LoginExternal method returns TRUE, the event GeneXusSecurity.GAMLoginEvents.OTPAuthenticationRequested is triggered.

This event calls the "DisplayOTPStep2" subroutine to change the Panel inputs, so it is prepared to read the OTP code that the user will insert. In addition, this event also warns the user that an authentication code was sent to them.

Event 'BtnNext'
    Composite
        GeneXus.Common.UI.Progress.ShowWithTitle("Connecting...")
        &LoginExternalAdditionalParameters = new()
        &LoginExternalAdditionalParameters.AuthenticationTypeName    = !"OTP-FFA"
        &LoginExternalAdditionalParameters.OTPStep                    = 1
        &isLoginOK = GeneXus.SD.Actions.LoginExternal(GAMAuthenticationTypes.OTP, &UserName, &Password, &LoginExternalAdditionalParameters)
        GeneXus.Common.UI.Progress.Hide()
        If &isLoginOK
            //OK
        Else
            GAMSDGetLastErrors(&Messages)
        Endif
    EndComposite
Endevent


Event GeneXusSecurity.GAMLoginEvents.OTPAuthenticationRequested
    Msg("An email was sent with your access code...")
    
    Do "DisplayOTPStep2"
    &LoginOTPStep = 2
    GeneXus.Client.ClientStorage.Set(!'LoginOTP-Step', &LoginOTPStep.ToString())
      GeneXus.Client.ClientStorage.Set(!'LoginOTP-UserName', &UserName.Trim())
EndEvent

Step 2: Validate code event

In this event, the external object method LoginExternal is used to validate the code given by the user. Therefore, the &LoginExternalAdditionalParameters.OTPStep property is defined as "2." 

Besides, the &password parameter is changed to &OTPCode in the LoginExternal method.

Event 'BtnValidCode'
    Composite
        GeneXus.Common.UI.Progress.ShowWithTitle("Connecting...")
        &LoginExternalAdditionalParameters = new()
        &LoginExternalAdditionalParameters.AuthenticationTypeName         = !"OTP-FFA"
        &LoginExternalAdditionalParameters.OTPStep                        = 2
        GeneXus.SD.Actions.LoginExternal(GAMAuthenticationTypes.OTP, &UserName, &OTPCode, &LoginExternalAdditionalParameters)
        GeneXus.Common.UI.Progress.Hide()
        Do "SetOTPStep1"
        Return
    EndComposite
Endevent

Event start

In cases where the app is running in the background, it is important to keep the state of the login process. This means that when users have been verified in the first verification step and received a code, they must be able to open another app to read the code without losing the state of the OTP step that had already been done.

To solve this problem, the "ClientStorage" external object is used. 

Event ClientStart
    &UserName.Enabled     = True
    BtnNext.Visible       = True
    TblCode.Visible       = False
    &LoginOTPStep.FromString(GeneXus.Client.ClientStorage.Get(!'LoginOTP-Step'))
    If &LoginOTPStep = 2
        Do "DisplayOTPStep2"
        &UserName = GeneXus.Client.ClientStorage.Get(!'LoginOTP-UserName')
    Endif
Endevent

Go Back event

This event calls the subroutine "SetOTPStep1" to cancel the OTP login process.

Event 'BtnBack'
    Composite
        Do "SetOTPStep1"
        Return
    EndComposite
Endevent

Subroutines

The above events call two different subroutines. 

The "DisplayOTPStep2" subroutine makes changes in the elements of the Panel so that the user can interact with either the username input or the OTPcode input. 

Sub "DisplayOTPStep2"
    &UserName.Enabled      = False
    BtnNext.Visible        = False
    TblCode.Visible        = True
EndSub

The "SetOTPStep1" subroutine reset the steps of the OTP login process, leaving the Panel by default.

Sub "SetOTPStep1"
    &LoginOTPStep = 1
    GeneXus.Client.ClientStorage.Set(!'LoginOTP-Step', &LoginOTPStep.ToString())
    GeneXus.Client.ClientStorage.Set(!'LoginOTP-UserName', "")
EndSub

Availability

This feature is available since GeneXus 17 Upgrade 9.

See Also

GAM - One Time Password (OTP)
GAM - Time Based One Time Password (TOTP)
GAM - Time Based One Time Password for mobile
GAM - Two factor Authentication for mobile