It is possible to authenticate and verify, in a second step, the user who is trying to log in. This is known as Two Factor Authentication (2FA), and 2 Step Verification (2SV).
2FA is commonly used when a password or username is entered, and a second validation step is performed by sending an email or SMS as a way to mitigate brute force attacks.
The second factor authentication can only be One Time Password (OTP) verification, including OTP Custom.
To improve security, the user is required to validate twice before accessing. The first step involves entering a username and password, and the second step performs another validation (like the one mentioned before).
In both cases, in a web or mobile app, when the user has this functionality enabled, every time the user logs in has to follow two steps. This means that while logging in, the user has to successfully pass the second factor to keep logged on the app.
Two Factor Authentication can be configured with the following authentication types: OTP, Local, Custom, WebService, GAMRemoteRest.
In this example, Local Authentication is set as the first factor authentication, and OTP is the second factor authentication.
- Step 1: Add the second factor authentication by choosing OTP. Read Steps to set up OTP to fully understand OTP configuration.
In order to use OTP only as second factor authentication, the checkbox "Use For First Factor Authentication?" must be kept unchecked.
- Step 2: In this example, the first factor authentication is going to be Local. Local is the default authentication in GAM, so you have to edit it.
In the edit form of Local Authentication, the check box "Enable Two Factor Authentication?" has to be selected.
In the "Authentication Type Name" Combo Box, choose the OTP that was added in step 1.
The checkbox "Force 2FA for all users?" is selected. This option sets 2FA for all the users in the application.
By selecting the checkbox "Force 2FA for all users?" in the first factor authentication, every user of the app is set with the "Enable two factor authentication?" checkbox selected.
If you do not select "Force 2FA for all users?", you must select the "Enable two factor authentication?" checkbox in the settings of every user that you want to use 2FA.
Besides the configuration shown above, 2FA properties can also be set in the GeneXus IDE. For this, you will have to refer to the properties by the following names:
- &AuthenticationTypeLocal.TwoFactorAuthentication.Enable
- &AuthenticationTypeLocal.TwoFactorAuthentication.AuthenticationTypeName
- &AuthenticationTypeLocal.TwoFactorAuthentication.FirstAuthenticationFactorExpiration (seconds): Numeric 9. Default = 900.
- &AuthenticationTypeLocal.TwoFactorAuthentication.ForceForAllUsers: If set to false, every user can enable this.
- &UserEnableTwoFactorAuth = Boolean (allows null)
Read this article: Email server configuration with GAM to learn more about it.
How to use 2FA through REST Services
1. Access Token
The Endpoint is: https://<domain>/<virtual_directory>/oauth/gam/v2.0/access_token
FIRST POST
Body:
client_id: Client ID of the application, required.
client_secret: Client Secret of the application, required.
grant_type=password: It's required.
scope: Scope of the user account you wish to access. It's only required when "&GAMApplication.ClientAuthenticationRequestMustIncludeUserScopes" it's True.
username: Username of the user with 2FA enabled, required.
password: Password of the User to be authenticated. required.
authentication_type_name: Name of the authentication type with 2FA configured at the server, required.
POSTMAN Example:
After this request you will receive an email with the code you will use in the Second Post.
SECOND POST
client_id: Client ID of the application, required.
client_secret: Client Secret of the application, required.
grant_type=password: It's required.
scope: Scope of the user account you wish to access. It's only required when "&GAMApplication.ClientAuthenticationRequestMustIncludeUserScopes" it's True.
password: OTP Code requested in the FIRST POST, required.
username:Username of the user with 2FA enabled, required.
authentication_type_name: Name of the authentication type with 2FA configured at the server, required.
use_2fa=true:It's required.
otp_step=2: It's required.
POSTMAN Example:
2. User Info
The Endpoint is: https://<domain>/<virtual_directory>/oauth/gam/v2.0/userinfo
GET
Headers
Content-Type: Type of content that will be returned. Use application/x-www-form-urlencoded, required.
Authorization: access_token obtained in the SECOND POST, required.
{
"guid": "4c921af0-6805-4f51-9cfe-4d6cd6821e05",
"username": "juan",
"email": "jperez@genexus.com",
"verified_email": true,
"first_name": "Juan",
"last_name": "Perez",
"external_id": "",
"gender": "M",
"url_image": "",
"url_profile": "",
"phone": "099 888 888",
"address": "",
"city": "",
"state": "",
"post_code": "",
"language": "",
"timezone": "",
}
Response:
Since GeneXus 17 Upgrade 5