This sample demonstrates how to modify the standard DPA login dialog box used with the Distributed Password Authentication (DPA) Security Support Provider (SSP) on a client's computer. This dialog box appears with the label Sign In when an SSPI negotiation identifies DPA as the SSP to the client for a particular realm. The DPA SSP is installed, along with the necessary SSPI libraries, with Microsoft® Internet Explorer version 3.0 or later. The DPA SSP allows for modification of the resources for this standard dialog box by providing a per-realm registry key and value that can point to a dynamic-link library that contains the desired custom resources. These customizable resources include the text that appears before the text boxes to collect the user name and password, the error text displayed in a few cases, as well as the help string that appears below the bitmap. The bitmap itself, being simply a resource, can be modified as well. However, the size and layout of the login screen cannot be altered. A complete list of the customizable resources is given in the following section.
The source can be found in the directory <sdk install root>\Samples\Microsoft Site Server\PM\customui\.
The following table lists the files that make up the DPA Custom Login User Interface sample, along with a brief description of the purpose of each.
| File name | Description |
| blank.bmp | This is a "placeholder" bitmap image. You could replace this bitmap with one of your choosing to provide custom identification. |
| config.reg | This is a standard REGEDIT4 registration file. It installs the appropriate entry in the client’s registry upon install. The sample version contains the entry
[HCLM\Software\Microsoft\MSAP\REALMS\MyRealmName] "DLLFile" = "samplerc.dll" You would replace the "MyRealmName" portion with the realm desired, and change the "DLLFile" value to the name of the DLL that implements the dialog box. For the sample, this file is called "samplerc.dll." |
| makefile | This is a standard makefile for the sample. It will rc compile the .rc file, the include file msapcdlg.h, and the bitmap to produce the DLL "samplerc.dll." Type nmake in the sample directory to compile the sample. |
| sample.rc | This file contains the text content for the various string resources, and the name of the bitmap file. This is the file you would most likely modify. Warning: Modify only the actual strings; do not modify the resource names for the strings! |
| setup.bat | This batch file is used to install the resource DLL into the proper location, and runs regedit on the .reg file included in the sample. This sets the proper registry key so that the resource DLL is loaded when the DPA dialog box is shown for a particular realm. |
| msapcdlg.h | This header file is located in the primary include directory of the SDK. It defines the resource IDs for the string resources used by the DPA login dialog box. Warning: Do not modify these values! |
The file Sample.rc contains all the text values for the string resources, as well as the name of the bitmap file. You can use this file as a template to create customizations for the dialog box, or use it just as an outline. The important items for the string table are listed in the following table.
| Resource | ID | Required? | Size | Description |
| SIGNIN | Yes | width: 160 pixels
height: 151 pixels |
This resource specifies the name of the bitmap to display. | |
| IDS_FRIENDLY_NAME | 1001 | no | <= 40 characters | This specifies the "friendly name" of the Realm. |
| IDS_USERNAME_LABEL | 1002 | no | <= 12 characters, including an & access key specifier | This specifies the text that appears to the left of the user name text box. You can specify the access key using the & symbol. |
| IDS_PASSWORD_LABEL | 1003 | no | <= 12 characters, including an & access key specifier | This specifies the text that appears to the left of the password text box. You can specify the access key using the & symbol. |
| IDS_SAVEPWD_LABEL | 1007 | no | <= 50 characters, including an & access key specifier | This specifies the text label for the Remember My Password check box. |
| IDS_ENTERNORP | 1004 | no | <= 128 characters | This specifies the text that appears in the "message" area of the dialog box, which is below the bitmap and the user name/password text boxes. |
| IDS_NOUSERNAME | 1005 | no | same as above | This specifies the text to be displayed in the message area if the user clicks OK before entering a user name. |
| IDS_NOPASSWORD | 1006 | no | same as above | This specifies the text to be displayed in the message area if the user clicks OK before entering a password. |
| IDS_PWDTOOSHORT | 1008 | no | same as above | This specifies the text to be displayed in the message area if the user clicks OK without providing a password with the required length (which is 1 character). |
A few of the resources require the designation of “hot keys” that highlight the associated text box from the keyboard. These keys are activated with the ALT and the key designated in the resource as lying just to the right of the &symbol.
For example
“&UserName”
designates ALT – U as the hot key for the user name text box.
You can use any bitmap editor of your choosing to create the bitmap that will identify the security realm visually to the user. The bitmap that accompanies the SDK is blank and is the correct size for the dialog box.
A makefile is included with the sample to make compiling the DLL simple. Make sure the proper environmental variables are set using VCVARS32.bat if required, and change directories to the sample directory. Then type nmake. Type nmake clean to remove old compiles before modifying the sample and compiling again.
You can change the name of the resulting DLL by modifying the makefile itself. The DLL name defaults to samplerc.dll. If you change the name of the DLL, you will also need to modify the config.reg and the setup.bat files as well to reflect the new name of the DLL.
To install the sample resources, copy the samplerc.dll compiled DLL, the config.reg, and the setup.bat file to a computer with Internet Explorer 3.0 or later installed. Execute the setup.bat file from the command line. This script will place the DLL in the appropriate directory for the target machine, and update the registry to reflect the presence of the DLL for this realm.
If you have an Internet Information Server 4.0 instance mapped to a Membership Authentication Service using the DPA security package, attempt to access a page through the Web server using the Internet Explorer browser. Make sure that either anonymous access is turned off for the Web server, or the page requires credentials to view. The customized Sign In dialog box should appear on the client machine with the new bitmap and text, prompting the user for credentials. You can enter a valid user name and password that exist in the corresponding Membership Directory Service to authenticate, and if successful, the resource should be returned to the browser.