Grant Temporary PAM Groups with pam_group and group.conf

pam_group lets a PAM service add a supplementary group to a login, but only when a user, terminal and time rule all match at once. The examples use the Ubuntu Linux-PAM package libpam-modules version 1.5.3-5ubuntu5.7, with the default rules file at /etc/security/group.conf.

Allow about 20 minutes, plus time to test the real PAM service. You need root access, a test account, the target service name, and an existing Unix group to grant. This changes authentication configuration, so keep an existing root session open while testing. A typo in a PAM stack can lock people out.

1. Check the installed module and its limits

Confirm the package version and module path before editing anything. These are read-only and need no elevated privileges:

$ dpkg-query -W -f='${Package} ${Version}\n' libpam-modules:amd64
libpam-modules 1.5.3-5ubuntu5.7
$ ls -l /usr/lib/*/security/pam_group.so

• pam_group is an auth-type module with no module options.
• It does not authenticate the user. It adds groups during PAM's credential-setting phase, based on the service that invokes it.
• Membership from this module is additional to whatever normal entries already exist in /etc/group.

2. Check the group and make a backup

Choose a group that already exists and know exactly what access it provides. Reading the group database is unprivileged:

$ getent group PROJECT_GROUP
PROJECT_GROUP:x:1234:

Replace PROJECT_GROUP with the real group, the numeric ID and current member list will differ. Nothing printed? Stop and resolve the group first, do not create a new privileged group just to make this example work.

Now back up both files that are about to change. This needs elevated privileges and leaves recoverable copies in the same directories:

# cp -p /etc/security/group.conf /etc/security/group.conf.bak
# cp -p /etc/pam.d/TARGET_SERVICE /etc/pam.d/TARGET_SERVICE.bak

If the rules file does not exist yet, create it with root ownership and mode 0644 using your normal editor, then verify those properties. The PAM service file should already exist. Do not overwrite either file with shell redirection.

3. Add the PAM module to one service

Edit the target service's PAM file as root and add this line in its existing auth section:

auth    required    pam_group.so

The module accepts no options, so do not append a guessed file name or group name, it reads /etc/security/group.conf by default. The required control flag keeps this module in the stack and records a failure, while the rest of the PAM stack carries on according to its existing rules. Preserve the service's current ordering and controls exactly as they are.

# grep -nE '^[[:space:]]*auth[[:space:]].*pam_group\.so' /etc/pam.d/TARGET_SERVICE
12:auth    required    pam_group.so

The line number is only an example. If the file uses an included stack, confirm which file is actually read, and check you have not accidentally added a second pam_group.so line.

4. Write one narrow group.conf rule

Edit /etc/security/group.conf as root. Each active rule has five semicolon-separated fields:

services;ttys;users;times;groups

This example grants PROJECT_GROUP to TEST_USER for the TARGET_SERVICE service, on any terminal beginning with tty, all day:

TARGET_SERVICE;tty*;TEST_USER;Al0000-2400;PROJECT_GROUP

• All of the first three fields must match. The service field is the PAM service name, the terminal field is the terminal name, and the user field can hold a username, a Unix group prefixed with %, or a netgroup prefixed with @.
• The final field is a comma- or space-separated list of groups to add.
• The time field uses two-character day names and 24-hour times. Al0000-2400 means all seven days, the whole day. A range whose finish is earlier than its start continues into the following day.

Use a narrow window when you can. This example grants members of the Unix group project-admins access on weekdays from 09:00 to 18:00:

TARGET_SERVICE;tty*;%project-admins;Wd0900-1800;PROJECT_GROUP

Logic lists use | for OR, & for AND and ! for NOT. The wildcard * can only be used once in an ordinary list, and Unix group and netgroup entries do not support wildcards or logic operators at all. Lines can continue with a backslash, and text after # is a comment.

5. Test in a fresh session

Start a new session through the target service as TEST_USER. Existing shells neither gain nor lose supplementary groups when you edit the configuration, so an SSH service needs a fresh second terminal, and a local login service needs a separate console or desktop login.

Once logged in, inspect the process groups, no elevated privileges required:

$ id TEST_USER
uid=1001(TEST_USER) gid=1001(TEST_USER) groups=1001(TEST_USER),1234(PROJECT_GROUP)
$ getent group PROJECT_GROUP
PROJECT_GROUP:x:1234:TEST_USER

The exact IDs and ordering vary. What matters is that the new session includes PROJECT_GROUP. Then go on to test the actual file or device access the group is meant to control, seeing the group in id proves the credential was added, not that every application will honour it correctly.

6. Diagnose a rule that does not match

Check the four values people most often mix up: the PAM service name, the terminal name, the account name and the current time. A rule for sshd does not automatically apply to login, and tty* does not mean every graphical or pseudo-terminal name. Capture the session's terminal with:

$ tty
/dev/pts/3

A session reporting a pseudo-terminal such as /dev/pts/3 will not match a rule beginning tty*. Only change the terminal field after checking the service's actual PAM context and thinking through the security consequences, an overly broad wildcard can grant the group in far more places than you intended.

Review the host's normal authentication logs if the module reports a PAM error. A missing user can produce PAM_USER_UNKNOWN; failure to grant a group can produce PAM_CRED_ERR. Those are module return values, not shell commands, and there is no option to silence them because this installed module recognises none.

7. Treat the security boundary as incomplete

Do not treat pam_group as the only control for highly sensitive access unless you have reviewed the mount layout, setgid behaviour, service stack, logs and recovery path together. The granted group also applies on top of /etc/group, so review the effective access rather than assuming the PAM rule replaces ordinary membership.

8. Undo the change

To remove the rule, delete or comment out the exact line in /etc/security/group.conf, then remove the pam_group.so line from the target PAM service. Existing sessions keep their current credentials until they end, so start a new session to verify the group is actually gone.

# cp -p /etc/security/group.conf.bak /etc/security/group.conf
# cp -p /etc/pam.d/TARGET_SERVICE.bak /etc/pam.d/TARGET_SERVICE

Done means

• You checked the installed Linux-PAM package and module path.
• A real existing group and one target PAM service were chosen deliberately.
• Both configuration files were backed up before editing.
• The auth required pam_group.so line and five-field rule were reviewed.
• A fresh matching session gained the group, and the negative cases did not.
• The setgid and writable-file-system limitation was part of the security decision.
• You know which backups restore the previous PAM configuration.