The Auth object can be used to control access to individual FoxWeb scripts. When a user requests a protected script, FoxWeb checks whether this user has already been authenticated and either allows execution of the script, or returns an authentication form. Valid user names and passwords can be contained in a table, and/or the Auth.AuthList property -- a character string containing comma separated user name/password pairs.
The Auth object provides quite a bit of flexibility in how it operates and appears to the user. The various object properties can be used to control the behavior of the object, as well as the content, design and behavior of the elements contained in the login form.
This object works in conjunction with the Session object and requires the browser to support cookies.
Note: The Auth object typically uses a POST form to collect user names and passwords. Unless you utilize SSL to encrypt communication between the browser and the server, it is possible that this sensitive information will be intercepted while it travels over the Internet. It is highly recommended that you always use SSL when any sort of sensitive information is transported over the Internet.
Auth.property|method([parameters])
| AcknowledgeUserID | Controls whether FoxWeb acknowledges correct entry of the User ID. |
| AuthFormFile | The path to the FoxWeb script, used to generate the authentication form. |
| AuthList | A comma-separated list of authorized user names and passwords. |
| AuthTable | The path to a table that contains authorized user names and passwords. |
| CancelAction | Optional JavaScript action that is performed when the user clicks on the Cancel button in the authentication form. |
| CaseSensitive | Causes passwords checks to be case-sensitive. |
| EncryptPassword | Allows passwords to be stored in encrypted form. |
| FailedPassword | Is populated with the submitted password after a failed authentication attempt. |
| FailedUserID | Is populated with the submitted user id after a failed authentication attempt. |
| Footer | HTML text that is displayed at the bottom the authentication form. |
| Header | HTML text that is displayed at the top the authentication form. |
| LoginTime | The time on which this user first logged in. |
| MaxLoginAttempts | The maximum number of unsuccessful login attempts allowed for a single browser during the duration of a user session. |
| NewLogin | Specifies whether the user just logged in with the current request. |
| Password | The password of the user that is currently logged in. |
| PasswordCaption | The caption of the password field in the authentication form. |
| PasswordFieldName | The name of the password field in the Auth.AuthTable table. |
| SaveCookie | Specifies whether the user is given the opportunity to save the authentication credentials as cookies on their browser. |
| Result | Is populated with the authentication result after a call to Auth.Authenticate. |
| ShowPassword | Specifies whether the password field in the authentication form is masked with asterisks or displayed as clear text. |
| Timeout | The amount of time during which the user can remain idle. If the user requests a protected page after his authentication session times out, then FoxWeb re-displays the authentication form. |
| UserID | The User ID of the authenticated user. |
| UserIDCaption | The caption of the User ID field in the authentication form. |
| UserIDFieldName | The name of the User ID field in the Auth.AuthTable table. |
| AdminAuthenticate | The same as the Authenticate method, but authenticates against the Admin. User ID and Admin. Password entries specified in the FoxWeb Control Center. |
| AdminLogout | Equivalent to the Logout method, but logs out users that logged in via the AdminAuthenticate method. |
| Authenticate | Checks whether the user has already been authenticated, and if not, it returns the authentication form. |
| ForgetPassword | Erases the cookie which holds permanent authentication information from the browser. |
| Logout | Logs the current user out of the system. The user will need to be re-authenticated in order to access another protected script. |
This property controls whether FoxWeb will acknowledge correctly-entered User IDs after a login failure. By default AcknowledgeUserID is set to .F., which causes FoxWeb to return an identical login failure message, regardless of whether the user entered a valid User ID or not. If AcknowledgeUserID is set to .T. then FoxWeb does not clear the User ID field and only asks for the password in the login failure message.
This property is read/write.
Auth.AcknowledgeUserID = .F.
The path to the FoxWeb script, used to generate the authentication form. By default this property points to the script AuthForm.fwx in the FoxWeb directory, but you can create other scripts and point to them from your applications. Different applications can share the same AuthFormFile script, or if you wish, each application can have its own.
This property is read/write.
Auth.AuthFormFile = cFilePath
FoxWeb by default uses the script AuthForm.fwx in the FoxWeb directory to generate the authentication form. Although the Auth object provides a great deal of flexibility in how the final authentication form will look (check the Header, Footer, UserIDCaption, PasswordCaption, CancelAction, ShowPassword properties), it is sometimes desirable to have a completely different design in the authentication forms used in your various applications.
FoxWeb provides the capability to create multiple authentication form scripts and use a different one for each application on your server. To do so, you will need to set the AuthFormFile property before you call the Authenticate method in your protected scripts.
When editing or creating authentication form scripts you should use the supplied AuthForm.fwx as a template. First make a copy of AuthForm.fwx and then modify it according to your needs. Make sure that you preserve all elements that are required by the Auth object. These include all expressions within script delimiters (<% and %>), as well as the <META> tags included at the top of the file. It is recommended that you always keep a backup of the original AuthForm.fwx that is installed with FoxWeb.
The AuthList property can be populated with a comma-separated list of authorized user names and passwords.
This property is read/write.
Auth.AuthList = cCredentials
|
Before using the Authenticate method you must populate the AuthTable property and/or the AuthList property. If both properties are populated, then FoxWeb searches both the user table and the user list for a match.
The AuthTable property specifies the path to a table, which contains authorized user names and passwords.
This property is read/write.
Auth.AuthTable = cTablePath
|
Before using the Authenticate method you must populate the AuthTable property and/or the AuthList property. If both properties are populated, then FoxWeb searches both the user table and the user list for a match.
If the field names in your table are different than the default names "userid" and "password", then you need to specify these names with the UserIDFieldName and PasswordFieldName properties.
To speed up searches in the user table you may want to index it on the User ID field. In order to make authentication case insensitive the Auth object searches the table by UPPER(userid). For this reason you will need to create your index on the same expression:
|
Obviously if the name of your User ID field is different you will need to adjust your index accordingly.
The CancelAction property specifies an action that is to be taken if the user clicks on the Cancel button of the authentication form.
This property is read/write.
Auth.CancelAction = cCommand
|
The command specified in this property is inserted in the OnClick clause of the Cancel button, so it must be a valid JavaScript command. If this property is not populated, then the Cancel button is not displayed.
For more information on JavaScript refer to the excellent books available at your local bookseller, or to the on-line resources that can be found on the Web.
The CaseSensitive property instructs the Auth object to do a case-sensitive comparison during user authentication. This affects passwords listed in the AuthList property, as well as passwords stored in the table specified by the AuthTable property.
This property is read/write.
Auth.CaseSensitive = lCaseSensitive
The EncryptPassword property allows storing of passwords in encrypted form. This affects passwords listed in the AuthList property, as well as passwords stored in the table specified by the AuthTable property. Passwords are not actually encrypted in the conventional sense of the word, but rather converted to a 128-bit hash, using the one-way MD5 algorithm. This means that it is actually impossible to retrieve the corresponding password from the hash string. Instead, the software converts user-entered passwords with the MD5 algorithm and compares them with the previously-converted passwords on the server.
In order to "encrypt" a password, you will need to use the Server.HashMD5 method. Important: If you intend to set EncryptPassword to .T., while keeping CaseSensitive equal to .F., you will need to convert passwords to upper case before processing them with the Server.HashMD5 method.
This property is read/write.
Auth.EncryptPassword = lEncryptPassword
The FailedPassword property is populated with the password that was submitted by the user during a failed authentication attempt.
This property is read only.
cFailedPassword = Auth.FailedPassword
This property can be used in fw_exit.prg along with Auth.Result and Auth.FailedUserID to log failed login attempts. Sample code can be found in the Auth.Result section.
The FailedUserID property is populated with the user ID that was submitted by the user during a failed authentication attempt.
This property is read only.
cFailedUserID = Auth.FailedUserID
This property can be used in fw_exit.prg along with Auth.Result and Auth.FailedPassword to log failed login attempts. Sample code can be found in the Auth.Result section.
The Footer property specifies HTML content that is inserted at the bottom of the authentication form.
This property is read/write.
Auth.Footer = cFooterText
|
The Header property specifies HTML content that is inserted at the top of the authentication form.
This property is read/write.
Auth.Header = cHeaderText
|
The LoginTime property returns the date and time that the current user first logged into the system during the current session.
This property is read only.
tTimeStamp = Auth.LoginTime
The following code checks the time the user logged in, and if it has been more than an hour it logs the user out of the system and deletes his entry from the user table.
|
The MaxLoginAttempts property can be used to limit the number of unsuccessful login attempts by a user.
This property is read/write.
Auth.MaxLoginAttempts = nTotalAttempts
|
This property can be used as a first line of defense against users who try to guess passwords, but it is not 100% secure. FoxWeb keeps track of unsuccessful attempts by incrementing a session variable. If the user restarts his browser (or in some other way removes cookies sent be the server) then the session cookie is deleted which in effect resets the count to 0.
The NewLogin property specifies whether the user has just logged in during the current request.
This property is read only.
lNewLogin = Auth.NewLogin
The following example returns a greeting on the first hit after a user is authenticated:
|
The Password property returns the password of the user that is currently logged in.
This property is read only.
Auth.Password = cPassword
The PasswordCaption property specifies the caption of the password field in the authentication form. By default this property is equal to "Password".
This property is read/write.
Auth.PasswordCaption = cCaption
|
The PasswordFieldName property specifies the name of the AuthTable field, which holds password information. By default FoxWeb looks for a field named "password".
This property is read/write.
Auth.PasswordFieldName = cFieldName
The SaveCookie property specifies whether the FoxWeb can store the User ID and possibly the password to the user's browser after a successful login.
This property is read/write.
Auth.SaveCookie = nFlag
| Value | Description |
| 0 | Nothing is stored on the client. After the user logs out, he will have to enter both his user name and password in order to log in. |
| 1 | The user name is stored on the client as a persistent cookie. Next time the user revisits the site from the same browser, the user name field in the authentication form will be pre-populated. |
| 2 |
If SaveCookie is set to 2, the authentication form includes a check box, which provides users the option to store a hash string representing the password on their browser. If this check box is checked, users will not be asked to log in again unless they explicitly log out of the system, in which case the password cookie is deleted.
This value stores the user name on the client regardless of whether the user checks the "Remember Password" check box. |
Even if this property is set to 2, the password is never actually saved as a cookie. Instead, a one-way hash string representing the password is sent to the browser. This means that even if the browser's cookie file is hacked, the password will not be vulnerable to the attacker.
The Result property is populated with the authentication result after a call to Auth.Authenticate. It can be used in fw_exit.prg along with Auth.FailedUserID and Auth.FailedPassword to log failed login attempts.
This property is read only.
| Value | Description |
| 1 | Successful login |
| 0 | No login attempt |
| -1 | Bad password |
| -2 | Bad user id |
| -3 | User resubmitted the login form from the browser history after logging out |
| -4 | User exceeded MaxLoginAttempts |
| -5 | Cookie verification error (the browser may not support cookies) |
The following sample code can be inserted in fw_exit.prg to log failed authentication attempts. It requires that you first create a table with the appropriate fields:
IF Auth.Result < 0 |
The ShowPassword property specifies whether the password field in the authentication form is masked with asterisks (type="password"), or is readable (type="text").
This property is read/write.
Auth.ShowPassword = lFlag
The Timeout property specifies the time in minutes that the user can remain idle without having to log in again. If the user does not request a script within the timeout period, he is asked to log in again the next time he tries to access a protected script.
This property is read/write.
Auth.Timeout = nMinutes
The Auth.Timeout value should always be less than or equal to the Session.Timeout value. All Auth object variables are saved as session variables, so if the session expires, the user will have to log in again anyway.
This property has no effect for users, that have checked the Save Password option in the authentication form, because these users will be logged in automatically anyway.
The default value of the Timeout property is 10 minutes.
The UserID property returns the User ID of the current user.
This property is read only.
cUserID = Auth.UserID
The following example returns a welcome message if the user has just logged in:
|
This property is only populated if the user has already logged in.
The UserIDCaption property specifies the caption of the User ID field in the authentication form. By default this property is equal to "User ID".
This property is read/write.
Auth.UserIDCaption = cCaption
|
The UserIDFieldName property specifies the name of the AuthTable field, which holds the user names. By default FoxWeb looks for a field named "userid".
This property is read/write.
Auth.UserIDFieldName = cFieldName
This method works exactly the same way as the Authenticate method. The only difference is that it authenticates against the Admin. User ID and Admin. Password settings entered in the FoxWeb Control Center. Setting the AuthList, AuthTable, CaseSensitive and EncryptPassword properties for this call is unnecessary and has no effect.
Auth.AdminAuthenticate()
This method works exactly the same way as the Logout method, but logs out users who logged in via the AdminAuthenticate method. Unlike the Logout method, you do not need to set the AuthList and AuthTable properties before calling AdminLogout.
Auth.AdminLogout()
Checks whether the user has already been authenticated, and if not, it returns the authentication form.
Auth.Authenticate(JustCheckAuth, UserID, Password)
|
The Authenticate method works by checking a number of session variables to see whether the user has been authenticated according to the authentication criteria required by the current page. If the user has already been authenticated against the same AuthTable and/or AuthList, then the method simply returns control back to the script. If on the other hand the user has not been authenticated yet, it generates an authentication form, which calls the same URL as the one that originated the call to the current script. If the current request includes form fields, they are preserved in the authentication form as hidden fields. The current query string is also preserved.
The ForgetPassword method deletes the password cookie from the browser. A password cookie is sent in the first place if Auth.SaveCookie = 2 and the user checks the "Save Password" check box in the authentication form.
Important: In order for this function to function properly you must populate the AuthTable and/or AuthList properties with the exact same values that were in effect during the time the user logged in.
Auth.ForgetPassword()
|
This method deletes the password cookie without logging the user out. After the user logs or times out, he will not be allowed back in until he is authenticated again, by completing the authentication form.
The Logout method logs a user out of the system.
Important: In order for this function to function properly you must populate the AuthTable and/or AuthList properties with the exact same values that were in effect during the time the user logged in.
Auth.Logout()
|
In addition to logging the user out, this method deletes the password cookie, if one had been previously sent to the browser.