Intranet/Hosting Toolkit | [table of contents]

`v1.14 December 2nd 2001` | CFX_GetUserGroups 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_GetUserGroups is a function-limited read-only subset of CFX_UserManager. Use of this tag is prefered in some situations. It allows you to do only three things: 1) list all users in the NT security database & all local/global groups that exist in a domain/workstation & current users 2) list the groups/localgroups a single user belongs to as well as basic user info, 3) or (as of 1.6) verify a user by username/password. THIS TAG IS FREEWARE. | C O N T E N T S Lists User Groups Verify Parameters Returned Variables Bugs Version History

`top`

## LISTS

#### <CFX_GetUserGroups>

If do not pass any arguments to this tag, aka:

> <CFX_GETUSERGROUPS>

then you get back several queries including: Users, LocalGroups, GlobalGroups and CurrentUsers.

### Users Query

This query contains a list of all NT user accounts plus some basic information.

- Username
- Fullname
- Comment
- UsrComment

### LocalGroups Query

This query lists all the various localgroups.

- Name

### GlobalGroups Query

This query lists all the (global) groups.

- Name
- Attributes
  - GroupEnabledByDefault
  - GroupMandatory
  - GroupOwner

### CurrentUsers Query

As of 1.4, the CurrentUsers query is returned. It lists all users currently logged in. Or should. Some older upgrade versions of NT apparently had "sticky" user accounts which would not be removed from the internal list when they logged out.

- Username
- Domain

`top`

## USER GROUPS/LOCALGROUPS AND BASIC INFO

#### <CFX_GetUserGroups USERNAME="" [SERVERNAME=""]>

Need to get some basic info about an NT account including what groups or localgroups it belongs to? If you pass to the tag the arguments Username and Servername you will retrieve three queries: UserGlobalGroups, UserLocalGroups and User.

## UserLocalGroups Query

- Name

## UserGlobalGroups Query

- Name
- Attributes
  - GroupEnabledByDefault
  - GroupMandatory
  - GroupOwner

## User

As of 1.5, this QUERY is also returned.

- Username
- Comment
- Fullname
- UsrComment
- CodePage
- CountryCode

`top`

## VERIFY USERNAME/PASSWORD

#### <CFX_GetUserGroups VERIFY="" PASSWORD="" [DOMAIN=""]>

As of 1.6, you can verify (or validate) whether a certain username with a certain password exists. This is typically used to validate a user that is trying to log into or manange an NT user account.

It works like this: You supply the username you wish to verify as the parameter VERIFY, their password as PASSWORD (and, optionally, their DOMAIN). If the username exists and the password is correct then GETUSERGROUPS will return "TRUE". If any error occurs or the account does not exist or the password is incorrect then "FALSE" will be returned.

Note that if an account is "DISABLED", or some other limitations are enabled then this function may tell you their usename/password are invalid. This is normal. Technically the VERIFY function is actually determining whether or not the account is able to be logged into, not whether it simply exists.

Please see the example page for a working example, but to query the Guest account you might do something like:

You might also get a A required privilege is not held by the client 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" for this special account.

> <CFX_GETUSERGROUPS VERIFY="Guest" PASSWORD="Guest">

`top`

## PARAMETERS

USERNAME
  The NT User Account name. Up to 20 printable ANSI characters (case sensitive) except: `" / \ [ ] : ; | = . + ? <>`
SERVERNAME
  Name of the server (such as \\SISSY).
DOMAIN
  Name of the domain.
VERIFY
  Same as USERNAME when doing a VERIFY.
PASSWORD
  Used with VERIFY. The user's password.

`top`

## RETURNED VARIABLES

This tag will echo back Username if you set it. It may return the Queries LocalGroups, GlobalGroups, UserLocalGroups, UserGlobalGroups and Users.

The tag will always return four other variables:

GetUserGroupsError
  A detailed error message. Cumulative. Blank if no error. DO NOT TRUST ANY DATA RETURNED IF THERE ARE ANY ERRORS.
GetUserGroupsDescription
  This is a general description of the tag.
GetUserGroupsVersion
  This tells you the major/minor version as well as the release quality.
GetUserGroupsSeconds
  The number of seconds the tag was processing.

`top`

## BUGS or FEATURES?

Is it a bug or is it a feature? You tell us.

If you think you've discovered a blatant bug, or if the configuration of your servers is such that the tag is incorrectly handling your system, feel free to send copies of the html results for the all the examples pages or any page you have written for your site using this tag.

Send results to ihtk@intrafoundation.com.

Updates to the tag will be made ASAP.

I am also interested in seeing the results of the examples pages using this tag even if it works. And, I'm interested in comments on making a more useful examples pages.

`top`

## VERSION HISTORY

- 1.13. December 2nd 2001.

  As this is the simplest of all the tags in ihtk, rewrote the c++ as an example for the rest of open-ihtk. Should be thread-safe now and more easily portable to COM.

- 1.13. October 2nd 2000.

  Misc. clean up.

- 1.12. July 24/25 2000.

  Made free and source code released July 24 2000 (version 1.12).

  This tag was made from code stripped out of an old 1.x version of CFX_UserManager (1.4 I think). It's old. And unmaintained, but works well. It was available for a long time for $20 but after awhile it became pesky to answer a lot of questions for simple $20 tag, so I thought about making it free. I didn't do so for a long time because I think it wouldn't be fair to those who bought a copy, but now... .

  The full compiled release version is available both in the eval and commercial versions of UserManager Suite as of v1.12 of CFX_GetUserGroups.

- 1.11. July 18 2000. More slight document changes for UserManager bundling.
- 1.10. May 16 2000. Slight document changes for UserManager bundling. It's part of the UserManager Suite now, ok?. It retains it's "yellow" feel from the 1.x era.
- 1.9. March 28 2000. Had a snack on a few minor bugs in cf and cfx code to soften some error reports. Some variables were coming back with "UserManager" prepended (because the code came originally from that tag), so changed it to the proper "GetUserGroups". Changed documentation slightly to reflect the tags bundled status (it's now bundled with CFX_UserManager).
- 1.8. Feb 17 2000. Omega. Final Release. For additional features refer to CFX_UserManager 1.15 and up. Misc clean up.
- 1.7. Jan 13 2000. Misc clarifications of examples on a report of SERVERNAME bug. This is _probably_ the last bug fix for this tag. It's almost more pesky than it's worth (generates a lot of email I don't have time to answer or trouble-shoot). It wouldn't be fair to make it free now though. Had thought about simply sending out the full source to all registered people before I take it off-line for good (CFX_UserManager is a different matter though).
- 1.6. Dec 27 1999. NEW FUNCTION "VERIFY": You can now verify a user account by username/password. New evaluation version that expires Feb 7th 2000.
- 1.5. Nov 3 1999. Added USER query returning Username, Comment, Fullname, UsrComment, CodePage and CountryCode per request of Bruce Bicknell. New eval that expires dec 31 1999, 11:59PM. Just in time for it to party with all the Y2K bugs that wake after their two thousand year slumber.
- 1.4. Oct 6 1999. Added CurrentUsers feature. doc and bug fixes.
- 1.3 misc.
- 1.2 misc.
- 1.1 misc.
- Oct 1. New Oct 31 1999 expiring eval passed out to a few people caught off guard.
- 1.0 august 14 1999
- 0.0 Unrecorded.

`top`
`f i n i`
`-{ts '2001-12-03 03:35:35'} /ihtkdocs/GetUserGroups/index.cfm-`