Username Modification Plugin Documentation

How it Works

The username modification plugin provides several options for modifying the username during the login process.

Typical Setup

The username modification plugin will not typically be used on it’s own. It is designed to modify the entered username to conform to specific standards of the primary plugin(s). Examples of this include replacing specific characters that are not typically allowed in Windows usernames.


The configuration interface for the username modification plugin is shown below.

Username Modification Configuration

When adding a new rule, you’ll be faced with the following options:


The stage you want the username modification to take place in. A brief description of the stages:

See the pGina Users Guide for more info.

List of Rules

The list of rules currently set. When changing the order of rules, you may only change the order of rules in the same stage. E.g. You may not swap an authentication and a authorization rule, since the authentication step takes place first.

Add Rule

Adds the specified rule to the rules list.

The rules are described below.


Appends the specified string to the end of the username.


Prepends the specified string to the beginning of the username.


Truncates the username to the specified number of characters.


Replaces each specified character in the first string with the second string. If the second string is left blank, the characters will be removed. Characters are case sensitive.

RegEx Replace

Replaces all matches for the specified regex expression with the specified string. If the second specified string is left blank, the matches will be removed.


Rather than modifying the username, the match rule checks to see if the username conforms to the specified regular expression.

During the authentication stage, if ANY match rule matches the username, the user will be authenticated WITHOUT verifying the password.

During the authorization and gateway stages, the default behavior is to authorize the username unless one of the match rules fail. A failure during either of these two stages will prevent login.

Consider this

By using this plugin pGina is unable to verify a user during logon as shown here. Pgina can’t detect a loggin off session from this user nor if this user is already logged in and tries to unlock the user. As you can see the Username Modification Plugin runs in stage 3 while the above checks are done in stage 2. Also plugins registered for Notification Events won’t work properly.