v2.11 November 30th 2001

CFX_Users OPEN-SOURCE NT DLL for Cold Fusion 4.0.1 and up Lewis A. Sellers http://www.intrafoundation.com/ihtk.asp products@intrafoundation.com

G E N E R A L

ABOUT

The tag itself returns a couple variables back no matter what you do (UsersDescription, UsersVersion and UsersError). These are always available unless there is a catastrophic failure of the tag.

Additionally you can use the ABOUT function to return more detailed information on the tag. The fields returned are mostly only of interest for curiosity or in debugging a situation.

Note below that though the tag returns it's SerialNumber, it's not used currently, and hasn't been for a very long time, but probably will be again soon.

For the curious, it also proves the total number of lines of c/c++ that the current build was using. This includes the scant comments in the source code. For instance, this build of the tag has 2732 lines of code.

Description

The general product description.

Version

The version number of the software, ie 2.0.

Quality

The quality field will be one of the following four: "Alpha", "Beta", "Gamma" or "Omega". Quality relates the quality control status of the version of the tag you're currently using.

Alpha code is highly unstable and shouldn't be trusted for anything. Do not use on production machines.

Beta code is close to being finish and it is in a debugging phase. Do not use on production machines.

Gamma code is for use on production machines. As far as the beta testers have determined it works as it should.

When a product goes Omega that generally means it is long used Gamma code that is now no longer being maintained.

SubVersion

The subversion number of the software, ie 4 for "2.0beta4".

SerialNumber

Currently unused.

Lines

The total lines of c/c++ code in the software.

BuildDate

The ODBC DATETIME when the tag was last compiled (built).

Evaluation

Boolean field (0 or 1). 1 indicates the version of the tag you're using is a time-limited evaluation version. 0 is full commercial.

ExpirationDate

The ODBC DATETIME date when the tag will stop working.

U S E R S

Managing users is what this software is all about. What that in mind it should probably be mentioned that, if you didn't know already the NT User Account name consists of up to 20 printable ANSI characters (case sensitive) except: " / \ [ ] : ; | = . + ? <>

USERS

<CFX_Users ACTION="USERS">

The additional fields that are available are the users' full human-readable name, any comments the administrators may have regarding the users, comments or a description by the users about themselves and their SIDs.

A SID? What's that? It's a Security Descriptor. It's the way NT makes sure all user accounts across domains are unique. Each time a user account is created a new SID assigned to it.

If you were wondering (and you know you were), the SID for the Administrator account of this machine is S-1-5-21-1177238915-688789844-1343024091-500. The Guest account has a SID of S-1-5-21-1177238915-688789844-1343024091-501.

If Computer is not supplied then the local machine is assumed.

CURRENTUSERS

<CFX_Users ACTION="CURRENTUSERS">

Returns a query containing a list of all users currently logged onto a machine. Note that there are some instances involving SAMBA, NT3.51 and certain NT4 service patches where the user list is known to be sticky. That is, once a user logs in they may listed as still logged in for a time after they have actually logged out.

The Domains field is a coma-separated list of all domains/servers visited by the user.

Domain is the domain of the user.

Computer is the name of the computer the user is logged in from.

ADD

<CFX_Users ACTION="ADD">

ADD, of course, adds a new user. It creates a restricted initial account. To flesh out the account you should use the CHANGEPROPERTIES and ADDGROUPS functions. Then use ENABLE to make the account active, if you initially created the account disabled.

Is it a local or a domain user? That depends on whether the computer you create it on is a domain controller.

Operations are broken up into a few more steps than the old CFX_UserManager, but this makes it a bit more accident tolerant.

You must specify a password of no greater than 14 characters. If your network requires it you may also allow users to be added with no passwords by simply not using the PASSWORD argument.

MustChangePassword forces the user to change their password the next time they log in.

CannotChangePassword denies a user the ability to change their passwords at all.

PasswordNeverExpires, as might be guessed, permits the user to continue on with their current password forever if they want.

AccountDisabled disables the account as it's created. Useful in some situations.

DELETE

<CFX_Users ACTION="DELETE">

Deletes a user. Note that even if you add a user account later on that has the same username as the old one, thier unique SID and RID identifiers WILL be different. This means file permissions granted to the deleted user can not simply be given back by recreating an account with the same name. You must re-permission all files with the new account.

COPY

<CFX_Users ACTION="COPY">

Have you ever used "User Manager for Domains" copy feature? Well then you know what this function does. It uses another account as a template in the creation of a new user account.

