NTAccess.Groups Readme

NTAccess.Groups: An ASP Component for Querying NT User groups
Version : 1.42
Release Date : 20 Febuary 98
Copyright (c) 1997-1999 by Simon Fell. All rights reserved.
Contact:
email : Simon Fell
WWW : Zaks Solutions Web Site

If you have any problems using this component please report it.

Description
NTAccess allows the the checking of membership to NT User groups for a user. This is very similar to the Novell function IfMember and the Kixtart function InGroup. It also allows for a number of group management functions to be accessed from ASP and other COM environments.

Installation Instructions
To use this ASP component move the DLL into a sub directory (like \winnt\system32\inetsrv\asp\Cmpnts or \winnt\system32) and run (from the directory copied to)

regsvr32 NTAccess.dll
If you are replacing an earlier version, remember to shutdown & restart IIS to reload the new version. ( "net stop iisadmin /y" from a command prompt, followed by "net start w3svc" )

License Agreement
NTAccess.Groups is copyright (C) 1997-1998 by Simon Z. Fell

NTAccess.Groups is currently free to download and use. You may NOT redistribute the package through BBS, Internet, FTP sites or by any other means without written permission from the Author.
You are prohibited from:
charging a fee or requesting donations for the package;
distributing/including the package in commercial products or for commercial gain (without a commercial license );
modifying the package.

All trademarks/registered names acknowledged.

NTAccess.Groups is provided as is, without warranty of any kind.
The author shall not be liable for damages of any kind. Use of this software indicates you agree to this.

How To Use
A set of example ASP scripts are included in the download

Object Properties / Methods
All the code snippets assume that

set ntg = Server.CreateObject("NTAccess.Groups")

has already been called. If you are using NTAccess.Groups from ColdFusion then, you should use a special version of the object "NTAccess.CFGroups"

