# Objects

*SECURE | Security Control

## Description

The *SECURE object is used to control security within NOMADS/iNomads. It stores and then validates user IDs, passwords and associated security class definitions.

Use these links to access examples provided below:

Example - Get the Current User Name
Example - Logon with User Name and Password
Example - Generate QR Code, Secret, and One-Time Password (TOTP)

## Methods and Properties

The following methods (in alphabetical order) are supported:

Method | Description
AddUser(Userid$,Name$,Classlist$,Password$) | Add user.
CanDo2FA(Userid$) | Checks to see if user can do Two-Factor Authentication. (The CanDo2FA method was added in PxPlus 2023.)
ChgUser(Userid$,Name$,Classlist$,Password$) | Change user.
ChgUserClasses(Userid$,Classlist$) | Change class list.
ChgUserEmail(Userid$,Email$) | Change user's email address. (The ChgUserEmail method was added in PxPlus 2023.)
ChgUserName(Userid$,Name$) | Change user name.
ChgUserPswd(Userid$,Password$) | Change password.
ChkClass(Userid$,Class$) | Return True/False.
ChkClassRights$(Userid$,Classes$) | Returns "", "V", or "F".
ClrClass(Userid$,Class$) | Removes a class.
DelUser(Userid$) | Delete user.
GetClass$(Userid$,Index) | Get class (loop through index).
GetToken$( ) | Returns a token that can be used to pass sign-on for one minute.
Load_TFA( ) | Load Two-Factor Authentication (TFA) values into the Secure object. Only allowed if user has ADMIN privileges. Returns 1 if successful, 0 if failure. (The Load_TFA method was added in PxPlus 2023.)
LogOff( ) | Logoff and drops the Secure object if it was logged on.
LogOn(Userid$,Password_or_Token$) | Logon using password and/or token.
Save_TFA( ) | Encrypt and save Two-Factor Authentication (TFA) values onto user control file. Only allowed if user has ADMIN privileges. Returns 1 if successful, 0 if failure. (The Save_TFA method was added in PxPlus 2023.)
Secret_Code$(User_Email$) | Generates a QR code in the working directory and produces a Base32-encoded secret when user security exists. (The Secret_Code$ method was added in PxPlus 2026.)
SetClass(Userid$,Class$) | Add a single class.
SetUserField(Variable$, Value$) | This function is used to define user variables that will be loaded into %usr.variable$ and made accessible to the application. Where:
Variable$ | Name of the string variable that will be prefixed with "%usr." whose value will be saved and loaded.
Value$ | Contains the value that will be saved and loaded.
This routine will allow values to be saved to the profile information for the current user. A maximum of 1K worth of data values may be saved. Example: %objSecure'SetUserField("CellPhone","4165551212") This would result in the value %usr.CellPhone$ being set to "4165551212" on subsequent sessions for the current user. (The SetUserField method was added in PxPlus 2023.)
Totp_Calculation$(Secret$) | Calculates and returns the current time-based one-time password (TOTP) using the given Base32 secret. (The Totp_Calculation$ method was added in PxPlus 2026.)
UpgradeSecurity( ) | Migrate OLD security file format.
VerifyByEmail(EmailAddress$ [,Name$ ] ) | Send user Two-Factor Authentication confirmation email. Name$ is optional. Returns 1 if successful, 0 if failure. (The VerifyByEmail method was added in PxPlus 2023.)
VerifyBySMS(SmsNumber$ [,Name$ ] ) | Send user Two-Factor Authentication confirmation text message. Name$ is optional. Returns 1 if successful, 0 if failure. (The VerifyBySMS method was added in PxPlus 2023.)
Verify2FA(Userid$) | Send either a text message or email (depending on capabilities and user preference) to user to confirm Two-Factor Authentication and await/confirm response. Returns 1 if successful, 0 if failure or user did not enter proper confirmation number. (The Verify2FA method was added in PxPlus 2023.)

