Cover V11, I11

Figure 1
Figure 2
Figure 3
Figure 4


PAM-like Authentication for Windows Clients

Nathan Yocom

Most derivatives of UNIX come with support for Pluggable Authentication Modules (PAM). UNIX boxes can authenticate users in a multitude of ways with PAM. However, if you put a machine running Microsoft Windows NT/2K/XP into the same authentication framework, you will encounter problems. The solutions currently available range from emulation of a domain controller with Samba, to various scripts and back-ends that replicate account information between heterogeneous hosts.

In the Computer Science department where I work, students receive and use accounts on our Solaris server, but many students also need access to machines with Microsoft Windows. To allow this, and still utilize our Solaris server as an authentication and storage point, I have worked with a colleague to create the GPL'd pGina ( Through the use of this replacement GINA for Windows and community-developed plugins for authentication, this tool, in some situations, can replace a Microsoft Windows Domain with other standard authentication methods. Figure 1 shows the ideal single-point authentication framework I was looking for, while Figure 2 shows what I would have had to do using currently available and mostly non-GPL methods.

What Is a GINA?

GINA stands for "Graphical Identification aNd Authentication", and is an extension loaded by the Winlogon.exe process, which is responsible for presenting the login dialog box, and handling SAS (typically CTRL+ALT+DEL) sequences. By using the freely available Windows Platform SDK, it is possible to write a replacement GINA library that functions however you like. pGina is exactly that -- a custom GINA interface that loads plugins that conform to an open standard to provide for modular authentication and identification (thus, pluggable Graphical Identification aNd Authentication, or pGina). With the use of pGina, we authenticate our Windows machines against an OpenLDAP schema running on our Solaris server. In this article, I'll describe what pGina does, then set up a system to authenticate against an LDAP server.

How Does pGina Work?

To begin, let's walk through a normal user login using pGina. After the user has entered his or her username and password, pGina passes that information, along with configuration settings, to a plugin. The plugin then determines whether the user is to be allowed access and can set up different options on a per-user basis. Once the plugin authenticates a user and has filled in any optional information fields (such as full name, description, administrator status, etc.), pGina regains control and continues with the login process.

Depending on how pGina is configured, a few different things can happen. For example, in classrooms and labs, we generally enforce a default profile and do not save changes that are made to a profile while logged in. pGina is configured so that every time a user logs in, he inherits a copy of the Default User profile. Therefore, pGina first creates a local user account with the username and password of the authenticated user, during which Windows gives the user a copy of the Default User profile. Upon logging out, pGina will delete both the local user and the corresponding profile, thereby removing any changes and customizations the user may have made. Conversely, in our faculty offices, we want users to be able to maintain a custom profile, so we set up pGina not to delete the user or profile upon logout.

pGina, through local user profile and settings management, tries to make a system behave as though it were on a domain. pGina can be configured in a variety of ways to make this happen -- through profile management, user groups, administrator flags, and even password management.

What You Need

To implement a similar framework in your environment, you must have:

1. An authentication service (for this example, I will use OpenLDAP)

