Editor's Note: Each month, this column discusses various aspects of e-commerce with Microsoft Site Server 3.0. This month's column examines automating some advanced features of Site Server's Personalization and Membership (P&M) feature with Windows Scripting Host (WSH) technology in the command-line-based script host (cscript.exe)
In my previous articles, I showed you some advanced configurations of Site Server 3.0 and its P&M features, including how to build a Site Server 3.0 Membership Directory Service (DS), map it to a Web server, and use a WSH script to apply an authentication architecture to the Web site. This month, I show you how to
- Add custom attributes to the Membership DS schema
- Add those custom attributes to the Members container to make them available to each person in the DS
- Add custom Membership groups to the DS schema
To make the process more interesting, I completely automate it with WSH technology in the Command Line Scripting Utility (cscript.exe).
As I described last month, any company with a Web farm has to have an automated process for bringing up new Web servers. With the added complexity of a DS, building and configuring those Web servers manually would take too long to get them into production. SetupDS.vbs completely automates the process for bringing new servers into production.
Examining the Technology
Let's take a look at how SetupDS.vbs works before I show you how to run it. (SetupDS.vbs is too long to print here—more than 1000 lines of code—so I just include excerpts in this column. You can find the entire script and supporting files in the Code Library of the IIS Administrator Web site at http://www.iisadministrator.com. Download the script now so that you can refer to it as you read the article.)
I'm a firm believer in commenting code, especially in a WSH script, so the first 35 lines of this script are comments about its functionality. Next, I declare a number of constants that I use and then the variables that are global to the entire script. When the code starts, I make sure the user has included all nine parameters you see on pages 9 and 10 when calling this script. If the user simply finds this script on a share and executes it, the script will display help about how to use it. (It's also good practice to display help in a WSH script even if you haven't supplied any parameters. In this case, displaying help instead of running the script without parameters will prevent an accidental failed configuration of a Membership server.) If any parameter is missing, the script outputs to the command window the syntax and proper format of the parameters that SetupDS.vbs requires. I describe each of the nine parameters later in the article.
The main body of the program begins at line 170. I declare all the supporting functions under the main body. If you examine the main body of the program, you'll see that the process of configuring the DS consists of four main steps:
I declare all four steps as public functions. In addition, all the steps return a status of the results and depend on the preceding function to succeed.
Public function BindAsUser binds a user who has rights to modify the Site Server 3.0 P&M DS. The trouble I had with this function illustrates a common problem that many software developers have with the concept of a security context in multitiered (Microsoft Windows Distributed interNet Applications—Windows DNA—architecture) programming. For many other projects, I've encapsulated most functions that this script uses into either Active Server Pages (ASP) or middle-tier Microsoft COM objects. I've used BindAsUser on many projects and never had a problem, but when I added it to this script, I received a security violation. Why? In all the ASP I wrote that included this function, I forced an authentication on the page. When users ran the page, they authenticated as DS administrators. Consequently, they ran the ASP under the security context of a DS administrator.
A similar situation existed when I encapsulated the BindAsUser function in middle-tier COM objects. I always run out-of-process components under the framework of Microsoft Transaction Server (MTS) for thread and connection pooling (which is definitely beyond the scope of this article). In this case, I use the MTS Identity property to run my COM objects under the security context of a Windows 2000 (Win2K)/Windows NT server administrator. If I run a WSH script from a command prompt, I'm not running under any security context or identity that has rights related to the DS. I'm not even running anonymously (which is the default if I were running under IIS). When I figured out what was happening, I did a little research on the OpenDSObject method. I changed the syntax of my call to include
- The root path of the DS (LDAP://servername:1003/o=realmname)
- The absolute format of the administrator's domain name (i.e., cn=Administrator, ou=Members, o=realmname)
- The administrator's password
- A constant (i.e., 0—other possible values 1 and 2 aren't applicable to the Site Server P&M DS)
The following format let me bind under the security context of the DS administrator, even though I was running the script from the command line.
Set g_objRoot = _ openObject.open _ DSObject(g_strRoot _ Path, "cn="& _ strUser &", _ou=Members, _ o=" & g_strOrgName, _ strPW, 0)
Public function PopulateSchemaAttributes adds the custom attributes to the DS. In this function, I use ActiveX Data Objects (ADO) to open a Microsoft SQL Server table named DSAttributes. You can download from the IIS Administrator Web site Code Library the SQL script to create DSAttributes and a Comma Separated Values (CSV) file with the data. Using SQL script makes the function more robust and provides the read-only data necessary for the drop-down lists you need for your site's management pages.
To create the DSAttributes table, run the SQL Server 7.0 Query Analyzer or SQL Server 6.5 query tool, then load this script and execute it. Next, use the SQL Server 7.0 import and export tool (Data Transformation Services—DTS—Wizard) to load the data. You can import the CSV file with the import tools in SQL Server 6.5 also.
The DSAttributes table, which Screen 1 shows, contains the names of attributes that the SetupDS.vbs script creates. The table also contains the names of attributes that already exist in the DS by default—my code ignores those names by design. As in my previous articles, I use the example of the Subscribers Only section on the IIS Administrator Web site. In this case, I add three attributes that are in the DSAttributes table:
subscriptionCode—the code or number assigned to each subscriber
subscriptionStart—the first issue a subscriber receives
- subscriptionEnd—an issue in the future that represents the last issue that will be sent to the subscriber
This example isn't an architecture that you would use in real life because Site Server P&M has a property that lets a member expire automatically from a group. Unfortunately, this feature is the only one I know of in Site Server P&M that didn't make it as a feature in the Win2K Active Directory (AD).
As I explained in the previous articles, adding an attribute to the schema isn't enough. After you add the schema, you need to make it available to the Members container. Public function AddAttributesToMembers does just that.
Like the PopulateSchemaAttributes function, AddGroupsToDS uses ADO to open a SQL Server table named DSGroups. You can download from the Code Library of the IIS Administrator Web site the SQL script to create DSGroups and a CSV file with the data. The DSGroups table contains the names of the Membership Groups that SetupDS.vbs creates. In this case, I'll create a DS group called Subscriptions, which will house all the subscribers to IIS Administrator. Site Server P&M automatically creates a Win2K/NT shadow group so that you can secure content by setting ACLs on files and folders. When you've run the SetupDS.vbs script and the Subscriptions group exists, P&M creates a group in the naming format of site_realmname_groupname in Win2K or NT.
Before you can run SetupDS.vbs, you need a Membership server that is mapped to a Web site. Refer to "How to Use Site Server's P&M Features," November 1999, for instructions about how to set up a Membership server through the Microsoft Management Console (MMC), or refer to "Advanced Personalization and Membership Features with WSH Scripting Technology, Part 1," March 2000, to set up a Membership server automatically with a WSH script.
When you run SetupDS.vbs, the script uses the wscript.echo command to output results to the command console window. If you run SetupDS.vbs with the default of 25 lines per screen, the number of lines of output will exceed the number of lines that window displays (25), so the initial lines of output scroll off the screen. If you want to prevent the SetupDS.vbs script from spilling the output it renders off the screen, you can extend the size of your command console window. Go to the Control Panel Console applet, and click the Layout tab. Change the height in the Screen Buffer Size to at least 50. This new screen buffer size forces the command prompt to remember 50 lines, even if they've scrolled by. Also change the height in the Window Size to 50 if your screen resolution supports it. This new window size effectively doubles the size of the command prompt window. Click OK to save the changes.
Download SetupDS.vbs, and place the script in a share on your Site Server. Run a command prompt (in Win2K, choose Start, Programs, Accessories, Command Prompt), and change to that directory. Now, you're ready to run the script. Here's the syntax:
SetupDS.vbs username password _ web-instance-number _ membership-instance-number _ server-name port-number dsn _ dbUser dbPassword
For example, on my server, I used the following format:
Cscript SetupDS.vbs _ Administrator password _ 1 2 INTERKNOWLOGY _ 1003 IISAdmin sa ""
- Administrator refers to the DS user who has privileges to modify the DS.
- password is the Administrative password of the new Membership server. (This password isn't the NT Administrator's password, but the password for the DS user who is modifying the DS.)
- 1 refers to the Default Web site (or the first instance of a Web server) to which the Membership server is mapped. You can determine the instance number of a Web server or Membership server by opening the Site Server Service Admin (MMC) snap-in and counting the instances starting from the top and moving down. For example, Default Web Site is the first Web server on Site Server. Beneath Default Web Site is the Administration Web site, which is the second instance of a Web server. If you add another Web server, it becomes the third instance.
- 2 refers to the second instance of a Membership server. If you look under the Personalization and Membership snap-in, you'll see the Default Intranet (NT authentication) Membership server, which is the first instance of a Membership server. If you create another Membership server, which you will for the SetupDS.vbs script in this article, it will be the second instance and appear directly under the first instance.
- INTERKNOWLOGY is the name of the Win2K/NT server on which you're running Site Server P&M.
- 1003 is the Lightweight Directory Access Protocol (LDAP) port number on which the Membership server communicates. If you've forgotten the LDAP port on which your DS communicates, you can quickly obtain it by right-clicking the Membership Directory Manager (MDM) snap-in of the Site Server Service Admin (MMC) connected to your Membership server, then selecting Properties.
- IISAdmin is the Data Source Name (DSN) that communicates with the SQL Server database housing the DSAttributes and DSGroups tables.
- sa is the SQL Server account with rights to the SQL Server database.
- "" is the SQL Server account password with rights to the SQL Server database. Don't use the quotation marks if your password isn't blank.
Modify the parameters to conform to your server, and execute SetupDS.vbs. Screen 2, page 9, shows the wscript.echo statement from the script execution. It took less than 10 seconds for the script to run on my notebook, on which Site Server and SQL Server 7.0 are running with Windows 2000 Advanced Server (Win2K AS). I included some simple screen I/O in the code so that you can monitor what's happening.
Now, let's examine what the script did. Access the Site Server Service Admin (MMC) by choosing Start, Programs, Microsoft Site Server, Administration. Navigate to the Membership Directory Manager snap-in, and click ou=Admin, then cn=Schema, as Screen 3 shows. Notice the three new subscription attributes that you added to the schema. Now, scroll down the schema list until you see the cn=member container. Double-click the container, then click the Class Attributes tab. Notice that the three subscription attributes have been added to the Member container, as Screen 4 shows. Now, navigate to the ou=Groups folder, which Screen 5 shows. Notice that the cn=Subscribers group now appears in the default list of groups.
If you're using NT, run the User Manager (Start, Programs, Administrative Tools, User Manager). Navigate to Groups, and you'll see the shadow group, which appears in the format site_realmname_Subscribers. If you're using Win2K, run the Active Directory Users and Computers tool (Start, Programs, Administrative Tools, Active Directory Users and Computers). Navigate to the Users folder. Click the Type column to sort the users from the Groups. You'll find the group you just created. In my case, the group is Site_Pacific_Subscribers, where
- Site is the default for all shadow groups
- Pacific is the name of the realm of my DS
- Subscribers is the name of the Site Server P&M group
CreateDS.vbs and SetupDS.vbs
I made the SetupDS.vbs WSH script robust enough to run many times without damaging the DS. When you combine SetupDS.vbs with CreateDS.vbs from last month's article, you have automated power over your Site Server P&M DS.