This is similiar to an ADD function in that it creates new acounts.

PROPERTIES

<CFX_Users ACTION="PROPERTIES">

As usual, the functions in this suite try to mimic the layout of the Windows GUI to make things easier to use. The user properties function is not an exception to this little rule-of-thumb.

Some of these fields are in effect read-only, but many can be changed with the CHANGEPROPERTIES function. See below.

User of course is the name of the NT account you requested information on.

PasswordAge is the time that has passed since the password has last changed.

PrivilegeLevel will be either "Guest", "User" or "Administrator".

LogonHomeDir is the home directory of the account.

LogonScript. If present, this script is run when the user logs in. The script may either a BAT, a CMD or a 32-bit EXE.

AuthorizedComputers. This restricts the user to be able to log in to only the comma-seperated workstations named in this field. As many as eight computers may be specified. If blank then any computer may be used.

LastLogon and LastLogoff are the odbc formatted dates when the user last logged on and when they last logged off. The fields will be -1 if they have never logged in. LastLogoff will be -1 if a user is currently logged in but has not YET logged off.

AccountExpires. Yes, it's the date when the account automatically expires. -1 if the account never expires.

Logonhours is a 168 character string indicating all the hours in a week (7 days times 24 hours equals 168 hours). Each character is a boolean. If it's "0" the user can't log in during that time. If it's "1" they can. Using CHANGEPROPERTIES you can effectively make it so a user can only log in during their scheduled work hours. Very handy for anti-hacking puposes.

LogonFailures is the number of times an incorrect password has been entered for that account. If it's above 2 or 3 (or 5000) that might tend to suggest indicate someone's tying to hack into the account.

Disabled. The user account is disabled. You can use ENABLE and DISABLE to set this at will.

LocalPath, Connect and To. These define where the user's home folder (if any) is located. You can either use LocalPath to access a local hard drive or Connect and To to setup a mapped network drive to a lan share.

AccountType. NORMAL, TEMPDUPLICATE, WORKSTATIONTRUST, SERVERTRUST and INTERDOMAINTRUST. TEMPDUPLICATES are users visiting from other domains. WORKSTATIONTRUST is the account for an actual NT Workstation or NT Server computer in this domain. SERVERTRUST is the account for BDC. INTERDOMAINTRUST allows for trust betwen two domains.

SID. This is an indentifier that is unique across domains (the world). It is matched to a current user name. When that user is deleted, and a new user with the asme name is created they are given a completely new SID however. Windows NT, etc actually uses the SID internally for most security/permissions work, not the username.

RID. Relative ID. It's similiar to a SID but of use within the domain only. It's sort of your (short) SID nickname.

CHANGEPROPERTIES

<CFX_Users ACTION="CHANGEPROPERTIES">

Changes the properties of an NT user account. Most of these fields have been discussed along with the PROPERTIES function above, so you should refer to that if you haven't already.

Note that just because the function says you can change it, doesn't mean that NT will let you. Certain combinations of fields are non-sensical to Windows and will be rejected. For instance: MustChangePassword and UserCannotChangePassword. You can't do both.

CHANGEPASSWORD

<CFX_Users ACTION="CHANGEPASSWORD">

Changes a user account password from OLDPASSWORD to NEWPASSWORD. If you do not specify the the Computer then the local one is assumed.

RESETPASSWORD

<CFX_Users ACTION="RESETPASSWORD">

Changes a user password without having to know the old one. Dangerous when used around Administrative accounts.

BLANKPASSWORD

<CFX_Users ACTION="BLANKPASSWORD">

Makes a user account have a blank password. Required to interact with some system.

ENABLE

<CFX_Users ACTION="ENABLE">

Enables a user account.

UNLOCK

<CFX_Users ACTION="UNLOCK">

Unlocks a system locked account.

DISABLE

<CFX_Users ACTION="DISABLE">

Disables the specified user account.

ISLOGGEDIN

<CFX_Users ACTION="ISLOGGEDIN">

Checks if specified user is currently logged into the system. Look at the IsLoggedIn field.

ISUSER

<CFX_Users ACTION="ISUSER">

Checks if specified user exists. Look at the IsLoggedIn field.

ISVALID

<CFX_Users ACTION="ISVALID">

If you supply a user name and a password, this function will attempt to determine if the combination is valid. In other words, could someone log into the system using this username/password pair?

When the accounts are locked out or disabled, etc this will be reported as invalid.

GROUPS

<CFX_Users ACTION="GROUPS">

