Login UX Component
Description
An interface for adding login functionality to an application that has the security framework enabled. Includes built-in support for reset password, account creation, two-factor authentication, and persistent login.
Discussion
The Login UX is a newer component added in the release of Alpha Anywhere 4.6.3.2 and is the recommended Login component to use. The Login UX has numerous advantages over the Legacy Login component:
- The Login UX is fully customizable
- The Login UX supports two-factor authentication
- The Login UX includes built-in support for password reset and new account creation
- The Login UX includes built-in support for two different after login behaviors - redirect to a target page, or set focus to a Panel Card that represents the starting point of your application
- The Login UX includes built-in support for 'persistent login' -- the user will be automatically logged in if they have previously logged in provided the login has not expired (you can customize the persistent login duration)
Creating a Login UX
To create a new Login UX, on the Web Projects Control Panel with Web Components selected in the left-hand list, click New. Select Web Component and click Next. Then, select Login and click Next.
If you are running the full Alpha Anywhere Development Environment, you'll be asked what type of Login component to create. Click UX - Create Login Component Using a UX Component to create a Login UX.
If you are using Alpha Anywhere Community Edition, you can only create a Login UX component.
Alpha Anywhere will prompt you for the following information before creating the Login UX:
- The type of Login Component to create. Select *[ui:UI -
- The Login Component Style.
- The name of the Component.
Two layouts are available for the Login UX: Image on Left and Image Behind. Both of these layouts are shown in the images below.
After selecting the layout and specifying a name for the component, the Login UX will be generated and opened in the UX Builder.
The Login component contains several Panel, depending on the type of layout chosen:
- Panel
- Description
- PANEL_LOGIN
This panel contains all of the Login controls.
- PANELCARD_APPLICATION
If the After login behavior is set to FocusPanelCard, the PANELCARD_APPLICATION is Panel shown. Here is where you can place the controls for your application.
- PANEL_IMAGE
If you chose the layout with Image on Left, the PANEL_IMAGE is the Panel that displays the image.
How to Change the Image
If you want to change the image that is used in the sample components, follow these steps:
Image on Left
Select the PANEL_IMAGE Panel card.
Change the image name in the Image name property.
PANEL_IMAGE Panel Image name propertyTo change the position of the image, select the PanelLayout that contains the PANEL_IMAGE and change the Layout flow direction property. For example, to put the image on the right, change the flow direction to RTL (right-to-left).
The Panel Layout flow direction property
Image Behind
Select the PANEL_LOGIN Panel Card
Set the new image name in the Image name property.
PANEL_LOGIN Panel Image name property
Configuring the Login UX
The Login settings found in the UX Properties are used to configure the Login UX. Here you can configure the After login behavior, login messages, log out behavior, password reset, account creation, and more.
- Login Property
- Description
- Persistent login
If checked, enables persistent login. Persistent login keeps the user logged in for an extended period of time, even if they close the app/browser. The Persistent login duration can be configured with Login duration (seconds).
- After login behavior
Defines what happens after the user successfully logs in. By default, the After login behavior is set to "RedirectToTargetPage". Other options include "FocusPanelCard", which is configured to give focus to the PANELCARD_APPLICATION panel, and "Nothing".
- Customize login failure messages
This setting is used to customize the various login failure messages. You can use text dictionary or language tags to add support for multiple languages. Login failure messages include:
MsgFailed=Login Information Incorrect MsgIncomplete=Required data is missing MsgLockedOut=Try Again Later MsgNotSupported=Option is Not Supported MsgPasswordExpired=Password has Expired MsgPasswordFormatError=Invalid Data Supplied MsgSecurityNotEnabled=Security is Not Enabled MsgUnknownError=Invalid Data Supplied MsgUserIdFormatError=Invalid Data Supplied
- Logout does a full page reload
If checked, the .a5w page containing the Login UX is reloaded. If you've configured the Login UX to FocusPanelCard, doing a full page reload will clear out any existing data or loaded components that the user should no longer have access because they have logged out.
- Allow password reset
Modern web applications typically never allow password recovery. However, if a user has forgotten their password, they do allow password reset. If you check the Allow password reset property, the Login UX will display the HYPERLINK_FORGOTPASSWORD link control to reset the user's password. The default label is "Forgot Password?". You can customize the label by changing the Hyperlink text for the HYPERLINK_FORGOTPASSWORD UX control.
For Allow password reset to work, the reset password control must be named HYPERLINK_FORGOTPASSWORD.
- Allow create account
Allows a user to create a new account. If the web project has enabled the extended user-information table, then when the user created their new account they will be able to set values for the fields in the extended user-information table including whether they want to enable two-factor authentication. See How to Capture Extended User Information when a User Creates a New Account for more info.
The default label for create account is "Create Account". You can customize the label by changing the Hyperlink text for the HYPERLINK_CREATEACCOUNT UX control.
For Allow create account to work, the reset password control must be named HYPERLINK_CREATEACCOUNT.
- Additional features settings
The Additional features settings contains properties for configuring other Login UX features including Password Reset, Password Reset email configuration, New Password configuration, and New Account creation. You can use text dictionary or language tags to add support for multiple languages.
Resetting Passwords
When a UX component is configured with integrated login, you can turn on a feature that allows a user to reset their password. The Password Reset feature requires a valid email address. This email address can either be the User ID or read from the Extended User Information Table.
Understanding Password Reset
When the user clicks the Forgot password? link on the Login dialog, the Login dialog changes to display the following. You can customize the wording on the dialog in the Login Features dialog. The Login Features dialog is opened when you click the smart field for the Additional features settings property in the Login section of the UX Builder.
The user will enter their email address and click the Reset Password button. an email will then be sent to the user's account.
The email will either be sent using your own email account or using an Alpha Software account. You can configure which email account is used to send the email in the Login Features dialog. The Login Features dialog is opened when you click the smart field for the Additional features settings property in the Login section of the UX Builder.
If you chose to use the <System> email account then you cannot set the from address of the email that is sent. The from address will automatically be set to [email protected].
The email that the user receives will contain a link (see image below).
When the user clicks the link the Login dialog is shown as follows:
The user will enter their new password and then click the Reset Password button.
The new password must satisfy the password validation rules specified in the Password validation rules property in the Security Settings dialog. In addition, you can also specify the name of a JavaScript function to validate the password that the user enters. To specify a custom Javascript function for the Password validation function property. This property applies both when the user is changing their password, or creating a new account.
Your JavaScript function should take a single argument, the password that the user entered, and it should return a string with an error message if the password is not valid, or it should return a blank value if the password is valid.
Resetting Passwords Using a Stored Email
The password reset feature is implemented as follows: An email is sent to user requesting the the password reset. In the case where the userid is an email address, the email address where to send the password reset email is known. But in the case where the userid is a value, the email address where to send the password reset email is not known. Therefore, if you have set the userid type to value, then in order to support the password reset feature, your web project must have an extended user-information table. Furthermore, this table must have a field called email and there should be an entry in the table for each user in your application. When the user requests a password reset, they will enter their userid. Alpha Anywhere will then look up this userid value in the extended user information table to find the email address associated with the userid and it will send the password reset email to this email address. If there is no email address found, then the user requesting the password reset will not receive an email, but Alpha Anywhere does not report that there was no associated email found as that would be a hacking vector. (It would allow a hacker to enter random userid values and see which ones generate an error, in effect allowing the hacker to guess userid values).
Handling Mobile
In a Cordova mobile application, password reset operates differently.
At the login screen the user can click the Forgot Password? link to request a password reset. An email will be send to the user and the email will contain a password reset token as shown in the sample below (you can customize the text in this message):
Example Reset Password Token MessageThe UX component will then automatically set focus to to a container that displays controls where the user can enter their password reset token and the new password.
Reset Password FormLogging Password Reset Requests
If you've configured your application to use the [Repository Table], Alpha Anywhere will log an entry in the Repository table when the user resets their password using Forgot Password?. The entry in the table includes the action, date the action was performed, and a description of what the action did.
Creating Accounts
If you have enabled the Allow create account property in the UX Component, the Login dialog will have a Create account link.
When the user clicks the link the Login dialog changes as follows:
The user will enter credentials for their new account and then press the Create Account button.
The new password must satisfy the password validation rules specified in the Password validation rules property in the Security Settings dialog. You can optionally specify a Javascript function to perform additional validation on the password.
If the new account is successfully created, then if the Web Project has specified an extended user-information table, the following screen will be shown:
At a minimum the dialog will allow the user to turn two-factor authentication on and if they turn it on, they will be able to select the two-factor authentication options: Email, SMS or Google Authenticator.
In addition, the dialog can prompt for additional fields in the extended user-information table. See How to Capture Extended User Information when a User Creates a New Account for more details.
How to Capture Extended User Information when a User Creates a New Account
The layout of the dialog shown to capture extended user information is shown in the UX component in the CONTAINER_EXTENDEDUSERINFORMATION container (the container does not have to have this name. It can be named anything you want. The name is defined in the Login Features dialog).
You can add additional controls to this container to capture information for other fields in your extended user information table. For example, say that your extended user information table contains these fields:
FIRSTNAME LASTNAME LANGUAGEPREFERENCE
You could add specially named controls to the CONTAINER_EXTENDEDUSERINFORMATION container to capture this additional information when the user creates a new account. Each control must be named the same as the corresponding field in the extended user information table, but with a prefix of EXTENDED_.
In the above example, you would add controls to the CONTAINER_EXTENDEDUSERINFORMATION container with the following names:
EXTENDED_FIRSTNAME EXTENDED_LASTNAME EXTENDED_LANGUAGEPREFERENCE
Understanding the After login behavior property
If you are using a UX component as your Login component, the After login behavior property determines what happens after the user logs in. This property can be set to RedirectToTargetPage or, FocusPanelCard.
If the property is set to RedirectToTargetPage, the Redirect page property is shown. This is the name of the page that the application should redirect to after user user logs in. The redirect page is any .a5w page in your project. You must explicitly define the redirect page.
For apps published to the Classic server, you can set the redirect page to <Default>. The Classic Server will read the redirect page from the project's Security Settings (see the Redirect page after login property.) <Default> is not supported on IIS or Alpha Cloud.
You can override the redirect page in the UX component's server-side onLogin event by setting the value of the e.url property.
In the case where the After login behavior is set to FocusPanelCard, you can overwrite the target Panel by adding code to the client-side AfterLogin event (e.g. {dialog.object}.panelSetActive('target panel') )
If this property is set to FocusPanelCard then after login, the UX will set focus to the specified Panel Card in the component. This option is typically used in Cordova mobile applications in conjunction with the Persistent login feature where there may be no internet connection when the application is launched, so redirecting to another page is not possible.
How Persistent Login Works
If you turn on the Has Integrated login functionality property for the UX you can specify that once the user logs in the login should be 'persistent' (by checking the Persistent login property). If persistent login is turned on then when the user loads the login component again (even after their session has expired, which would normally log them out), the user will be automatically logged back in.
You can specify the duration of the persistent login. If more time has passed than the specified duration, then when the user loads the login component again (after their session has expired), they will no longer be automatically logged in and they will have to log in again.
Videos
Using a UX Component as your Login Dialog
When you enable the Security Framework for your project you will need a login dialog where users will log into your application. A UX component can be used as the Login component and can be configured to allow password reset and new account creation.
In this video we show how to use a UX component as your Login dialog.
Reset Password
A common requirement in any Security Framework is the ability for the user to reset their password if they have forgotten it. The typical pattern for this is to send an email to the user. The email has a link that the user can click to bring up a dialog where they can change their password.
In this video we show how this is done.
Create new account
A common requirement in any Security Framework is the ability for a user to create a new account.
In this video we show how the user can create a new account.
In addition, if the Web Project has defined an Extended User-information table, then at the same time that the user creates their new account, they can choose to enable two-factor authentication.
In this video we show how this is done.
After Login Behavior
After the user has logged into your application using a UX component, configured as a Login dialog, the "after login behavior" can either redirect the user to another page in your application, or to another Panel in the UX component.
In this video we show how the "after login behavior" is configured.
Persistent Login
A common requirement when building an application with the Security Framework is to enable 'persistent login'. With 'persistent login' a user will not need to log into the app again after they have successfully logged in once.
In this video we show how 'persistent login' is enabled.
Password reset when userid is a value (not an email address)
The password reset feature can be used when the userid in the security framework is a value (rather than an email address).
This video shows how this is done and how the extended user-information table must be configured.
Using the password reset feature in a Cordova mobile application
The password reset feature can be used in Cordova applications running on mobile devices. The behavior of the component is slightly different than when running in a browser.
In this video we show how password reset work in a Cordova application.
Login using Google
When you configure a UX component as a Login Component you can enable Login with Google to allow users to login using the Google credentials.
Webinar: Intro to The New Alpha Anywhere Security Genie
Dion McCormick presents an introduction to Alpha Anywhere's new Security Genie.