2. pGina and the LDAPAuth Plugin (available at:

3. A Windows 2000/XP machine with Administrative access for testing


The first thing to set up is on the server side. Setting up OpenLDAP is well documented in other articles and resources, so for the sake of brevity, I will assume you have a working schema that authenticates ldap_bind() attempts. Other LDAP servers will work as well, however, we use OpenLDAP because it is open source and freely available.

To begin, install the core of the new framework, pGina and the LDAPAuth plugin. (As of this writing, the most current revision of pGina is 1.3, so substitute the current revision accordingly.) As a local administrator on the Windows machine, do the following:

1. Ensure that the machine is not part of a domain; if it is, remove it.

2. Download and run pGina130.exe. This is a standard installation routine, and for this example, the defaults should suffice. pGina and an example plugin should now be installed.

3. Download and run ldapauth.exe from the pGina Web site.

Again, this is a pretty standard installation; be sure that the path for installation corresponds to the one you chose in step 2 (the default).

pGina and the LDAP plugin are now installed, but not configured. Do not reboot until you have configured them.

Plugin Configuration

Unfortunately, as of this writing, the LDAP plugin does not have a nice GUI configuration box. Run regedit (Start->Run->"regedit") and navigate to the HKLM\SOFTWARE\pGina\ldapauth key. Here we will place the appropriate LDAP settings for authentication.

The LDAP plugin has a variety of options that should allow a fit regardless of your schema configuration. For the sake of brevity, I will discuss the basic settings necessary for this example, but a complete list of the available options is on the pGina Web site. Each of the following values should be added to the registry key as strings:

ldapContext0 -- "dc=something,dc=here"

ldapMethod -- "1"

ldapPrePend -- "uid="

ldapServer -- "" useSSL = "0"

The ldapContext0 string indicates the LDAP context with which the plugin should connect. ldapMethod indicates the method of binding that should be used (see documentation on the pGina Web site for other options). ldapPrepend is the string to be pre-pended to the username. ldapServer is the server to authenticate against. useSSL indicates whether the request should be tunneled through SSL. For now, this example shows how to set things up without SSL. Later, I will look at encrypting requests. Reboot now and you should be able to log in as any valid LDAP user.

Using SSL Tunneling

To secure the LDAP authentication transaction, you can tunnel the requests over SSL using a tool such as stunnel ( on the UNIX end. Installation of stunnel is fairly straightforward. After downloading and decompressing the latest version, run:

# ./configure
# make
# make install (as root)
During this process, you will be asked for information in order to generate a security certificate. Alternatively, you can get a signed certificate from a third party.

Ensure that ldap and ldaps are valid entries in your /etc/services file (or equivalent for your flavor of UNIX). You should have at least:

ldap         389/tcp
ldaps        636/tcp
Now you can start stunnel and tell it to redirect and decrypt requests on the ldaps port to the ldap port:

stunnel -p [path to your certificate] -d ldaps -r localhost:ldap
For more information on stunnel and tunneling services over SSL, see Your UNIX machine should now be set up to authenticate users via LDAP over SSL, so I'll move on to setting up the Windows machine.

For LDAP tunneled through SSL to work correctly from the Windows side, your SSL certificate must be signed by a third party. Or, if you created a certificate (e.g., cert.pem when installing stunnel), you must add that certificate to the trusted stores on the Windows machine. (Thanks to Micah Cooper, author of the LDAPAuth plugin, for instructions on how to do this):

1. Obtain the public key certificate. This is the last section of text from your cert.pem file.

2. As an administrator, double click on the certificate file.

3. Select "Next".

4. Select "Place all certificates in the following store".

5. Select "Browse".

6. Check the "Show physical stores" box.

7. Expand "Trusted Root Certification Authorities" and then highlight "Local Computer".

8. Hit "OK", and all is well.

Your Windows machine is now ready for authenticating against your LDAP server over SSL, but you still need to tell the LDAP plugin to do so by changing the useSSL registry entry to a "1". (Micah has provided some very good guidelines for testing LDAP over SSL on the pGina Web site if you run into problems.)

pGina Configuration

A GUI configuration tool is available to facilitate changing the behavior of pGina. After installation, it should be available in your Start menu under "pGina" as "Configure". Running this tool allows you to configure and test either a plugin or pGina. Click the "Configure pGina" button, and locate your installation of pGina.dll. This will bring up the GUI tool shown in Figure 3. Here are the available options.

The first few settings are string values, some of which may be blank.

Plugin -- This should contain the full path to the selected pGina plugin.

Maps -- In this box, you can specify login time drive->directory mappings. So, if you were running a Samba file server (or other file server) and wanted the user's home directory mapped to drive X on login, you would put X:\\hostname.for.share\%username% here. Multiple entries may be used by separating each with semicolons.

MSGina -- For GINA chaining. Some people already use custom GINAs for other interfaces, and pGina can dynamically chain to them by inserting their paths here.

The remaining settings are simply 0- or 1-bit style flags.

Debug Output -- Dump text to C:\pgina_debug[????].txt containing debug information. This file will be requested from you should you report a bug or problem. This file may contain usernames and passwords, which should be edited out prior to sending them.

Keep Profiles -- This setting indicates whether pGina should keep individual user profiles from one login to the next. By default this is 0; if set to 1, then Force Local should also be turned on.

Passthru Mode -- When this option is turned on, pGina will not do anything. It will still be loaded and active, but will pass all information and calls to the MSGina specified earlier.

Allow Locking -- Toggles the ability to lock the workstation with CTRL+ALT+DEL while logged in.

Map Admins -- When this option is turned off (default), pGina will not try to map things in the "Maps" setting if the authenticated user is a local administrator.

Button Action -- Toggles the action/caption for the button on the login screen.

Force Local -- Forces login of a user if a plugin user and the local user have the same username (regardless of password similarity/difference). When combined with Keep Profiles, this can allow a user to maintain a custom local profile.

Recommendations and the Future of pGina

I recommend reading the Technical Manual available on the pGina Web site for further pGina details and explanation of the different options. In the future, pGina promises to include a "roaming profile"-like functionality that allows for pseudo-roaming profiles (stored on a Samba share, or other remote media), along with other features and fixes. I encourage you to explore the options and configuration that work best for you, then roll your own installation utility (e.g., Spoon Installer) to ease installation across your enterprise (or through ghosting utilities, etc.).

Remember, pGina is GPL'd, so you can customize the login screen (see Figure 4), display your organization's logo or text, as well as other things. pGina Project information is also available on SourceForge at:
For more information on the available plugins, or on developing your own, check out the pGina Web site or email me.


Michael Wright, Pacific Lutheran University: pGina Co-Developer

Microsoft Support Article on "Setting up a custom default user profile": \

pGina and pGina Plugin Documentation:

GINA Documentation:

Micah Cooper, Miami University Ohio: Author of the LDAPAuth pGina plugin

Jeremy C. Sparks, Willamette University

Nathan Yocom has worn many hats in the IT industry during the past eight years. For the past two years, he has worked as the Technical Support Specialist for the Department of Computer Science and Engineering at Pacific Lutheran University. His experience programming in both UNIX and Windows environments, combined with his systems administration experience, has lent itself well to projects such as pGina, which work to promote interoperability within a heterogeneous environment. He can be contacted at: