Class BrokServers

Programmatic Identifier

MemAdmin.BrokServers.1

CLSID

cd8f114e-c4ac-11d0-bbda-00c04fb615e5

COM Class Name

Brokservers

Type Library Name

Brokcfg 1.0 Type Library

Type Library Location

c:\Microsoft Site Server\bin\P&M\brokcfg.dll

Threading Model

“Both”

The BrokServers COM class defines an object that can be used to examine and configure information relating to Membership Authentication service instances.  This includes the mappings to Application service instances, IIS metabase information and authentication packages.

If the object is created directly, then methods exposed through the interface become “read-only.” Administrators must use the special ObjCreator COM class to create an instance of this class using the CreateObjAuth method to render it “read/write”.  Once the object has been created using this method, the calling process or thread invoking methods must also have Windows NT administrative privileges for them to succeed.  If not, attempts to alter object properties and invoke methods that update the service instances configuration will return the E_ACCESSDENIED HRESULT value.

Interfaces

The BrokConfig COM class exposes the IBrokServers dual interface, exposing both a custom COM interface and a dispinterface to its properties and methods.

Interface IBrokServers

ClearMapping

The ClearMapping method clears a mapping of a Membership Authentication service instance to a specified Application service instance. (e.g. "W3SVC", 1)

IDL Definition

HRESULT ClearMapping(
BSTR bszServiceName, 
LONG lVirtServId 
);

Parameters

bszServiceName

The application service name (e.g. “W3SVC”)

lvirtServId

The Membership Authentication service instance identifier.

Return Values

A standard HRESULT value

Example

Set ObjCreator = CreateObject("ObjCreator.ObjCreator.1")
Set BrokServers = ObjCreator.CreateObjAuth("MemAdmin.BrokServers.1")
BrokServers.CleapMapping "W3SVC" , "1"

CreateServer

The CreateServer method creates a new Membership Authentication service instance.

IDL Definition

HRESULT CreateServer([out] VARIANT* plVirtServId);

Parameters

plVirtServId

on return, the address of a VT_I4 variable containing the new Membership Authentication service instance identifier.

Return Values

A standard HRESULT value

Example

Set ObjCreator = CreateObject("ObjCreator.ObjCreator.1")
Set BrokServers = ObjCreator.CreateObjAuth("MemAdmin.BrokServers.1")
BrokServers.CreateServer InstanceID
WScript.Echo "New Instance: " & InstanceID

DeleteServer

The DeleteServer method deletes the Membership Authentication service instance.

IDL Definition

HRESULT DeleteServer(LONG lVirtServId);

Parameters

lVirtServId

The Membership Authentication server instance identifier of the instance to delete.

Return Values

A standard HRESULT value

Remarks

This method will return E_ACCESSDENIED unless the object was created using the ObjCreator COM class method CreateObjAuth and the calling process has Windows NT administrative privileges.

Example

Set ObjCreator = CreateObject("ObjCreator.ObjCreator.1")
Set BrokServers = ObjCreator.CreateObjAuth("MemAdmin.BrokServers.1")
BrokServers.DeleteInstance "3"

GetAuthTypes

The GetAuthTypes method returns an integer specifying the authentication security support provider packages configured in the specified IIS metabase path.

IDL Definition

HRESULT GetAuthTypes(
BSTR bszPath, 
[out, retval] LONG *plTypes
);

Parameters

bszPath

an IIS metabase path (e.g. "/LM/W3SVC/3/ROOT/dir1" )

plTypes

on return, an integer value specifying the configured authentication packages for this “URL.” The integer is a bit-wise "OR" of the allowed types. (See Below)

Return Values

a standard HRESULT value

Remarks

The integer is composed of an "OR" bit-mask of the values listed below. (e.g. val | val2 | val3 ).  The bits, all being powers of "2", are listed below in their base 10 integer equivalents.

The following definitions are available through the type library when using C/C++:

const LONG BROK_AUTH_TYPE_ANON =           0x0001;
const LONG BROK_AUTH_TYPE_PWDCOOKIE =      0x0002;
const LONG BROK_AUTH_TYPE_BASIC =          0x0004;
const LONG BROK_AUTH_TYPE_DPA =            0x0008;

Example

Path = "/LM/W3SVC/3/ROOT/dir1"
Set MemServers = CreateObject("MemAdmin.BrokServers.1") ‘ read-only

ltypes = MemServers.GetAuthTypes(Path)
‘ check for anonymous access
If ltypes and 16 Then
     wscript.echo “Anonymous Access Allowed”