Lists the groups the user is a member of. By default global domain groups are listed. Use SCOPE to see the other: SCOPE can be: Global or Local.

ADDGROUPS

<CFX_Users ACTION="ADDGROUPS">

Adds a group or list of groups to a user account. The GROUPS field can be a single group or multiple groups seperated by a comma. Use SCOPE to specify if the group is "Global" or "Local".

REMOVEGROUPS

<CFX_Users ACTION="REMOVEGROUPS">

Remove a group or list of groups from a user account. The GROUPS field can be a single group or multiple groups seperated by a comma. Use SCOPE to specify if the group is "Global" or "Local".

AUTHENTICATE

<CFX_Users ACTION="AUTHENTICATE">

The term "authenticate" (or "authentication") has effectively taken on the meaning of sending your credentials (username and password) and then logging in under that account and performing some action on that user's behalf. This tag can not do authentication under that definition. It CAN however take a username and password and validate that a said username exists and whether the password is valid. This function is called "IsValid" or "Validate"

This function does nothing. So why is it included? Because people keep asking where the authentication function can be found in the documentation.

Usually what they're really wanting is the "IsValid" or "Validate" function.

VALIDATE

<CFX_Users ACTION="VALIDATE">

This function is an alias for "IsValid". It is included simply to compliment the "authentication" terminology.

• 2.10 January 3rd 2001.

  Added IHTKPASSWORD. Upgraded reporting code.

• 2.9 December 3rd 2000.
  • Someone noticed the PROPERTIES "domain" parameter wasn't properly working. FIXED.
  • Added partials pattern matching function SEARCHUSERS for David.
• 2.8 November 3rd 2000.
  • Fixed COPY error handling.
  • Upgraded error reporting.
  • Fixed CHANGEPASSWORD bug when no computer stated.
• 2.7 October 25th 2000.
  • Minor documentation fixes
• 2.6 September 29th 2000.
  • Added more tests
  • Fixed some doc errors
  • Cleaned up some code
• 2.5 September 21th 2000.
  • Document clarifications and changes to out-right mistakes in parts.
  • Changed/Added tests.
  • Added even more error reporting information.
  • Fixed situations where computer name was not being properly formatted.
• 2.4 September 19th 2000.

  Upgraded error reporting code to v1.2.

• 2.3 August 31st, Sept 4,8,9,10,11 2000.
  

  NEW TAG: CFX_Users. CFX_UserManager is obsoleted. Split it into two. User functions are moved here (group functions move into CFX_Groups and rest is taken over by CFX_NetworkTopology ). This tag is rather different than the older CFX_UserManager, though it takes freely from it's old code base.

  Be aware that this new tag hasn't had a chance to settle in the field. Triple-check your results if you're doing anything 'exotic'.

  If there's something that been forgotten or misdocumented, email and then check the next release.

• 2.2 August 1st 2000.
  
  • misc
  • Added domains function.

• 2.1 June 30, July 4 2000.
  
  • Got rid of the photographs. Was taking too long to CFMAIL the software.
  • Added GETPRIMARYGROUP
  • Apparently don't mention explictly which functions return SQL queries and when they return to Groups. Fixed.

• 2.0 June 18, 25-26, 27, 28 2000.
  
  • Ripped all shares/network drives/permissions functionality out and moved it to it's own tag: CFX_NFS.
  • Rewrote/polished the docs.
  • Added some photography to break up the layout of the documentation page.
  • Removed PRIVILEGES from ADD. Is now ignored in ADDs.
  • Changed ENUM to USERS.
  • Added USERSQUICK
  • Added SID to USERS and INFO.
  • Added DOMAIN parm to SERVERS. (duh. How'd I forget that? And why'd no one mention it before?)
  • In general removed a lot of useless fields and cleaned up various functions. More than I feel like documenting.
  • Lost all the code to CFX_UserManager when the power flickered while saving. Fortunately God in his infinite wisdom made CDRWs. Had to rewrite the two days of lost code.
  • Added COPY
  • Added SETPRIMARYGROUP
  • Got sick of looking at it. Released it.

  No doubt there will be a 2.1 in a few weeks to squash any remaining bugs. Should have spent another week or two debugging, but been working on this off and on for a couple months and just wanted to get it done and out of the way at the moment. If there's a problem -- just tell me.

  
  
