pGina Local Machine Plugin Documentation

How it Works

The local machine plugin manages authentication and authorization for accounts that exist on the machine itself. It also is responsible for creating local accounts (possibly temporary ones) when a user is authorized to log in, but does not have a local account. During a logoff the plugin is also responsible to delete a user or scramble the password. Much of the functionality provided by this plugin was formerly part of the core in pGina 2.x and earlier.

The local machine plugin can execute in any or all main pGina stages (authentication, authorization, gateway, notification and change password).

Authentication Stage

In the authentication stage, the local machine plugin attempts to authenticate the user’s credentials against an existing local account. If the local user account does not exist, or the credentials do not match, the plugin registers failure for this stage.

It can be configured to always attempt to authenticate, or to only do so if the user has not already been authenticated by a plugin that was executed earlier within this stage.

If the LocalMachine plugin authenticates the user, it will copy the group membership of the local account into pGina’s internal list of groups. Note that this will NOT happen if it does not successfully authenticate the user. However, the authorization stage can be configured to do so anyway.

Note that you probably always want to make sure that the local machine plugin is enabled in the authentication stage. If not, you risk being unable to log into the machine if for some reason the alternate authentication methods fail (such as a network issue).

Authorization Stage

The local machine plugin authorizes users based on group membership. It can be configured such that a user must be a member of the administrator group to be authorized, and/or the user must be a member of one of a set of other local groups.

The plugin can also be configured to only apply these rules to accounts that were authenticated by this plugin and not by others. Or alternatively, it can apply these authorization rules to all authenticated users.

Gateway Stage

If enabled in the gateway stage, the local machine plugin ensures that the authenticated (and authorized) user has a local account. If not, one is created. It also makes sure that the local account has the appropriate group membership. Note that this stage does modify the group membership and other attributes of a local account (see “Local Groups” below). But remember users are tracked by the user comment "pGina created", and if the user exists (was’nt creaded by pgina itself) this attrib will not be set. This ensures that the user is NOT deleted even if the plugin is configured to do so. The already applied attributes on this account still remain!
You can also configure the plugin to add the user to a set of mandantory groups.

We recommend that you have this plugin enabled in the gateway stage if you are using non-local account logins such as LDAP or MySQL Authentication.

The plugin can also be configured such that the local account should be scheduled for removal or have its password scrambled upon logoff. This is done by notifications.

It’s possible to import user attributes from an LDAP (only if the pgSMB2 plugin is’nt used)


The profile cleanup and scramble password task is done here. If a user is logging off, the plugin is notified and executes the appropriate task. During that time the system won’t shut down, nor is the corresponding user able to log in again, until all tasks have been completed. Another user is able to login while another instance of the plugin is still logging someone out. It’s so called "non blocking". You can relay on, that the user is deleted or the password scrambled, before this user is able to relogin or the system shuts down.
Users are tracked by there profile description “pGina created”

Following can be done too (only if the pgSMB2 plugin is’nt used)

Change Password

This is’nt a stage during login, its more an event that is triggered during a password change. The plugin will change the local user password. It’s a good idea to disable the Control Panel “User Accounts”, found at "GPO\User Configuration\Control Panel\Hide specified Control Panel items" value "@usercpl.dll,-1"

The password change event is only triggered if the user is using CTRL+ALT+DEL or CTRL+ALT+END.

Local Groups

In the gateway stage, this plugin will make sure that the group membership of the local account is an exact match with the list of groups provided by the plugins. This can potentially remove or add groups to an existing account. In order to understand this, consider the pGina login process. During the execution of the pGina pipeline, plugins can add or remove groups from an internal list of groups. This list is initially empty at the beginning of the pipeline. When the gateway stage is executed, the LocalMachine plugin sees this list of groups of which the user should be a member, and attempts to make sure that the actual local account is a member of the same list of groups (no more, no less). To do so, it may remove or add groups to the local account as necessary.

If the local account already exists prior to logon, there are two locations where this plugin will copy the group membership of the existing local account into the internal list of groups described above. First, in the authentication stage the LocalMachine plugin will copy the group membership if the user is successfully authenticated by the plugin. Second, the authorization stage will copy the group membership of the local account if configured to do so (see the “Mirror groups from local user” option below).

Also, note that you probably want to make sure that the LocalMachine plugin executes last in the gateway stage. This is because there may be other plugins who change the group membership in the gateway stage. They should do so before the LocalMachine plugin executes because it is the LocalMachine plugin that makes sure that the local account is actually a member of the internal list of groups.


LocalMachine Plugin Configuration