The following properties (in alphabetical order) are supported:

Property | Description
ChangePswdReqd | Flags if password change required.
Company$ | Company name for current user. (The Company$ property was added in PxPlus 2023.)
Email$ | User email address, if verified. (The Email$ property was added in PxPlus 2023.)
LogonFailed | Flag indicating a logon failed. (The LogonFailed property was added in PxPlus 2023.)
NeedNewPasswd | Flag to indicate new password needed.
Name$ | User name.
Retries | Number of allowed logon attempts. (For NOMADS, defaults to 3. For iNomads, defaults to the value of %inomads'failed_logon_tries.) (The Retries property was added in PxPlus 2023.)
Secret_Encoded$ | Contains the Base32-encoded secret generated by Secret_Code$(User_Email$). (The Secret_Encoded$ property was added in PxPlus 2026.)
SMSno$ | User SMS phone number, if verified. (The SMSno$ property was added in PxPlus 2023.)
TFA_Application$ | Application name that will be used in verification emails and/or text messages sent to users. (The TFA_Application$ property was added in PxPlus 2023.)
TFA_Nomads_Time | Time for NOMADS/Windows application. (The TFA_Nomads_Time property was added in PxPlus 2023.)
TFA_Nomads_UOM$ | Unit of Measure: M - Minutes H - Hours D - Days (The TFA_Nomads_UOM$ property was added in PxPlus 2023.)
TFA_SMS_Auth$ | SMS account information. (The TFA_SMS_Auth$ property was added in PxPlus 2023.)
TFA_SMS_Provider$ | SMS service provider. (The TFA_SMS_Provider$ property was added in PxPlus 2023.)
TFA_SMTP_From$ | User ID to send email from. (The TFA_SMTP_From$ property was added in PxPlus 2023.)
TFA_SMTP_Port | SMTP port number. (The TFA_SMTP_Port property was added in PxPlus 2023.)
TFA_SMTP_Pswd$ | Password for account. (The TFA_SMTP_Pswd$ property was added in PxPlus 2023.)
TFA_SMTP_Srvr$ | SMTP mail server. (The TFA_SMTP_Srvr$ property was added in PxPlus 2023.)
TFA_SMTP_SSL | Indicator if SSL/TLS used to connect. (The TFA_SMTP_SSL property was added in PxPlus 2023.)
TFA_SMTP_User$ | User ID to connect with. (The TFA_SMTP_User$ property was added in PxPlus 2023.)
TFA_State$ | Two-Factor Authentication (TFA) state: Y - Enabled N - Disabled O - Optional by user (The TFA_State$ property was added in PxPlus 2023.)
TFA_Web_Time | Time for Web access (iNomads, Webster). (The TFA_Web_Time property was added in PxPlus 2023.)
TFA_Web_UOM$ | Unit of Measure: M - Minutes H - Hours D - Days (The TFA_Web_UOM$ property was added in PxPlus 2023.)
Unsecured | Current states (0 - Not signed on).
UserID$ | Current User ID.
UseTFA$ | Indicates if user requires Two-Factor Authentication: N - Never Y - On new/expired devices A - Always (The UseTFA$ property was added in PxPlus 2023.)

## Example - Get the Current User Name

> ! Get the current username
> secObj=new("*secure");
> Who$=secObj'UserID$;
> drop object secObj

## Example - Logon with User Name and Password

> ! Logon given a user and password
> secObj=new("*secure");
> secObj'Logon(userId$,token$);
> drop object secObj

## Example - Generate QR Code, Secret, and One-Time Password (TOTP)

> secObj = new("*secure")
> secObj'secret_code$("user@company.com") ! Creates a QR code in the working directory

> secret$ = secObj'secret_encoded$ ! Retrieves the Base32-encoded secret
> print secret$

> totp$ = secObj'totp_calculation$(secret$) ! Returns the current 30-second TOTP
> print totp$

(This example was added in PxPlus 2026.)

## See Also

Security Manager