• 2.0beta (aka, The Blue Version). April 1 & May 11, 16-19 & May 29-June 2, June 13-15. 2000 Anno Dominus.
  Good Morning. This is the first new production release since 1.12. It is MAJOR revision.
  The name has been changed to UserManager Suite (as that's what some people had started referring to it as in their emails anyway). It's now bundled with: CFX_GetUserGroups and newcomer CFX_IIS. It now requires either NT 4 with ADSI installed or Windows 2000.

  There have been many additional changes, including, but not limited to:

  • Fixed INFO lastlogon/lastlogoff to pad with 0's for 4 & 2 digit decimal formats
  • Fixed SETINFO acctexpires bug
  • Changed SETINFO acctexpires to use -1 for unlimited instead of having to use 1970-01-01 00:00:00 (which is what NT considers unlimited)
  • SETUSERINFO MAXSTORAGE has been obsoleted/removed. GETUSERINFO supports your legacy code by always returning "-1" for this field.
  • Added THISSERVER function.
  • Added LOCALDRIVES function.
  • Changed ENUM function name to USERS.
  • Added SHARES, SHAREADD, SHAREDELETE (folder shares)
  • Added NETWORKDRIVES, MAPNETWORKDRIVES, DISCONNECTNETWORKDRIVE (mapped network drives)
  • Deprecated VERIFY
  • Added PERMISSIONS, PERMISSIONGRANT, PERMISSIONDENY, PERMISSIONREVOKE (NTFS folder permissions (ACLs))
  • Added VALIDATE (supercedes VERIFY)
  • Added ISLOGGEDIN user function
  • Changed to allow plural or singular parameters for some functions, ie LOCALGROUP and LOCALGROUPS.
  • Improved various error description reporting.
  • Rewrote docs
  • Reworked tests
  • Added USEREXISTS
  • fixed serious SETGROUPS memory bug

  Yes if you bought a copy back with version 1.x you get free 2.x upgrades (whether you want them or not).

  Sorry about the long delay between 1.12 and 2.0. The work was a lot more involved than anticpiated.

  Big thanks to Felix Kasza at mvps.org for all the useful reference material (I was going back to their site so much this week I finally just said "what the hell" and had a program make a mirror copy of their website which I then burned to cdr). The Microsoft API docs straight-out lie in many places and there seem to be very few places or people who know how to work around these API issues.

  NOTE: 2.0beta brought to you a THINK! power bar. Better than heroin. :-) There have been several betas (2.0beta1, 2.0beta2, 2.0beta3 and 2.0beta4, etc). Beta3 and up were public. Beta4 was the first wide-beta. Beta5 was the last beta before the final (almost). Beta6 actually was the last.

  
  
• 1.15alpha. March 7 2000. This was almost the first production release since 1.12. (Versions 1.13 and 1.14 were evaluation/beta only releases.) CFX_GetUserGroups is now bundled with it's big brother. Drives, Shares and Permissions/ACL features are almost finally available. Now 3388 lines of code (close to double of 1.12). ( THIS IS A TEMP RELEASE BECAUSE OF ALL THE PESKY EMAIL WANTING A NEW EVALUATION RELEASE TO BE POSTED. :-) THE OLD FULL 1.12 IS STILL THE CURRENT OFFICIAL PRODUCTION RELEASE. IT'S GOING TO STAY THAT WAY UNTIL I HAVE A FULL 3 OR 4 DAYS TO FINISH THE TAG. DO NOT EXPECT ANYTHING TO DO WITH ACL/PERMISSIONS, SHARES, OR MAPPED DRIVES TO WORK YET. )
• 1.14. Jan 29 2000. Explore VERIFY on non-local server issues. Revise docs. Begin internal mods for possible addition of attrib/share/acl functionality to tag (allows managing of NTFS folders corresponding to users/groups) -- undocumented. Added BLANKPASSWORD="Yes" arg for ADD function as per request (Richard).
  This has been a bad week for anyone wanting a new eval version of the tag. In the middle of what was to be a major upgrade for 1.14 and my old PDC server dies (alright, I was swapping out what I thought was a bad power supply and it took it's revenge and electrically damaged/tainted most of the hardware in the box.) This leaves me in a bit of a position as releasing a new 1.14 eval. So 1.14 is a special build only for people looking for a new evaluation version. Don't use it in production. I've not got a new PDC server so it's not been re-tested yet. Eval release only (full 1.12 is still available in both executable and source.) Wait for 1.15 for new features. Released as "1.14 - Feb 15 2000 (Special Release - Not For Production Servers)".
  
• 1.13. Jan 13 2000. r&d; for a bug report. False, but misc. cleanups & document clarifications. Not released.
• 1.12. Dec 27 1999. NEW FUNCTION "VERIFY": You can now verify a user account by User/password. New evaluation version that expires Feb 7th 2000. Happy Yoshushua Mass and 2005 Anno Dominus. /-)
• 1.11 Nov 3-6. Several misc. changes. probably the last revision for a few months. Two issues addressed were:
  
  • ADD would not always add the specified LOCALGROUPS. For a while I thought this was only happening on Trisha's computer. However, once I started getting in to the code this afternoon (which was some of the oldest in the tag) I realized it probably hadn't been working at all for a while. My current tests just weren't showing it. Rewrote the code. Fixed as far the slightly tweaked tests will verify.
  • There was a report of the tag not functioning if QUERY was not present. So far only one report. Looked at the code. Nothing obvious. Presumably a CString issue. Hmm. The workaround would seem to simply be to specify the QUERY tag in every instance.
  I think the tag needs a few more confidence tests. If you've written any of your own, send them in.
