| Intranet/Hosting Toolkit | [table of contents] |
![[CFX_UserManager]](../../ihtkdocs/UserManager/title.png) v2.3 December 2nd 2001 |
CFX_UserManager
OPEN-SOURCE NT DLL for Cold Fusion 4.0.1 and up Lewis A. Sellers http://www.intrafoundation.com/ihtk.html ihtk@intrafoundation.com |
|
FOREWORD This is an Allaire Cold Fusion Extension Tag (CFX). It is for use with Allaire Cold Fusion Servers 4.0.1 (and up) running on Microsoft NT. It was written by Lewis A. Sellers of Intrafoundation Software. CFX_UserManager provides a functionality similar to NT's administrative tool "User Manager for Domains": With it you can create, delete, modify or copy any NT user account You also have control over the local and domain groups which the user may be a member of. There are also additional "support" functions available which include, among other things, browsing the list of currently logged in users, listing domain controllers and servers, etc. Please read the version history for current tag status before emailing questions. |
C O N T E N T S |
The tag itself returns a couple variables back no matter what you do (UserManagerDescription, UserManagerVersion and UserManagerError). 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 3754 lines of code.
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.
New as of 2.0. Returns information about the server the cfx tag is installed on. For the most part these fields are of little practical use beyond curiosity. ComputerName and Username are exceptions however.
ComputerName relates the actual name given to the computer by netBIOS. This is also known as the server name if you prepend two-slashes to it. For instance, you're currently reading this on a machine that calls itself SASHA.
Username is the NT user name of the account that the ColdFusion application server is running under. It's installed by default to use SYSTEM. Some people will create an Administrator account specifically for ColdFusion to run under. You, btw, are using the account SYSTEM to run ColdFusion.
The fields returned are:
MaxUsernameLength, MaxPasswordLength and MaxPathLength are useful in that they give you the system's maximum character length for those three fields. This is information, which if you didn't already know of it, is useful in checking form fields for valid data.
This function returns a list of all servers in a domain. If you don't specify a domain, it assumes the local one. Additionally, instead of having it return all the servers in said domain you can ask for only specific types (through SERVERTYPE) such as:
For instance, this allows you to quickly list all the workstations only. If you don't specify a server type, then it assumes you want all servers.
SERVERS returns a SQL query with the following six columns:
The name field is primarily all that is important. PlatformID, VersionMajor and VersionMinor, etc refer to LAN Manager specific information that you probably aren't interested in unless you're debugging your network.
LEGACY NOTE: In 1.x this function was called SERVERSENUM. To support legacy cfml code you may still use the action SERVERSENUM. It simply calls the current SERVERS function.Returns a list of domains.
DOMAINS returns a SQL query with one field:
Retrieves the Primary (PDC) Domain Controller name. Of use mainly for NT4.
The function returns a SQL query with the following column:
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: " / \ [ ] : ; | = . + ? <>
So, you want a list of all the users in the domain and you want it quickly. You've come to the right function. USERSQUICK returns SQL query with the single field called Username. This field of course an NT user account name.
This function is quicker than USERS (below). It's generally of more use when doing autonomous book-keeping type work where you don't need to know anything other than the usernames.
If servername is not supplied then the local machine is assumed.
This is similiar to USERSQUICK, but it provides a little more information. 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.
The field names for the returned query are:
If servername is not supplied then the local machine is assumed.
LEGACY NOTE: In 1.x this function was called ENUM. To support legacy cfml code you may still use the action ENUM. It simply calls the current USERS function.Adds a new user account by username. You can specify a minimum number of attributes of the account when initially creating it. To access or modify the more detailed attributes use the SETINFO function.
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 using the argument BLANKPASSWORD="Yes".
In 1.x days the FLAGS parameter was used to set several boolean flags that specified attributes of this account. Don't bother with it anymore. You can explicitly toggle these options now with the parms: SCRIPT, ACCOUNTDISABLE, HOMEDIRREQUIRED, LOCKOUT, PASSWORDCANTCHANGE, and DONTEXPIREPASSWORD. You can also directly set the account type with ACCOUNTTYPE. The last can take a value of NORMAL, TEMPDUPLICATE, WORKSTATIONTRUST, SERVERTRUST or INTERDOMAINTRUST. NT won't accept all combinations of these as valid. In that case no change will be made.
If servername is not supplied then the local machine is assumed.
As stated above, FLAGS does not need to be used anymore. But if you're maintaining legacy code this is how it works. "Flags" is a number containing the following boolean switches. Add up the numbers in parentheses to compute the magic number you wish to use. 66409 is the Administrator default. 66115 is the Guest default.
Deletes a user by username. Note that even if you add a user account later on that has the same username their SID 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.
If servername is not supplied then the local machine is assumed.
Gets detailed information on the specified user account. This function returns a SQL query with a large number of fields. Some of them are... of little use beyond technical curiosity. Let us first list them all before we go further:
Username of course is the name of the NT account you requested information on.
PasswordAge is the number of seconds that have passed since the password has last changed.
Priv will be either "Guest", "User or "Administrator". It is a read-only field.
HomeDir is the home directory of the account.
ScriptPath. The full path to a bat, cmd or exe that runs everytime the users logs in. (And no, it can't be a cfm as far as I know.)
Parms is an interesting little field. It is used by MS applications to store null-terminated (ie, c-style) text strings. MS warns against modifying this information.
Workstations. This restricts the user to be able to log in to only the comma-seperated workstations named in this field. If no workstations are named, then they may use any station in the domain.
LastLogon and LastLogoff should be fairly obvious. The field will be 0 if they never logged in or have yet to log off.
AcctExpires. Yes, it's the date when the account automatically expires. In um1.x this field returned 1970-01-01 00:00:00 if the account never expired. This date is zero hour for NT's Y2K unfriendly date system. That's a bit cryptic though isn't? So for um2.x it was changed to report "-1" if the account never expires. (Sorry if that breaks some legacy code.)
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 SETINFO you can effectively make it so a user can only log in during their scheduled work hours. Very handy for anti-hacking puposes.
BadPWCount (Bad Password Count) 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.
LogonServer is exactly what it sounds like. The server the acount last logged in on. For NT Servers \\* is returned.
UserID is your account RID. It's similiar to a SID but of use within the domain only.
When PasswordExpired is not 0, then the password has expired.
Script. If this boolean value is 1, then the script in ScriptPath is executed when the user logs in.
AccountDisable. The user account is disabled.
HomeDirRequired. Not actually used in NT4.
PasswordNotRequired. No password is required to log in.
PasswordCantChange. The user can't change the password. Only an administrator.
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.
The Flags field is the raw bit-encoded boolean flags for various attributs of an account. Since 2.x decodes them for you this may or may not be of much use.
If servername is not supplied then the local machine is assumed.
LEGACY NOTE: There have been a few changes since 1.x. AcctExpires now returns -1 instead of 1970-01-01 00:00:00 if the account does not expire. Several spelling formats have been deprecated rom hte NT default to something human-readable.Sets or changes information relatingto the NT user account.
Most of these fields have been discussed along with the GETINFO function above, so you should refer to that if you haven't already.
Here's a hint if you're trying to set your "Primary Group". See where it says PrimaryGroupID here and in GETINFO? Now, when you list (domain) GROUPS, see where it says GroupID? Yes, those are the same thing. If you set your PrimaryGroupID to the GroupID of a domain group then you've just set that as your Primary Group. FYI.
If servername is not supplied then the local machine is assumed.
Again, flags is left over from 1.x. It allows you to directly modify certain properties of the user account via boolean flags. 66409 is the Administrator default. 66115 is the Guest default.
Changes a user account password from OLDPASSWORD to NEWPASSWORD. If you do not specify the domainname or the servername then the local domain is assumed.
This function may take several seconds to complete.
Checks if specified user is currently logged into the system. Return boolean values in UserManager variable. "0" means user is not logged in. "1" means user is logged in.
New as of 2.0.Checks if specified user exists. Return boolean values, ie "0" or "1". "0" means user account does exist. "1" means user account does not exist.
New as of 2.0beta5.Returns a query containing a list of all users currently logged onto a server. Note that there are some instances involving SAMBA, NT3.51 and certain NT 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. The other columns are self-evident: Domain is the domain of the user, the LoginServer is the machine they logged in from, etc.
LEGACY NOTE: In 1.x this function was called LOGGEDUSERSENUM. To support legacy cfml code you may still use the action LOGGEDUSERSENUM. It simply calls the current LOGGEDUSERS function.New as of 1.12, you can validate user acounts. That is, you can give this function a username and password, and it will tell you if that is a validate account or not.
Btw, this function may seem innocent enough at first, but do not let access to it be easily exposed on your site. Hackers simply running nothing other than ColdFusion like you could easily set up a script with CFHTTP, etc to toss a dictionary at your site in order to brute force figure out what your Administrator password is. And so on. As with all functions here, no matter how trival they may sem at first, guard them well.
Anyway, results of VALIDATE are returned in boolean numbers. "0" (aka FALSE) if the username/password pair do not match. "1" (aka TRUE) if they do. If any error occurs or the account does not exist or the password is incorrect then "0" will be returned.
Note that if an account is "DISABLED", or some other limitations are enabled then this function may tell you their username/password are invalid (as well as producing a lengthy bit of text in the UserManagerError variable.) This is normal. Technically the VALIDATE function is actually determining whether or not the account is able to be logged into, not whether it simply exists. Thus, if the account is disabled, it can not be logged in to and the VALIDATE will fail.
You might also get the A required privilege is not held by the client error message if you do not have the Cold Fusion Server logging is as SystemAccount. You'll need to add the advanced right to the group "Act as part of the operating system" to the account that the Cold Fusion server runs under.
LEGACY NOTE: This function superceeds the old VERIFY function. Externally the only difference is VALIDATE returns boolean values, while VERIFY returned the text values "TRUE" or "FALSE". For legacy purposes VERIFY is still maintained in the code, but is otherwise undocumented.Have you every used User Manager for Domains' copy feature? Well then you know what this function does. It uses another account as a template in the create of a new user account. This is similiar to an ADD function in that it creates new acounts.
You can do this without a special function using GROUPS and SETINFO, but this is simplier to use. SETPRIMARYGROUP will change the global group which is a users' primary group. For this function to work the user must already be a member of said group (GROUPADDUSER).
You can use GETINFO and GROUPS to derive the name of an accounts' primary group, but this is faster. It returns the name of the primary (global) group the user is a member of in UserManager.
Blank if the group or username is unknown.
New for 2.1
Lists all localgroups. Data is returned in an SQL query with the fields Name and Comment. If servername is not supplied then the local machine is assumed.
Adds to the local groups.
Deletes a local group.
Adds members to the specified local group. Members may be a comma separated list.
Deletes members from the specified local group. Members may be a comma separated list.
Lists all members of a local group.
Gets list of local groups user is in. If servername is not supplied then the local machine is assumed.
Lists all groups. If servername is not supplied then the local machine is assumed.
Adds to the global groups.
Deletes a global group.
Adds a user to a global group.
Deletes a user from a global group.
Lists all users of a global group.
Gets list of global groups user is in.
Sets user info. If servername is not supplied then the local machine is assumed.
![[The grassy field]](../../ihtkdocs/UserManager/field1hd.png)
Spent most of Sunday today retrofitting first GetUserGroups as a test then CFX_UserManager here to A) be thread-safe and B) setting it up as an example for future open-ihtk tags.
This was a very fast and somewhat serious rewrite -- it converted the tag from being essentially class-less C in nature to embracing C++ classes in such a way as to overcome threading issues. Or at least that was the purpose. I really don't have the time to reconfigure a bunch of Windows NT 4 machines, etc and properly test this tag so... You'll have to do that yourself.
Normally I wouldn't have spent the time to upgrade such old software, but apparently sub-contractors for NASA have been using it... and have ran into threading issues of late. Thus... as someone who's fairly pro-space it's been nagging at me for a while. So since I couldn't get anyone else to do it, I went and did it myself.
Hope it works under NT4... I haven't even seen my copy of NT4 in probably a year now so it's all just educated guess work. I sure as hell wouldn't trust any multi-million dollar projects to the code. :-) But then that is why I've released the entire code-base as an open-source project: with the hopes some interested programmers somewhere will get-together, clean it up and stress test the hell out of it.
Oh, well and that people will stop asking me questions about the tag. :) See the Online Support Forums.
--min
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.
There have been many additional changes, including, but not limited to:
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.