[Previous] [Next] [Contents] [Index]
This chapter describes the functions for the Authorization Object for use with VBScript. It includes the following sections:
3.2 Function List
3.1 Overview
For more information, see the samples subdirectory of the NetCrusader/Web installation directory. The comtest.asp file shows examples of every function described in this chapter.
3.1.1 Conventions
NOTE:
All parameters are strings except where noted. In examples, strings are
often used in the parameters, but you can use variables instead.
3.1.2 Error Handling
All functions support standard COM exceptions.
The following sample code illustrates this.
Set myComObj = CreateObject("NetCAuth.NetCObj.1")
myComObj.InitModel mymodule.txt, "/", 0
myComObj.Authenticate("SamIam", "greeneggs")
Response.Write "LogOff failed.<br>"
Response.Write "Error # " & Err.Number & "Desc: " & Err.Description & "<br>"
End If
3.1.3 Functions that Write Cookies
The following functions write cookies:
Alternatively, you may turn on the Response buffer as follows:
Remember, too, that the user's browser must be configured to accept cookies if you use any of the functions that write cookies.
3.2 Function List
The functions are:
Authenticate
BecomeSelf
BecomeUser
CheckAccess
ChangePassword
CreateAttributeSchema
CreateUser
DeleteCredential
DeleteUser
GetGroupAttribute
GetGroupMembers
GetUserAttribute
GetPermissons
GetPrincipal
GetUserGroups
InitModel
Logoff
RemoveFromGroup
SetGroupAttribute
SetUserAttribute
SingleSignOn
AddToGroup
Adds a user to a group.
Syntax
AddToGroup(callerName, callerPassword, userName, groupName)
Parameters
Example
In the following example, the user CatInthehat is added to the group teller.
Set bankObj = CreateObject("NetCAuth.NetCObj.1")
BankObj.AddToGroup("superuser", "password", "CatInthehat", "teller")
Returns
If an error occurs, an error object is created. See Section 3.1.2 on page 18 for suggestions on error handling.
Authenticates the user with the Security Server. Creates a credential object in the local cache. See note about Response buffer in Section 3.1.3 on page 18.
Authenticate(userName, password)
Parameters
IN/OUT
Parameter
Description
IN
userName
A string representing the user name.
IN
password
A string representing the user password.
Example
In the following example, the user, SamIam, is logging in with the password greeneggs.
Set bankObj = CreateObject("NetCAuth.NetCObj.1")
bankObj.Authenticate("SamIam", "greeneggs")
Returns
If an error occurs, an error object is created. See Section 3.1.2 on page 18 for suggestions on error handling.
NOTE:
BecomeSelf and BecomeUser should be used together, as a pair, and
used only when making calls to set attribute values or when passing
credentials to a NetCrusader/CORBA environment
Syntax
If an error occurs, an error object is created. See Section 3.1.2 on page 18 for suggestions on error handling.
NOTE:
BecomeSelf and BecomeUser should be used together, as a pair, and
used only when making calls to set attribute values or when passing
credentials to a NetCrusader/CORBA environment It is important to call
BecomeSelf as soon as the identity has been successfully passed to the
CORBA object.
Syntax
If an error occurs, an error object is created. See Section 3.1.2 on page 18 for suggestions on error handling.
Verifies that a user has access permission to an object.
NOTE:
You must be authenticated (use the Authenticate or SingleSignOn
function) and then call the function InitModel before calling the
CheckAccess function.
Syntax
CheckAccess(objectName, desiredAccess)
Parameters
Example
Set bankObj = CreateObject("NetCAuth.NetCObj.1")
bankObj.InitModel "aBank", "/", 0
bankObj.Authenticate "SamIam", "greeneggs"
perm_v = bankObj.CheckAccess("/Checking", "v")
Returns
This function returns 0 if the caller does not have access permission to the object; non-zero otherwise.
Errors
If an error occurs, an error object is created. See Section 3.1.2 on page 18 for suggestions on error handling.
Changes a user's password. An administrator can change a user's password. A user can change his own password. When callerName and userName are equal, it is assumed that the user is changing his own password. In this case, callerPassword is the old password and newPassword is the new password.
Syntax
ChangePassword(callerName, callerPassword, userName, newPassword)
Parameters
Example
Set aComObj = CreateObject("NetCAuth.NetCObj.1")
aComObj.ChangePassword "admin", "foo", "user1", "hello"
MsgBox Err.Description
Returns
If an error occurs, an error object is created. See Section 3.1.2 on page 18 for suggestions on error handling.
Defines a custom attribute to the system.
Syntax
CreateAttributeSchema(caName, caPassword, attributeName, attributeType)
Parameters
NOTE:
All custom attributes are of the type string.
Example
myComObj.CreateAttributeSchema("admin", "foo", "DepartmentName", "g")
Returns
If an error occurs, an error object is created. See Section 3.1.2 on page 18 for suggestions on error handling.
CreateUser(adminName, adminPassword, userName, userPassword)
Parameters
Example
Set bComObj = CreateObject("NetCAuth.NetCObj.1")
bComObj.CreateUser "admin", "foo", "jsmith", "hello1"
MsgBox Err.Description
Returns
If an error occurs, an error object is created. See Section 3.1.2 on page 18 for suggestions on error handling.
Invalidates a credential in the cache.
NOTE:
This is an internal NetCrusader/Web function that should not generally
be used. Instead, to log off a user, use LogOff.
Syntax
DeleteCredential(user, reserved)
Parameters
IN/OUT
Parameter
Description
IN
user
The name of the user whose credentials are being removed from the cache.
IN
reserved
Reserved.
Example
aObj.DeleteCredential "CatinTheHat", ""
Returns
If an error occurs, an error object is created. See Section 3.1.2 on page 18 for suggestions on error handling.
Deletes a user account.
Syntax
DeleteUser(adminName, adminPassword, userName)
Parameters
Example
aComObj.DeleteUser "admin", "foo", "jsmith"
Returns
If an error occurs, an error object is created. See Section 3.1.2 on page 18 for suggestions on error handling.
Obtains the value of the named attribute for a group. Note that the name of the attribute (the schema definition) must have been created using CreateAttributeSchema.
Syntax
GetGroupAttribute(groupName, attributeName)
Parameters
IN/OUT
Parameter
Description
IN
groupName
The name of the group to whom the value is attached.
IN
attributeName
The name of the attribute.
OUT
value
A string containing the value of the attribute.
Example
aString = myComObj.GetGroupAttribute("managers", "budget")
Returns
A string containing the value of the named attribute.
Errors
If an error occurs, an error object is created. See Section 3.1.2 on page 18 for suggestions on error handling.
Obtains a list of members of a group.
Syntax
GetGroupMembers(groupName)
Parameters
IN/OUT
Parameter
Description
IN
groupName
The name of the group whose members you want to obtain.
OUT
memberList
An array of strings comprising a list of the members in the group.
Example
aString = myComObj.GetGroupMembers("Customers")
Returns
An array of strings comprising a list of the members in the group
Errors
If an error occurs, an error object is created. See Section 3.1.2 on page 18 for suggestions on error handling.
Obtains the value of the named attribute for a user. Note that the name of the attribute (the schema definition) must have been created using CreateAttributeSchema.
Syntax
GetUserAttribute(userName, attributeName)
Parameters
IN/OUT
Parameter
Description
IN
userName
The name of the user to whom the value is attached.
IN
attributeName
The name of the attribute.
OUT
value
A string containing the value of the attribute.
Example
aString = myComObj.GetUserAttribute("jsmith", "cellphone")
Returns
A string containing the value of the named attribute.
Errors
If an error occurs, an error object is created. See Section 3.1.2 on page 18 for suggestions on error handling.
Returns a string containing a concatenation of all the permission symbols for the object.
NOTE:
You must be authenticated (use the Authenticate or SingleSignOn
function) and then call the function InitModel before calling the
GetPermissions function.
Syntax
GetPermissons(objectName)
Parameters
IN/OUT
Parameter
Description
IN
objectName
The object name as defined in the ACL model.
OUT
permissions
A string containing permissions for the object.
Example
perm_set = bankObj.GetPermissions "Checking"
In this example, we create a variable called perm_set to hold the permissions returned by the call to check the permissions on the Checking object.
Returns
A string containing a concatenation of all the permission symbols for the object.
Errors
If an error occurs, an error object is created. See Section 3.1.2 on page 18 for suggestions on error handling.
NOTE:
You must be authenticated (use the Authenticate or SingleSignOn
function) before calling the GetPrincipal function.
Syntax
GetPrincipal()
Parameters
IN/OUT
Parameter
Description
OUT
principalName
A string containing the name of the user.
Example
Dim principal
principal = bankObj.GetPrincipal
In this example, we create a variable called principal to hold the principal name returned by the call.
Returns
The function returns a string containing the principal name of the user authenticated with the COM object before the method was called.
Errors
If an error occurs, an error object is created. See Section 3.1.2 on page 18 for suggestions on error handling.
Obtains a list of the groups to which a user belongs.
Syntax
GetUserGroups(userName)
Parameters
Example
aString = myComObj.GetUserGroups("jsmith")
Returns
An array of strings comprising a list of the groups to which the user belongs.
Errors
If an error occurs, an error object is created. See Section 3.1.2 on page 18 for suggestions on error handling.
Initializes a matched set of object and ACL models.
Syntax
InitModel(moduleName, modelRoot, traversePerm)
Parameters
Example
bankObj.InitModel "fbank", "/", "0"
In this example, fbank is the name of the module (the model file is called fbank.txt) and the ACL begins at the root.
Errors
If an error occurs, an error object is created. See Section 3.1.2 on page 18 for suggestions on error handling.
Logs the user off. See note about Response buffer in Section 3.1.3 on page 18.
If an error occurs, an error object is created. See Section 3.1.2 on page 18 for suggestions on error handling.
Removes a user from a group.
Syntax
RemoveFromGroup(callerName, callerPassword, userName, groupName)
Parameters
Example
Set aComObj = CreateObject("NetCAuth.NetCObj.1")
aComObj.RemoveFromGroup "admin", "foo", "jsmith", "ExecutiveStaff"
MsgBox Err.Description
Returns
If an error occurs, an error object is created. See Section 3.1.2 on page 18 for suggestions on error handling.
NOTE:
Before calling SetGroupAttribute, you must authenticate as a user
who has permission to manage the user or group. You must then call
BecomeUser, and then SetGroupAttribute. After you make the
SetGroupAttribute call, you must call BecomeSelf. To summarize:
authenticate, call BecomeUser, call SetGroupAttribute, and then call
BecomeSelf.
Syntax
SetGroupAttribute(groupName, attributeName, value)
Parameters
IN/OUT
Parameter
Description
IN
groupName
The name of the group to whom the value is attached.
IN
attributeName
The name of the attribute.
IN
value
A string containing the value of the attribute.
Example
Dim aString As String
aString = myComObj.SetGroupAttribute("managers", "budget", "unlimited")
A string containing the value of the named attribute.
Errors
If an error occurs, an error object is created. See Section 3.1.2 on page 18 for suggestions on error handling.
NOTE:
Before calling SetUserAttribute, you must authenticate as a user who
has permission to manage the user or group. You must then call BecomeUser,
and then SetUserAttribute. After you make the SetUserAttribute call, you
must call BecomeSelf. To summarize: authenticate, call BecomeUser, call
SetUserAttribute, and then call BecomeSelf.
Syntax
SetUserAttribute(userName, attribute name, value)
Parameters
IN/OUT
Parameter
Description
IN
userName
The user for which the value is being set.
IN
schemaName
The name of the attribute.
IN
value
The value of the attribute.
Example
Dim aString As String
myComObj.SetUserAttribute "jsmith", "phonenum", "01144-012345234"
If an error occurs, an error object is created. See Section 3.1.2 on page 18 for suggestions on error handling.
Returns the single sign-on credentials.
Syntax
SingleSignOn()
Parameters
IN/OUT
Parameter
Description
OUT
status
A string indicating whether the single sign-on succeeded or failed:
Example
A string indicating whether the single sign-on succeeded or failed.
Errors
If an error occurs, an error object is created. See Section 3.1.2 on page 18 for suggestions on error handling.
[Previous] [Next] [Contents] [Index]
To make comments or ask for help, contact support@entegrity.com.