• 1.10 Nov 3. Not released.
• 1.9 Oct 31 1999, that night. Changed the docs. Especially the part about how to register. :) misc..
• 1.8 Oct 29 1999. ADD. misc. New "y2k" evaluation version expires Dec 31 1999 (eval's are generally released a week or two after the last expires.) (Note: Technically it's already been the 3rd millennium for 5 years, but that's a long story.)
• 1.7 Oct 26 1999. Our unofficial bug-hunter for October, Trisha Prothro, noticed more bad behavior with ADD. 2126 lines.
• 1.6 Oct 23 1999. Fixed sticky QUERY. Fixed ADD problem with FLAGS for Trisha. misc.
• 1.5 Oct 6 1999. Craig Davis noticed some problems setting up shared network drives. Oops. You _could_ (barely) but there was no documentation and neither did INFO retrieve the associated info. ADD, SETINFO, and INFO underwent recoding. All "tests" changed. Most changes since 1.0. Probably some new bugs introduced that will need to be squashed in 1.6. A few clarifications in the docs (this page). 2089 lines of c/c++ code. I'm a little leery of 1.5 here as it was rapid, involving more than minor recoding but only verifying through the standard confidence tests. Seems to work. Hmm....
• 1.4 Oct 4. Minor Doc and bug tweaks based on some user feedback. New confidence tests.
• 1.3 Oct 2. Doc and bug fix. New eval on-line.
• 1.2 Oct 1. Doc and bug fix.
• Oct 1. New Oct 31 1999 expiring eval passed out to a few people caught off guard by the original.
• 1.1 august 29th. a few quick changes. new QUERY variable feature. a date-limited evaluation version is released. more verbose error messages.
• 1.0 august 10-14th (intermittent) 1999. like a beta out of hell. no feedback for the last few days. either no more bugs, or no one cares. Either way... We're a gamma release now. Have fun. Send feedback. As for the rest "God only knows... Colour fades away..."
• 0.13beta august 4th 1999. during an acid flash-back God told me to set a freon bug free, free, free, so I did. as God commanded.*
• 0.12beta july 29 1999. bugs, bugs everywhere and not a drop to drink. morning bug hunt. close to gamma. most non-group issues resolved. Price increased. Personally I believe in making software so cheap you don't even have to think about it before you buy. You just buy. Perhaps even if you don't need it. (What do I care if you use it or not?) Thus, you probably won't see another price increase anytime soon. Also, features are essentially locked now. Only optimizing code, removing bugs, and tweaking features will be addressed from now on out.
• 0.11beta july 27 1999. early morning squish-party for setinfo/INFO, etc. mull price increase.
• 0.10beta july 26 1999. bug hunt in RAH powered-suits. added the simple serialno func (re: Allaire tag gallery)
• 0.9beta july 26 1999. same as .8 but forgot to pack the .8dll in the zip files sent out /-)
• 0.8beta july 25 1999. 2049 lines of code (submit to Allaire tag gallery)
• 0.7beta july 22 1999. (john-john and the sea day) 1900 lines of c/c++ code
• 0.6beta (pdc & large domain testing)
• 0.5beta July 21 1999. "Now I know why few people have ever tried to write such a tag before. Maybe I should charge more. /-)"
• 0.4alpha
• 0.3alpha (private-only release)
• 0.2alpha
• 0.1alpha (first public release)
• 0.0alpha This tag started out to service a need within a Web Hosting and Intranet project. It's primary use still is intranet-centric.