• Home
• Download
• Support
• Documentation
• Develop
• FAQ
• Thanks

pGina User’s Guide

• Installation
• How pGina Works
• Configuration
• Ordering Plugins
• Credential Provider Filter
• Logging
• Remember

Installation

pGina is packaged in a standard Windows installer, so installation is as easy as downloading and running the installer. After initial installation, pGina will be configured with the “LocalMachine” plugin enabled for the authentication and gateway stages (see below). This means that you will be able to use pGina out-of-the-box to log into the machine using existing local accounts, and if necessary, the LocalMachine plugin will create accounts for authenticated users.

In addition to the “LocalMachine” plugin, a standard set of additional plugins is provided and made available, but none of them are initally enabled.

Verify Install

After installation, start the pGina configuration application. Verify that the pGina service is running and that the Credential Provider/GINA is installed and enabled.

pGina will not function properly unless these components are working. More information about the Credential Provider and pGina service is provied in the next section.

How pGina Works

pGina is a replacement for the default Windows Credential Provider (or CP). Through plugins, pGina allows you to configure many aspects of the login process from authentication and authorization through to logging and terminal events.

Note that the Credential Provider framework is supported in Windows 7/Vista and higher. Prior versions of Windows used a framework called GINA. For much of this guide, we’ll simply refer to it as a Credential Provider or CP.

The diagram below represents a high-level picture of a typical logon process.

To distinguish between pGina and a nomal windows user accounts, every pGina user is marked with a user comment of"pGina created". Only non existent (LocalMachine plugin) and"pGina created"user accounts are touched by pGina, if that’s not the case then this particular account wont be altered by pGina. To go further, local non pGina users and Domain users dont run through the plugin chain!

The logon process proceeds as follows:

1. The user enters their credentials at the pGina logon user interface. Note that this UI may be one of several options (called credential providers) presented to the user. For example, the user might be presented with several tiles, many of which are local accounts with only one being the pGina UI.
2. The pGina credential provider (or GINA) passes the credentials to the pGina service. If the user is currently logging off a relogin is denied. If the user is not a pGina user than he is processed by WinAPI authentication procedures, and if a user was already authenticated he will be processed by the WinAPI as well. If nothing from above apply, than the service sends those credentials through the plugin pipeline described below. This stage potentially fails if you modified the username by using a plugin like Username Modification!
3. After the credentials have been processed by the plugins, the pGina service sends a result (success/failure) along with a set of credentials (username/ password) back to the pGina CP. Note that these credentials may not be the same as those that were provided by the user. They may have been altered at some stage by one or more plugins.
4. If the result returned from step three is success, the pGina credential provider passes the (possibly altered) credentials to Windows indicating a successful logon attempt. Note that pGina does not actually log the user on to the machine. It is the Windows OS itself that does that. This means that if a local account does not exist that matches the credentials, the logon will fail, even if the pGina plugins have registered success. Therefore, it is often the case that one of the plugins will be responsible for creating a local (often temporary) account. The plugin called “Local Machine” takes care of this in the Gateway stage. For details, see the documentation for the Local Machine plugin.

As indicated above, it is important to note that pGina does not actually log the user on to the computer. The Windows OS is still ultimately responsible for logging the user on to the machine and possibly creating a profile for the user. pGina’s job is to authenticate and authorize the user, and perform any other pre-logon actions that may be needed. This means that in order for a logon to be successful, a local account must exist that matches the credentails returned by the pGina CP (Credential Provider). In a typical case, pGina would be configured to create the local account prior to logon, and possibly delete that account after logoff (see the LocalMachine plugin).

To explain the logon in a different way

• If a System is NOT member of a Domain
  • a user will be authenticated against the local system
    • exists a user with that name on the system incl. the comment "pGina created" than he will be processed by pGina
    • exists a user with that name on the system without the comment "pGina created" than he will be authenticated by the WinAPI and doesn’t go trough the pGina chain.
    • exists no user with that name on the system than the logon will be processed by pGina
• If a System IS member of a Domain
  • a user will be authenticated against the Domain
  • if a user is providing a leading .\ , than he will be authenticated against the local system google
    • in this case, the same rules apply as if this system where NOT member of a Domain

What username formats are suported?

User Principal Name

User principal name (UPN) format is used to specify an Internet-style name, such as UserName@Example.Microsoft.com. The following table summarizes the parts of a UPN.

