NTAccess.User Readme

NTAccess.User : An ASP Component for NT User account management
Version : 1.41
Release Date : 14 March 1999
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.user allows a number of user account management functions to be performed from an ASP script, or 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 Nta_user.dll
If you are replacing an earlier version, remember to shutdown & restart IIS to reload the new version.

License Agreement
NTAccess.User is copyright (C) 1997-1999 by Simon Z. Fell

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 first getting a commercial license);
modifying the package.

All trademarks/registered names acknowledged.

NTAccess.User 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 ntu = Server.CreateObject("NTAccess.User")

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

Property : Server : The UNC Name of the server holding the user 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
ntu.Server = ""
ntu.Server = "\\TheServer"
ntu.Server = "\\AnotherServer"
```
Property : User : The name of the user account to perform any functions on. The Server and User properties must be set before any other functions can be called.
```
Examples
ntu.User = "Administrator"
ntu.User = "WebUser1"
ntu.User = REQUEST("LOGON_USER") 
```
Property : TrimErrorCodes : This defaults to FALSE, if set to true by the script any error codes returned by err.description have the trailing carage return and line feed characters removed, otherwise the error description string has a CR & LF sequence at the end
```
Examples
ntu.TrimErrorCodes = True
ntu.TrimErrorCodes = False
```
Property : FullName : This sets or retrieves the Users Full Name field from the user account.
```
Examples
response.write "Welcome " & ntu.FullName 
ntu.FullName = "Fred Flintstone"
```
Property : AccountComment : This sets or retrieves the Users Comment ( or Description ) field from the user account.
```
Examples
response.write ntu.AccountComment
ntu.AccountComment = "Added By Web Registration System"
```
Property : NeverExpirePassword : This sets or retrieves the Never Expire Password field from the user account. To set the property the account running the script must have account operator or administrator privileges.
```
Examples
if ntu.NeverExpirePassword then
	response.write "Your Password will not expire"
end if
ntu.NeverExpirePassword  = false
ntu.NeverExpirePassword  = true
```

Property : Disabled : This sets or retrieves the account disabled flag. To set the property the account running the script must have account operator or administrator privileges.

Examples
if ntu.disabled then
	response.write "Sorry your user account has been disabled"
	response.write "<BR>please contact the webmaster"
end if
ntu.Disabled  = false
ntu.Disabled  = true

Property : MustChangePW : This sets or retrieves the "User must change password at next logon" flag. Please note that use of this property invokes a overhead much larger than any other property, and is not cached with other properties. To set the property the account running the script must have account operator or administrator privileges.
```
Examples
if ntu.mustChangePW then
	response.write "You need to change your password before you can enter the site"
	response.redirect "changepassword.asp"
end if
ntu.mustChangePW  = false
ntu.mustChangePW  = true
```

Property : CantChangePassword : This sets or retrieves the User Can't Change Password flag. To set the property the account running the script must have account operator or administrator privileges.

Examples
if ntu.CantChangePassword then
	response.write "Sorry, only the administrator can "
	response.write "change the password for this account"
end if
ntu.CantChangePassword  = false
ntu.CantChangePassword  = true

Property : Lockout : This sets or retrieves the Account Lockout flag. To clear the property the account running the script must have account operator or administrator privileges. This flag can only be cleared it cannot be set
```
Examples
if ntu.Lockout then
	response.write "Sorry, your User account has been "
	response.write "locked out, please contact the webmaster"
end if
ntu.Lockout = false
```

Property : HomeDir : The path to the user account home directory.

Examples
ntu.HomeDir = "c:\users\" & ntu.User
ntu.HomeDir = "\\Server1\users\Fred"
response.write "Your home directory is " &  ntu.HomeDir

Property : HomeDirDrive : The drive that the users home directory is mapped to.

Examples
ntu.HomeDirDrive = "u:"
ntu.HomeDirDrive = ""
response.write "Your home directory is mapped to " &  ntu.HomeDirDrive

Property : ScriptPath : The location of the account logon script.

Examples
ntu.ScriptPath = "c:\users\logon.bat"
ntu.ScriptPath = "\\Server2\netlogon\main.bat"
response.write "Your Logon Script is " &  ntu.ScriptPath

Property : ProfilePath : The users profile path.

Examples
ntu.ProfilePath = "c:\users\"
response.write "Your Profile Path is " &  ntu.ProfilePath

Property : AccountExpiry : Returns the date/time that the users account will expire, or will return 1 for never expires.

Examples
ntu.AccountExpiry = "1/1/1999"
ntu.AccountExpiry = 1
response.write "Your account expires on " & ntu.AccountExpiry

Function : GetDomainController (domain, PDConly) : This sets the Server property to the name of a domain controller for the specified domain. if PDConly is set to true, then the search is limited to the PDC only.
```
Example
ntu.GetDomainController("OurDomain", true)
ntu.GetDomainController("OurDomain")
```
Function : AddUser NewUserName , Password, Comment : This adds a new user account to the system. The account is set with the passed comment and password. The account running the script must have account operator or administrator privileges. .
```
Examples
ntu.AddUser "WebUser22" , "DefaultPassword", "Added Web Registration System"
ntu.AddUser "DialIn99" , "DialUpPassword", "For Network DialIn Access"
```
Function : DeleteUser : This deletes the user account specified by the User property. The account running the script must have account operator or administrator privileges.
```
Example
ntu.User = "DialIn99"
ntu.DeleteUser
```
Function : Rename : This renames an existing user account specified by the User property, to the new value. The account running the script must have account operator or administrator privileges.
```
Example
ntu.User = "Guest103"
ntu.Rename "Customer56"
```
Function : ChangePassword OldPassword, NewPassword : This changes the password for the user account specified by the user property.
```
Example
ntu.User = "DialIn99"
ntu.ChangePassword "DialUpPassword" , "NewPassword"
```
Function : GetMaxPasswordAge : This returns the maximum age for passwords in seconds. ( This is set from the Account Policy in User Manager ). If Password expiry is not enabled it will return -1. Password expiry can be overridden on an account by account basis by using the Never Expire Passwords option.
```
Example
MaxAge = ntu.GetMaxPasswordAge
if MaxAge > -1 then
	response.write "Max Password age : " & (MaxAge\86400) & " days"
