Kitto.Auth.DB

Defines the DB authenticator, an authenticator that uses a custom table on the database to store users and passwords.

TKAuthUser class

User data read from the database. Used internally as a helper class.

property Name: string read FName write FName;

The user name read from the database.

property PasswordHash: string read FPasswordHash write FPasswordHash;

The password hash read from the database.

TKDBAuthenticator class

The DB authenticator uses a custom table in the database to authenticate users. The table has fixed name and structure. To use a different table name or structure, set parameters or create a descendant. The authenticator needs the same auth items as its ancestor TKClassicAuthenticator.

In order for this authenticator to work, it is required that the database contains a table called KITTO_USERS with the following structure:

• USER_NAME String uniquely identifying the user.
• EMAIL_ADDRESS Unique e-mail address for the user. This is optional, and only used by ResetPassword.
• PASSWORD_HASH String containing the MD5 hash of the user's password.
• IS_ACTIVE Set to 0 to disable (ignore) a user. Disabled users will not be able to log in.

When Authenticate is called, the authenticator fetches the user record (if active) and checks the supplied password against the MD5 hash stored there. You can use clear-text passwords instead of MD5 hashes if you set the IsClearPassword parameter to True. You can also override the SQL select statement used to get the user record through the ReadUserCommandText parameter, which allows you to use a different structure without the need to define an inherited authenticator.

Parameters:

• IsClearPassword Set this item to True to signify that the password is stored in clear, and not hashed, in the database. Default False.
• ReadUserCommandText A SQL select statement that selects a single user record, with the fields USER_NAME and PASSWORD_HASH and a single string parameter that will be filled in with the user name. Example: select UNAME as USER_NAME, pwd as PASSWORD_HASH from USERS where ENABLED = 1 and UNAME = :P1 Any additional fields returned by the statement are kept as part of the auth data. Example: select USER_NAME, PASSWORD_HASH, SOMEFIELD from USERS where IS_ACTIVE = 1 and USER_NAME = :P1 The item SOMEFIELD will be available as part of the auth data (and as such, through the authentication-related macros as well) for as long as the user is logged in. The item will be of whatever data type SOMEFIELD is. You can have more than one such items. This technique is useful to apply fixed user-dependent filters to data sets and data partitioning among users, for example.
• IsPassepartoutEnabled Set this item to True to signify that the passepartout password is enabled (that means that a user can authenticate wither with her own password or the passepartout password). If the passepartout password is used to log in, the IsPassepartoutAuthentication Boolean item is set to True into AuthData.
• PassepartoutPassword A password to be used as a passepartout for every user account. Setting this parameter has no effect if IsPassepartoutEnabled is not True. The value of this parameter represents a cleartext or hashed password depending on the value of IsClearPassword.
• AfterAuthenticateCommandText Optional SQL statement that will be executed just after authentication. Supports macros, even authentication-related ones.
• SetPasswordCommandText A SQL update statement that updates the password field of a given user's record. The statement must have two params named USER_NAME (that will be filled with the current user's name) and PASSWORD_HASH (that will be filled with the new password or password hash depending on the state of IsClearPassword). By default, the standard KITTO_USERS table is updated. This statement is executed when the authenticator's Password property is set in code.

function RehydrateAuthData(const AUserName: string;

Refills AAuthData from the KITTO_USERS record (no password check), for an identity a validated JWT already proved but whose session was lost. Returns False when the user is unknown or no longer active — the read filters IS_ACTIVE — so a disabled account's token stops working. See TKAuthenticator.RehydrateAuthData.

function IsPasswordMatching(const ASuppliedPasswordHash: string;

Returns True if ASuppliedPasswordHash matches AStoredPasswordHash. By default this means that they are the same value. A descendant might use different matching rules or disable matching altogether by overriding this method.

procedure ResetPassword(const AParams: TEFNode);

Generates a new random password for the user identified by UserName/EmailAddress in AParams, stores it (flagged as must-change) in the database and returns it via the AParams "Password" node.

procedure QRGenerate(const AParams: TEFNode);

Generates a QR code encoding the OTP shared secret for the user identified in AParams, for use in PIN (TOTP) authentication.

TKDBCryptAuthenticator class

Same Authenticator as TKDBAuthenticator, it only manages hashed passwords using BCrypt algorithm (in BCrypt unit). It requires a field on the custom user table named PASSWORD_HASH at least 60-CHARACTER LONG. It shifts automatically from TKDBAuthenticator's hash method to BCrypt (after the first successful login), without the need to do a password reset.

procedure AfterConstruction;

Marks the authenticator as BCrypt-enabled.

function IsPasswordMatching(const ASuppliedPasswordHash: string;

Returns True if the supplied password matches the stored BCrypt hash; transparently rehashes and upgrades the stored hash on success when its strength (cost) is below the configured threshold.

procedure ResetPassword(const AParams: TEFNode);

Resets the user's password to a new random, BCrypt-hashed value respecting the ValidatePassword rules.