Login web application

The login application (login app) is a central piece of Sphinx, since it's used whenever a user needs to perform a login operation.

The login app provides web-based user interface for several steps in the login process, like asking for the account identifier (e-mail, phone number, username), a password, allowing for user self-registration (sign-up), e-mail/phone number confirmation, forgot password workflow, among other operations.

Here are some of the pages/operations available in login app

  • Login (ask account identifier then password)
  • Registration (sign-up)
  • Reset password
  • E-mail/phone number confirmation

The behavior and appearance of login app can be changed in many ways and we will cover it in this chapter.

Note

The examples show properties being set from code, for better explanation and organization, but most (if not all) of such properties can be set directly in the object inspector.

Login behavior

You can configure login behavior by using TSphinxConfig.​Login​Options property. You can change things like what user information must be confirmed prior to login, and what data can be used to identify an user at login.

Account identifiers

By default, users should use their e-mail to login, i.e., they type the e-mail address to identify their account, and then type the password.

You can change this behavior by using the Use* properties in TSphinxConfig.​Login​Options. For example, when using the following code:

SphinxConfig1.LoginOptions.UsePhoneNumber := True;

Will allow for the user to login with either his/her e-mail or phone number.

login email or phone number

As a second example, the following code:

SphinxConfig1.LoginOptions.UseEmail := False;
SphinxConfig1.LoginOptions.UsePhoneNumber := False;
SphinxConfig1.LoginOptions.UseUserName := True;

Will just ask for username at login.

Fields needing confirmation

The confirmation process consists of generating a token for confirmation, sending the token to the user e-mail (or phone number) and then requiring user to type such token to confirm data. When a token is generated, an event is fired, and it's up to the developer to effectively send an e-mail message to the user inbox, or sending a phone message with the token.

By default, Sphinx requires that user e-mail must be confirmed. Thus, after a user registration, users can't login unless the e-mail is confirmed.

You can disable this, and/or also require that phone number must be confirmed, by using TLoginOptions.​Require​Confirmed​Email and TLoginOptions.​Require​Confirmed​Phone​Number properties. For example, the following code:

SphinxConfig1.LoginOptions.RequireConfirmedEmail := False;
SphinxConfig1.LoginOptions.RequireConfirmedPhoneNumber := True;

Will require phone number to be confirmed, and do not require e-mail to be confirmed anymore.

login phone number confirmation

Forbid self-registration

By default, the login app displays a link for users to create an account themselves in case they don't have one. It's displayed in the first page where users should type their account identifier, with the text "Don't have an account? Register now". You can disable self-registration and hiding such link by setting the following property.

SphinxConfig1.LoginOptions.ForbidSelfRegistration := True;

Two-factor authentication setup

Users can setup two-factor authenticaction directly from the login application. When you explicitly require 2fa for all users (or an specific user), they will not be able to login until they enable it.

After the user types the account identifier and correct password, if 2fa is required for him/her, a page will be displayed providing the QR Code to be read in the authenticator app (e.g., Google Authenticator or similar), and the code generated by the app. After user provides the correct code, 2fa will be enabled for the account and 2fa authentication code will be required for future logins.

login 2fa qrcode

User registration behavior

There are several things you can configure to fine-tune the user registration behavior, like what fields are required and unique. This is mostly configured using TSphinxConfig.​User​Options property.

Required fields

By default, users need to provide their e-mail address, and it must be unique (no other registered user can have the same address). You can specify more fields to be required, for example:

SphinxConfig1.UserOptions.RequireUserName := True;
SphinxConfig1.UserOptions.RequirePhoneNumber := True;

Unique fields

When you do that, the registration page will automatically ask for both fields during registration.

You can also specify that some fields must unique, like phone number:

SphinxConfig1.UserOptions.RequireUniquePhoneNumber := True;

Then no new users will be able to provide a phone number that is already associated to another user. User names are always required to be unique, you can't disable that.

login registration errors

Visual customization

You can completely customize the look and feel of the login app. When the browser redirects to the login page, it loads several additional files that used by the page, like 3rd party JavaScript files (jquery, for example), CSS files and also image files (the logo displayed).

You can replace any of those files with your own one. You achieve this by setting the TUIOptions.LoginAppFolder property to a local folder in your disk, at your choice:

  SphinxConfig1.UIOptions.LoginAppFolder := 'C:\SphinxLoginApp';

Once you do that, when Sphinx server is providing the files for the login app, it will first check if such file is present in such folder. If yes, it will use it. If not, it will provide the default, built-in file.

The files might need to be located in subfolders, depending on the URL being requested. All files must be relative to the base URL <server>/oauth/login/.

For example, suppose your Sphinx base URL server is http://localhost:2001/tms/sphinx. When the system navigates to the login web application, you can inspect your browser requests to see the additional files it will load, and you will see, for example, the the logo image is loaded from:

http://localhost:2001/tms/sphinx/oauth/login/img/logo.png

As you can see, the path relative to <server>/oauth/login/ is simply img/logo.png. That means that to replace the logo image by your own, you should create a subfolder named img inside the folder C:\SphinxLoginApp and then add a file named logo.png there.

Replacing the logo image

In summary, if you have set TUIOptions.​Login​AppFolder to C:\SphinxLoginApp, then to replace the logo image just create a PNG file at C:\SphinxLoginApp\img\logo.png with the image you want.

Changing style

The login web app loads an empty CSS file from css/custom.css. It's loaded after the login.css which contains the default styling, thus any CSS directive you add to that file will override the default one.

Thus, if you have set TUIOptions.​Login​AppFolder to C:\SphinxLoginApp, you fully customize the login app style by creating a CSS file at C:\SphinxLoginApp\css\custom.css with the CSS directives you want. You can of course inspect the existing login app elements in the browser to see ids and classes of existing tags to customize.

This is an small example of the content of custom.css.

body.my-login-page {
    background-color: #d3e5f7;
    font-family: Verdana, Geneva, Tahoma, sans-serif;
}

#divLogo img {
    height: 60px;
}

And how it affects the page, with a new logo.

login custom