Skip to main content
Version: Current

Access control - authentication overview

There are many different ways for your application to perform authentication. Each method requires the implementation of an 'Authenticator'. The authenticators offered by the Genesis low-code platform are:

SSO Token authentication covers both SAML and OIDC

Some of these techniques support Multi-factor Authentication (MFA) to bring additional security.

Each of these requires its own configuration settings in the application's auth-preferences.kts file, which is created by the build process. To change the default auth-preferences.kts, create the details in a new auth-preferences.kts file and replace the existing file in:

app-name/server/app-name-app/build/genesis-home/auth/scripts/auth-preferences.kts

Authentication workflow​

Regardless of which authentication method is used, the process for logging in remains the same.

  1. The client (either a Genesis UI or an API client) sends a request to the EVENT_LOGIN_AUTH endpoint.

    The body of this request contains different fields depending on the target authentication mechanism. For example, the field SSO_TOKEN is only valid for SAML and OIDC authenticators, whereas USERNAME and PASSWORD must be provided if using GenesisPassword or LDAP.

  2. Each authenticator is tried in turn, and returns one of three possible responses, Succcess, Failure or Incompatible.

  3. On the first success received, a USER_SESSION record is created; a SESSION_AUTH_TOKEN and REFRESH_AUTH_TOKEN are issued and returned on the EVENT_LOGIN_AUTH_ACK message.

  4. If all configured authenticators return a Failure or Incompatible, then a NACK message will be sent to the client with an error.

The session token must be included on all future requests sent from the client in this session.

The refresh token is a one-time use to create a new session, without having to re-enter credentials.

If the client is set up for MFA, and the second factor verification stage fails, a short-lived temporary session will be created so that first factor credentials do not have to be re-entered.

Username and password authentication​

Username and password authentication allow users to log in directly to your application. You must choose one of the solutions provided in order control this process.

To specify which one to use, just edit the application's auth-preferences.kts file and call any of the functions exposed inside the 'authentication' block to register an authenticator instance.

The differences between the solutions associated with each value are detailed below.

Genesis Password​

Genesis Password authentication uses internally stored hashed credentials to authenticate users. It checks user credentials against an internal table. This provides the following features:

  • User accounts can be locked.
  • Passwords can be set to expire.
  • Passwords can be required to conform to a configurable standard.
  • Users can reset or change their password (assuming they can log in first).
security {
    authentication {
        genesisPassword {
            validation {
                passwordSalt = ""
                passwordStrength {
                    minimumLength = null
                    maximumLength = 256
                    minDigits = null
                    maxRepeatCharacters = null
                    minUppercaseCharacters = null
                    minLowercaseCharacters = null
                    minNonAlphaNumericCharacters = null
                    restrictWhiteSpace = true
                    restrictAlphaSequences = false
                    restrictQWERTY = true
                    restrictNumericalSequences = true
                    illegalCharacters = ""
                    historicalCheck = null
                    dictionaryWordSize = null
                    restrictDictionarySubstring = false
                    restrictPassword = false
                    restrictUserName = false
                    repeatCharacterRestrictSize = null
                    passwordExpiryDays = null
                    passwordExpiryNotificationDays = null
                }
            }

            retry {
                maxAttempts = 3
                waitTimeMins = 5
            }
        }
	}
}

LDAP​

LDAP authentication uses its namesake protocol to authenticate users.

LDAP authentication relies on an external party that cannot be operated from your application. So, by setting LDAP, you lose control of the internal authentication functionality. As a direct consequence, requests to change or reset passwords won't be accepted.

For LDAP authentication, a username must exist inside the internal records of the application. To do this, create a user entry inside the USER table for every LDAP user of the application. There is no password checking between this login and the application's internal records; authentication will rely solely on LDAP.

To set up LDAP authentication, a connection to an LDAP server must be configured in the auth-preferences.kts file.

For more information on configuring LDAP authentication, see Username and password authentication.

The example below shows LDAP authentication specified, with userIdType set to cn for the search for the username.

security {
    authentication {
		ldap {
		    connection {
		        url = "localhost"
                port = 389
                searchBases {
				    searchBase {
                        entry("ou=People,dc=example,dc=com")
			        }
                }
                bindDn = "CN=DTADevBindUser,ou=People,dc=example,dc=com"
                bindPassword = "password123"
                userIdType = "cn"
			}
		}
    }
}

SSO authentication​

SSO authentication enables users to use a single set of credentials to access a range of applications, including those built on the Genesis low-code platform. For more information on SSO technology, see the Single-sign on Wikipedia page.

SSO authentication is a more involved process to enable; it requires additional file changes, which are detailed in the following pages:

Using more than one authentication type​

Your application can use two or more authentication types concurrently; the use of one does not mandate or prevent the use of the other. Each configured authenticator will be tried in turn to see if a logon message can be successfully authenticated.