Part	Example
User account name. Also known as the logon name.	UserName
Separator. A character literal, the at sign (@).	@
UPN suffix. Also known as the domain name.	Example.Microsoft.com

Down-Level Logon Name

The down-level logon name format is used to specify a domain and a user account in that domain, for example, DOMAIN\UserName. The following table summarizes the parts of a down-level logon name.

Part	Example
NetBIOS domain name.	DOMAIN
Separator. A character literal, the backslash (\).	\
User account name. Also known as the logon name.	UserName

The pGina Architecture

pGina consists of two main components: the Credential Provider (or GINA), and the pGina service (which manages the plugins).

The CP augments or replaces the default Windows authentication user interface. It plugs-in to the Windows system and can configure the UI that is displayed at login time (or during unlock, UAC control, etc.). The pGina CP, however, does very little on its own. It simply receives the user’s credentials and passes them along to the pGina service via a named pipe, and then waits for a response from the service. User authentication/authorization is instead managed by the plugins that run within the pGina service.

The pGina service is a standard Windows service that is started at boot time, and runs with SYSTEM priviledges. Note that upon initial boot, it may take some time for pGina service to start, and the CP will (of course) be unable to communicate with the service until it is started.

Configuration

• Tile Image - You can set your own Image here. 200x200 BMP
• MOTD - A short message to display on the login screen. No new lines are displayed!
• pGina Service - The status of the service
• Credential Provider - Enable, disable, register or unregister pGina credential provider
• NTP Servers - You can set NTP Servers here, line by line
• Unlock - If you modify the username using a plugin, you can force here to use the real username during an unlock
  • This will only apply in the unlock screen!
• Logon
  • Display last user name in logon screen - If enabled the last successfully logged in username will be displayed by pGina
  • Prefer local Authentication - First read How pGina Works. It’s only usefull in a Domain environment! If enabled the logon routine is reversed.
    • A user can logon locally without providing a leading .\ but if you want to logon with an Domain user account you need to provide the domain like : domain\user
• Email Notifications - If something goes wrong you can enable email notifications here
  • smtp Server - space seperated list of smtp servers smtp.domain.local:25
  • email Addr: - space seperated list of email recipients
  • Username: - Username for authentication against an smtp server
  • Password: - Password for authentication against an smtp server
  • Prefer Login credentials - If enabled login credentials from the logon/logoff user are used to authenticate against the smtp. As a fallback option Username: and Password: where used
  • SSL - If disabled the smtp connection is unencrypted. Unencrypted transfer is a fallback if encrytion is not possible.

Plugins

pGina manages the logon process by delegating the work to a set of zero or more plugins. Plugins have the job of deciding whether or not the user is who she says she is (authentication), whether the user should be granted access (authorization), and taking other login-time actions. The process involves a pipeline consisting of three main stages as illustrated in the following diagram.

Each stage involves zero or more plugins, and a given plugin may be involved in multiple stages. After the user provides his/her credentials, pGina passes through the three stages one at a time, in the order shown above. Each stage may succeed or fail depending on the results of the plugins involved. The purpose of each stage is summarized below.

• Authentication - Plugins involved in this stage validate that the user is who he/she says she is. This might be done by validating the credentials against some external database or other source.
• Authorization - This stage is intended to determine whether or not the user (who is already authenticated) is allowed to access the resources that are being requested. For example, a user might only be allowed to login if they are a member of certain groups.
• Gateway - This is similar to the Authorization stage in that it may fail, however, the intention is not to authorize users, but to provide post-authorization account management that may fail. For example, the “Local Machine” plugin executes within the gateway stage. It is responsible for creating (if necessary) a local Windows account that matches the credentials of the user that is logging in. If for some reason, this fails, then the user cannot be logged in, and this plugin must stop the login process and provide an appropriate error message. In general, this stage provides a “last chance” for a login to fail (post authenticate/authorize).

Plugins can be configured to provide services for zero or more of the above stages. For example, the “LocalMachine” plugin provides services for all three stages. In the authentication stage, it verifies that the user’s credentials match that of some existing local account, and in the authorization state, it verifies that the authenticated user is allowed to log on to the machine.

There can be zero or more plugins involved with each stage. If any stage fails, the login fails. However, stages have different rules regarding when a stage succeeds or fails.