End If
‘ now check for Membership SSPs
if ltypes And 1 Then
  wscript.echo "Automatic Cookie"
Elseif ltypes And 2 Then
  wscript.echo "HTML Forms Auth"
Else 
     If ltypes And 4 Then
       wscript.echo "Clear Text/Basic"
   End If
     If ltypes And 8 Then
      wscript.echo "DPA"
   End If
End If

GetSecurityMode

The GetSecurityMode method returns a BOOL value specifying whether Windows NT authentication is the configured mode for the service instance.  TRUE means that NTLM is set to handle authentication.  FALSE means that a Membership Authentication service instance is set to handle authentication. 

IDL Definition

HRESULT GetSecurityMode(
BSTR bszServiceName, 
LONG lVirtServId, 
[out, retval] BOOL *pbNTSecurity
);

Parameters

bszServiceName

the name of the service. (e.g. “W3SVC”)

lVirtServId

the corresponding service instance identifier (e.g. 3)

pbNTSecurity

on return, a BOOL value that is set to TRUE if Windows NT authentication is set for this instance or FALSE if a Membership Authentication service instance is providing authentication services.

Return Value

a standard HRESULT value

Example

Set MemServers = CreateObject ("MemAdmin.BrokServers.1") ‘ just reading
Type =  MemServers.GetSecurityMode("W3SVC",1)
If fIsNTMode Then
  wscript.echo "IIS Instance 1: NTLM for auth"
Else
  wscript.echo "IIS instance 1: Site Server Auth"
End If

GetServers

The GetServers method returns an array of all currently defined Membership server instance identifiers and their associated names.

IDL Definition

HRESULT GetServers(
[in,out] VARIANT* plVirtServIds, 
[in,out] VARIANT* pComments
);

Parameters

plVirtServIds

on return, a VT_ARRAY of LONG variables holding Membership server instance identifiers.

pComments

on return, a VT_ARRAY of BSTR variables holding Membership server instance names.

Return Values

A standard HRESULT value

Example

Set ObjCreator = CreateObject("ObjCreator.ObjCreator.1")
Set BrokServers = ObjCreator.CreateObjAuth("MemAdmin.BrokServers.1")

call BrokServers.GetServers(Ids, Names)
For i = LBound(Ids) to UBound(Ids)
 wscript.echo Ids(i)
 wscript.echo Names(i)
Next

HasNTAdminPrivilege

The HasNTAdminPrivilege method returns a successful HRESULT value if the calling process has Windows NT administrative privileges on the local machine. It returns a failed HRESULT value otherwise.

IDL Definition

HRESULT HasNTAdminPrivilege();

Return Values

A standard HRESULT value

Example

On Error Resume Next
Set ObjCreator = CreateObject("ObjCreator.ObjCreator.1")
Set BrokServers = ObjCreator.CreateObjAuth("MemAdmin.BrokServers.1")
'  Check error number to see if it succeeded
if Err.Number <> 0 Then
  wscript.echo "Error:  Account does not have proper credentials"
End If

HasWritePrivilege

The HasWritePrivilege method returns a success HRESULT value if the current user has the necessary privileges to update configuration settings.  This method will always return failed HRESULT values unless the object was created using the ObjCreator COM class through the CreateObjAuth method and the calling process has Windows NT administrative privileges.

IDL Definition

HRESULT HasWritePrivilege();

Return Values

A standard HRESULT value

Example

On Error Resume Next
Set ObjCreator = CreateObject("ObjCreator.ObjCreator.1")
Set BrokServers = ObjCreator.CreateObjAuth("MemAdmin.BrokServers.1")
BrokServers.HasWritePrivilege  
'  Check error number to see if it succeeded
if Err.Number <> 0 Then
  wscript.echo "Error:  Account does not have proper credentials"
End If

MappedTo

This method attempts to fetch the Membership Authentication Service instance and name that are mapped to an instance of a particular service.

IDL Definition

HRESULT MappedTo(
BSTR bszServiceName, 
LONG lVirtServInstId, 
[in,out] VARIANT* plVirtMemInstId, 
[in,out] VARIANT* pbszComment
);

Parameters

bszServiceName

The service name to find mapping for. (e.g. “W3SVC”)

lVirtServInstId   (e.g. 3)

The instance ID for the service specified by bszServiceName.

plVirtMemInstId

Upon return, a VT_I4 value containing the corresponding Membership Authentication server instance identifier.

pbszComment

Upon return, a VT_BSTR value containing the Membership Authentication server instance name.

Return Values

A standard HRESULT value

Example