else
	response.write "Password Expiry not enabled on this server"
end if
```

Function : GetPasswordAge : This returns the number of seconds since the password has been changed (for the account specified by the user property). This will return -1 if the never expire passwords flag is set.Can be used with GetMaxPasswordAge to warn of impending password expiry.

Example
MaxAge = ntu.GetMaxPasswordAge
if MaxAge > -1 then
	pwAge = ntu.GetPasswordAge
	if pwAge > -1 then
		TimeLeft = (MaxAge - pwAge)\86400
		if TimeLeft < 14 then
			response.write "Your Password will expire in "
			response.write TimeLeft & " days, please change it"
		end if
	end if
end if

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
ntu.User = ntu.StripDomain(request("LOGON_USER"))
```
Function : UserLogon DomainName , Password, FullLogon : This performs a Logon request, and can be used to validate user accounts against the NT user account database. The User account to logon is specified by the user property. if FullLogon is false, the account is validated but the thread running the script continues to run under the original account. If FullLogon is true, the user is logged in and the thread running the script runs under the logged in account. This can be useful in circumstances where administrator privileges are required ( say to add a user ), but you don't want to give the IUSR_SERVER account administrator privileges.
```
Example
ntu.User = "WebAdmin"
ntu.UserLogon "" , "WebAdminPassword" , true
ntu.Adduser request("UserName") , request("Password") , "Web Registration"
```
Function : UserLogoff : Thsi functions logs out the user previous logged in with UserLogon, the reset of the script continues to run as the original user account (typically IUSR_ComputerName). The user will be automatically logged off at the end of the script if UserLogoff is not explicitly called.
```
Example
ntu.User = "WebAdmin"
ntu.UserLogon "" , "WebAdminPassword" , true
ntu.Adduser request("UserName") , request("Password") , "Web Registration"
ntu.UserLogoff
```
Function : GetThreadUserName : This returns the name of the user account which is currently running the script. This is mainly used for debugging.
```
Example
response.write ntu.GetThreadUserName
```
Function : UserCount : This returns the number of user accounts on the specified server. It also retrieves the list of account names, which can be accessed via the UserItem function.
```
Example
for i = 0 to ntu.UserCount - 1
	response.write ntu.UserItem(i)
next
```

Function : UserItem (index) : This returns the user account name at the specified index into the table of names, UserCount must be called first to establish the table.

Example
for i = 0 to ntu.UserCount - 1
	ntu.User = ntu.UserItem(i)
	response.write "<TR><TD>" & ntu.User & "<TD>"
	response.write "<TD>" & ntu.FullName & "</td>"
	response.write "<TD>" & ntu.AccountComment & "</td></tr>"	
next

Function : ResetPassword "NewPassword" : This changes the users password to the specified string without having to know the old password. Administrator privileges are required for this to work.
```
Example
ntu.ResetPassword "DonaldDuck"
```
Function : CopyUser "SourceUserName", "NewUserName" : This creates a new user account with the username "NewUserName", the users configuration is a copy of the "SourceUserName"'s account. Administrator privileges are required forthis to work.
```
Example
ntu.CopyUser "userTemplate", "DDuck99"
```
Property : localServerName : This returns the UNC name of the computer the component is running on ( e.g. \\WebServ1 ).
```
Example
response.write ntu.localServerName
```
Property : localDomainName : This returns the name of the domain or workgroup the computer is a member of.
```
Example
response.write ntu.localDomainName
```