• Authentication - At least one of the plugins involved in this stage must register success for the process to continue. If there are zero plugins registered, this stage fails.
• Authorization - All plugins involved in this stage must register success for the process to continue. If there are no plugins registered, this stage succeeds.
• Gateway - All plugins involved in this stage must register success for the process to continue. If there are no plugins registered, this stage succeeds. However, the "Local Machine" plugin will almost always be registered in this stage.

Plugins can provide services to multiple stages, and these services can be selectively turned on or off. For example, consider plugin Foo that provides Authentication and Authorization. pGina can be confiured such that Foo only provides Authentication, only Authorization, both, or neither. Configuration is described later in this document.

Plugins can also be ordered within each stage. For example, suppose plugins Foo and Bar are providing services to the user session stage. We can configure Foo to be invoked before Bar, or Bar before Foo.

User Information

During the execution of the above pipeline, pGina maintains some information about the user. This includes user-name, password, group membership and other information. This information can be altered by plugins during the pipeline, and/or used by plugins to modify the state of the machine. For example, plugins may add or remove groups, alter the username or password, or a plugin might attempt to create a local account using this information. This means that the order that the plugins execute within each stage of the pipeline is important (see below), and different orders may produce different results. One must be careful to configure your plugins in the order that makes sense for your setup. The final values of username/password/domain are passed along to Windows to complete the logon process.

In a typical setup one wants to make sure that a local account exists or is created at the end of the pipeline. To do so, one should configure the LocalMachine plugin so that it executes last in the Gateway stage. It is the Gateway stage of the LocalMachine plugin that creates (if necessary) local accounts. If the LocalMachine plugin executes earlier, it may miss important information for the local account (such as group membership).

Event Notifications

Plugins may also register to recieve event notifications from a WindowProc function. These events include: logon, logoff, lock, unlock, console connect, console disconnect, and a few others (see msdn for a full list). A plugin that desires to recieve these notifications will be listed as a “Notification” plugin in the configuration interface. The plugin will not recieve events unless it is enabled (see the section on configuration below). Its a good idea to keep Notifications enabled.

Change Password

Plugins can register to recieve change password notifications from the Credential Provider, by using CTRL+ALT+DEL or CTRL+ALT+END.
Pgina will not recieve a change password event from the control panel or managment console! A plugin that desires to recieve these notifications will be listed as a “Change Password” plugin in the configuration interface. The plugin will not recieve events unless it is enabled (see the section on configuration below).

Selecting and Configuring Plugins

In the pGina configuration interface, plugins can be enabled/disabled under the “Plugin Selection” tab. If a plugin provides services for a given stage, a checkbox will appear in the appropriate column. You can enable/disable a plugin for a given stage by using the checkbox.

To configure a plugin, double click on it or select it and click on “Configure..”. The plugin’s configuration dialog will appear. The options are plugin specific, and you should refer to the documentation for each plugin for details about configuration of an individual plugin.

Ordering Plugins

Under the “Plugin Order” tab, you can determine the order that each plugin is invoked. There is a list for each pGina stage, and you can re-order the plugins within each list.

Credential Provider Filter

Credential Providers can be filtered for the Logon, Unlock, Change Password and Cred UI screens. Installed Providers are listed under Credential Provider. If you want pGina to be the only Credential Provider available on the logon screen than you need to enable the Logon checkbox for the PasswordProvider.

Logging

pGina logs information to the following files, found in the main pGina installation directory (%ProgramFiles%\pGina.fork\log).

• pGina.Configuration_log.txt

  This contains log messages from the pGina configuration application.

• pGina.Service.ServiceHost_log.txt

  This file contains log messages from the pGina service.

• pGina.InstallUtil_log.txt

  This contains log messages from the registration utility that is used during installation/uninstallation to enable/disable the CP and pGina service.

Logging support in pGina is supported by Apache log4net, and is configured within the log4net configuration file, which is (by default) located here:

%ProgramFiles%\pGina.fork\log4net.config.

If you would like to log to a different file, simply edit this file. For details about log4net configuration, see the Apache log4net documentation.

Remember

• local non pGina users and AD users dont run through the plugin chain
• pGina users are marked with the user comment of "pGina created"
• make sure that plugins are in the correct order
• be careful if you disable credential providers
• use %ProgramFiles%\pGina.fork\log\pGina.Service.ServiceHost_log.txt to trace failures