Set ObjCreator = CreateObject("ObjCreator.ObjCreator.1")
Set BrokServers = ObjCreator.CreateObjAuth("MemAdmin.BrokServers.1")

BrokServers.MappedTo "W3SVC",1, MemVirtId, MemVirtName
wscript.echo "World Wide Web Service Virtual Server ID =1 mapped to "
wscript.echo MemVirtName & " which is Authentication server ID = " & MemVirtId

MapToBroker

The MapToBroker method maps a specified instance of a specified service to a Membership Authentication server instance.

IDL Definition

HRESULT MapToBroker( 
[in] BSTR bszServiceName, 
[in] LONG lVirtServInstId, 
[in] LONG lvirtMemInstId 
);

Parameters

bszServiceName

The service to map. (e.g. “W3SVC”)

lVirtServInstId

The instance ID for the service to map to a Membership Authentication server instance. (e.g. 3)

lVirtMemInstId

The Membership Authentication server ID to map the service to. (e.g. 4)

Return Values

A standard HRESULT value

Remarks

This method will return E_ACCESSDENIED unless the object was created using the ObjCreator COM class method CreateObjAuth and the calling process has Windows NT administrative privileges.

Example

Set ObjCreator = CreateObject("ObjCreator.ObjCreator.1")
Set BrokServers = ObjCreator.CreateObjAuth("MemAdmin.BrokServers.1")

BrokServers.MapToBroker "W3SVC", 1, 2
' this maps IIS instance 1 to Mem instance 2

SetAuthTypes

The SetAuthTypes method sets the authentication type for a specified IIS metabase URL. 

IDL Definition

HRESULT SetAuthTypes(BSTR bszPath, LONG lTypes);

Parameters

bszPath

the IIS metabase path to set the authentication type for. (e.g. "/LM/W3SVC/2/ROOT/dir1/dir2" )

lTypes

the security support provider packages to use for the associated path.  (See below) 

Return Value

a standard HRESULT value

Remarks

In C++, the const values listed below can be used to create the value to send the object in the lTypes parameter.  The can be combined in the standard bitwise "OR" to represent multiple types.  In higher level languages, one can pass the sum instead.

The typedef values found in the type library are listed below. 

const LONG BROK_AUTH_TYPE_ANON =           0x0001;
const LONG BROK_AUTH_TYPE_PWDCOOKIE =      0x0002;
const LONG BROK_AUTH_TYPE_BASIC =          0x0004;
const LONG BROK_AUTH_TYPE_DPA =            0x0008;

This information specifies the Security Support Provider (SSP) package allowed for this particular URL path.  This information is used to configure the IIS metabase. 

This method will return E_ACCESSDENIED unless the object was created using the ObjCreator COM class method CreateObjAuth and the calling process has Windows NT administrative privileges.

Example

Set ObjCreator = CreateObject("ObjCreator.ObjCreator.1")
Set BrokServers = ObjCreator.CreateObjAuth("MemAdmin.BrokServers.1")

tbasic = 4
tAnon = 1
ltypes = tbasic + tAnon
' this works because the values are bitwise, so no carrying is
'  required.
Path = "/LM/W3SVC/2/ROOT/dir1/dir2"
BrokServers.SetAuthTypes (Path,ltypes)

StartServer

The StartServer method attempts to start the specified instance of a Membership Authentication service instance.

IDL Definition

HRESULT StartServer ( [in] LONG  lVirtServId ) ;

Parameters

lVirtServId

The Membership Authentication server instance ID.

Return Values

A standard HRESULT value

Remarks

This method will return E_ACCESSDENIED unless the object was created using the ObjCreator COM class method CreateObjAuth and the calling process has Windows NT administrative privileges.

Example

Set ObjCreator = CreateObject("ObjCreator.ObjCreator.1")
Set BrokServers = ObjCreator.CreateObjAuth("MemAdmin.BrokServers.1")

BrokServers.StartServer 1   ' start server # 1

StopServer

The StopServer method attempts to stop the specified instance of a Membership Authentication service instance.

IDL Definition

HRESULT StopServer ( [in] LONG lVirtServId ) ;

Parameters

lVirtServId

The Membership Authentication service instance ID.

Return Values

A standard HRESULT value

Remarks

This method will return E_ACCESSDENIED unless the object was created using the ObjCreator COM class method CreateObjAuth and the calling process has Windows NT administrative privileges.

Example

Set ObjCreator = CreateObject("ObjCreator.ObjCreator.1")
Set BrokServers = ObjCreator.CreateObjAuth("MemAdmin.BrokServers.1")

BrokServers.StopServer 1 '   stops server # 1