Property : Server : The UNC Name of the server holding the user group accounts, normally the Primary Domain Controller (PDC), but doesn't have to be. Can be left blank if the web server is also the server with the user accounts.
```
Examples
ntg.Server = ""
ntg.Server = "\\TheServer"
ntg.Server = "\\AnotherServer"
```
Property : Global : If set indicates that global groups are to be checked, rather than local groups. This defaults to FALSE, note that only domain controllers have global groups.
```
Examples
ntg.Global = false
ntg.Global = true
```
Property : TrimErrorCodes : This defaults to FALSE, and all error descriptions returned by err.description will have a trailing CR & LF sequence at the end, set this property to TRUE to stop this.
```
Examples
ntg.TrimErrorCodes = True
ntg.TrimErrorCodes = False
```
Property : LocalServerName : This read only property returns the name of the local server in UNC format ( e.g. \\WebServ1 )
```
Examples
response.write "Server : " & ntg.LocalServerName
```
Property : LocalDomainName : This read only property returns the name of the domain or workgroup that the local server is a member of ( e.g. WestCostOps )
```
Examples
response.write "Server Domain : " & ntg.LocalDomainName
ntg.Server = ntg.GetDomainController(ntg.LocalDomainName)
```
Property : GroupComment (GroupName) : This returns, or sets the comment field for the specified group. A standard COM error is thrown if the group doesn't exist, or you don't have the required rights to change the comment field.
```
Examples
ntg.GroupComment("Domain User") = "Every user in the domain"
response.write ntg.GroupComment("Domain Admins")
```
Function : GetDomainController (domain, PDConly) : This sets the Server property to the name of a domain controller for the specified domain. if PDConly is true, then the function will only return the name of the PDC not of any of the BDC's. PDConly is an optional parameter and defaults to false.
```
Example
ntg.GetDomainController("OurDomain")
ntg.GetDomainController("OurDomain", true)
```
Function : StripDomain InString : This take a NT Domain and Username string ( as returned by REQUEST("LOGON_USER")), and strips the domain name part of the string away. The username part of the string is returned.
```
Example
Welcome <% = ntg.StripDomain(request("LOGON_USER")) %>
```
Function : IsMember (User, Group, CheckGroup) : This searches the user groups to see if User is a member of the Group group. CheckGroup determines how this search is performed. If CheckGroup is false, then the group list for the user is searched for the group. If CheckGroup is true, then the user list for the specified group is searched, if the group contains another group, then this is also searched, where permitted, this includes checking global groups on different domains. As of v1.40 this function will strip the user name as required, so you can always pass users as "domain\user". Both modes (i.e. either setting of CheckGroup) now checks for indirect local group membership, so either mode should now return the same results. In testing using CheckGroup = FALSE, performed much faster.
```
Examples
if ntg.IsMember("Support\WebUser1", "PremiumArea1" , true) then
	response.write "<a href=""/premiumArea1/"">Members Only</a>"
end if
if ntg.IsMember(request("LOGON_USER"), "Sales" , false) then
	response.write "<a href=""/sales/"">Sales Team Home Page</a>"
end if
```
Function : AddUserToGroup User, Group : This adds the specified user to the specified group. The group can be local or global depending upon the global flag. Account operator or administrator privilege's are required for this function to succeed.
```
Examples
ntg.AddUserToGroup ntg.StripDomain(request("LOGON_USER")), "Sales"
ntg.AddUserToGroup "DialUp101", "DialUpUsers"
```
Function : DeleteUserFromGroup User, Group : This removes the specified user from the specified group. The group can be local or global depending upon the global flag. Account operator or administrator privilege's are required for this function to succeed.
```
Examples
ntg.DeleteUserFromGroup ntg.StripDomain(request("LOGON_USER")), "Sales"
ntg.DeleteUserFromGroup "DialUp101", "DialUpUsers"
```
Function : GetServerType : This returns a number which represents details about the server, each bit in the return value represent different functions, see the example script for details of the bit maps.
Function : UserCount (GroupName) : This returns the number of user accounts in the specified user group. It also retrieves the list of account names, which can be accessed via the UserItem function.
```
Example
for i = 0 to ntg.UserCount("Domain Users") - 1
	response.write ntg.UserItem(i)
next
```
Function : UserItem (index) : This returns the user account name at the specified index into the table of names, UserCount(GroupName) must be called first to establish the table.
```
Example
for i = 0 to ntg.UserCount("Power Users") - 1
	response.write ntg.UserItem(i)
next
```
Function : GroupCount (UserName) : This returns the number of user groups that the specified user belongs to. It also retrieves the list of group names, which can be accessed via the GroupItem function.
```
Example
for i = 0 to ntg.GroupCount("WebUser1") - 1
	response.write ntg.GroupItem(i)
next
```
Function : GroupItem (index) : This returns the group name at the specified index into the table of group, GroupCount(UserName) must be called first to establish the table.
```
Example
for i = 0 to ntg.GroupCount("DialUp101") - 1
	response.write ntg.GroupItem(i)
next
```
Function : GroupListCount : This returns the number of user groups located on the server specified by the server property, the global property specificy whether these are local or global groups. The actual Group names are returned by the GroupListItem function.
```
Example
for i = 0 to ntg.GroupListCount - 1
	response.write ntg.GroupListItem(i)
next
```
Function : GroupListItem (index) : This returns the group name at the specified index into the table of groups, GroupListCount must be called first to establish the table.
```
Example
for i = 0 to ntg.GroupListCount
	response.write ntg.GroupListItem(i)
next
```
Function : NewGroup GroupName, GroupComment : This adds a new local or global group with the specified name and comment.
```
Example
ntg.NewGroup "WebGroup1","Auto Created by NTAccess.Groups"
```
Function : DeleteGroup GroupName : This deletes a local or global group with the specified name, will still be deleted even if there are still entries in the group.
```
Example
ntg.DeleteGroup "WebGroup1"
```
Function : SetUsersPrimaryGroup UserName, GroupName : This sets the users primary group to be the global group specified. The user must already be a member of the group.
```
Example
ntg.SetUsersPrimaryGroup "fblogs01", "Domain Users"
```