pGina Local Machine Plugin Documentation
- Plugin Name: Local Machine
- Plugin Type: Authentication, Authorization, Gateway, Notification, Change Password
- Version: 3.9.9.2
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)
- import the users full name by using the Attribute converter (Fullname)
- mount a home drive by using the Attribute converter (usri4_home_dir_drive and usri4_home_dir)
- make use of a roaming profile by using the Attribute converter (usri4_profile)
Requires enabled GPO setting "Do not check for user ownership of Roaming Profile Folders"
Notification
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)
- a login script can be started in the users context during log on. Its only possible by using the LDAP plugin Attribute converter (LoginScript)
- the profile size can be limitited. Its only possible by using the LDAP plugin Attribute converter (usri4_max_storage)
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.
Configuration
Authentication
- Always authenticate local users – When this is checked, the plugin will always attempt to authenticate the user against a local account. If this is not checked, the plugin will only attempt to authenticate when the user has not already been authenticated by a plugin that has executed earlier within the authentication stage.
Note that this plugin will copy the groups of the local account into the internal list of groups (see above) only when authentication is successful (or configured to do so in the authorization stage).
Authorization
- Mirror groups from local user – Load all groups from the local account into the pGina user information store so that the LocalMachine’s Gateway stage (and other subsequent plugins) will see that the user should be a member of those groups. When this plugin is enabled in the Gateway stage, it will attempt to make sure that the local account has the same groups as listed in the internal user information store. This is automatically done if the user was authenticated by this plugin regardless of the state of this option. Will erase all previous collected group informations
- Authorize all authenticated users – When this is checked, the plugin will attempt to authorize all users. Otherwise, the plugin will only authorize users that were authenticated successfully by this plugin.
- Require local administrator group membership – Only authorize users that are members of the Administrators group.
- Require membership in one of the following local groups – Only authorize users that are members of one of the groups listed below this checkbox. You sould always prefer to use SID’s to define a group name!
Gateway
- Failure to create or join local groups should prevent login – When this is checked, the plugin will register failure if it is unable to create or join the local groups that are requested.
- Mandantory groups – The local account is added to these local groups if not already a member.
Notification
- Remove account and profile after logout – When this is selected, the plugin will remove the account and its profile after logout. Its only applied to users created by pgina!
- Scramble password after logout – When this is checked, the plugin will scramble the password of the local account after logout. Its only applied to users created by pgina!