In this blog post we will cover how to customize the "login web app" in TMS Sphinx.

About TMS Sphinx

TMS Sphinx is a robust Delphi framework that enables developers to build Single Sign-On (SSO) servers, offering an alternative to solutions like Auth0 and Duende Server, and, of course, your own home-made solution. Its key advantage lies in granting developers full control and flexibility, thanks to the provision of full source code. TMS Sphinx allows for royalty-free server deployment, supporting unlimited users and requests without additional costs. This feature makes Sphinx particularly attractive for projects requiring customized authentication flows and scalability without the burden of licensing fees. In addition to that, being written in Delphi, you can fully customize it and easily integrate with your existing applications.

The login web application

In the heart of TMS Sphinx platform lies the login web application (or simply "login app") —a pivotal tool ensuring users a seamless sign-in journey. This application offers a web-based interface catering to various login-related tasks, including:

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

Of course, customizability in a login web application is vital because it allows for tailoring the user experience to match the specific branding and operational requirements of a business. It ensures the application can adapt to various authentication workflows, user interfaces, and so on.

TMS Sphinx offer several ways to customize the login web app look-and-feel and behavior.

Customizing login behavior

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;

This will allow for the user to log in with either his/her e-mail 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.

Confirmation workflow

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 a 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's inbox, or send a phone message with the token.

By default, Sphinx requires that user's 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;

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

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;

Customizing 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.

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;

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 with another user. User names are always required to be unique; you can't disable that.

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 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. This is achieved 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 the Sphinx server is providing the files for the login app, it will first check if such a file is present in the specified folder. If yes, it uses it. If not, it provides the default, built-in file.

Files may 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.

Localizing the login app

Changing the login page language and server messages should be as simple as setting the UIOptions.DefaultLanguage property in the TSphinxConfig component (from code or at design-time in object inspector):

  SphinxConfig1.UIOptions.DefaultLanguage := 'pt-br';

But, of course, an existing translation should be available for the chosen language. Here are the current available translations:

• English (default)
• de-de: German
• fr-fr: French
• it-it: Italian
• nl-be: Dutch (Belgium)
• nl-nl: Dutch (Netherlands)
• pt-br: Brazilian Portuguese
• sv-se: Swedish

Registration page in German:

Registration page in French:

What if your language is not available?

If TMS Sphinx still doesn't support the language you want to use, you can translate the messages yourself, and if you want, you can send them to us to include in the official distribution - actually most of the supported TMS Sphinx languages were contributions from users, thank you all for that!

The TMS Sphinx documentation has a specific topic describing exactly how you can translate the messages yourself. Just follow the instructions!

Try TMS Sphinx now!

Ready to experience the full potential of Sphinx for your authentication needs? Get started with our trial version now and unlock the power of customizable, royalty-free SSO solutions! 

TMS Sphinx Web Page

TMS Sphinx Documentation

Download TMS Sphinx trial now