Forward X Cookies Through su with pam_xauth

You will configure su to pass the current X display's authentication cookie into the account you assume, then remove the temporary credential when the session closes. This is useful for running an X application as another local user without manually copying ~/.Xauthority.

Allow about 20 minutes. You need an X session with a usable DISPLAY, the libpam-modules package, su, and xauth. The examples use Ubuntu's installed Linux-PAM package version 1.5.3-5ubuntu5.7 and xauth 1.1.2. A headless shell has no display cookie to forward, so it cannot provide a meaningful test.

1. Confirm the local prerequisites

Run these read-only checks as your ordinary desktop user:

$ printf 'DISPLAY=%s\n' "$DISPLAY"
$ command -v su
/usr/bin/su
$ command -v xauth
/usr/bin/xauth
$ dpkg-query -W -f='${Package} ${Version}\n' libpam-modules:amd64
libpam-modules 1.5.3-5ubuntu5.7
$ xauth -V
1.1.2

If DISPLAY is empty, stop at this checkpoint. Installing a display server or inventing a display value is outside this guide. If xauth is in a non-standard location, record its absolute path for the module option used later.

2. Check the current PAM rule

Inspect the service file before editing it:

$ grep -n 'pam_xauth' /etc/pam.d/su || true

No output means the module is not currently configured for su. The module provides only the PAM session type. It belongs in /etc/pam.d/su, not in a password or authentication line.

This next step changes system authentication configuration and requires elevated privileges. Before editing, make a recoverable copy with a root shell:

$ sudo cp -p /etc/pam.d/su /etc/pam.d/su.before-pam-xauth

Keep that copy until the test is complete. If a PAM edit causes trouble, restore it with sudo cp -p /etc/pam.d/su.before-pam-xauth /etc/pam.d/su from a root-capable console. Do not close your existing administrative session before testing a PAM change.

3. Add the session module

Open the file as root and add this line to the session section:

session  optional  pam_xauth.so

The optional control flag follows the module's documented example. It means an inability to forward an X cookie does not by itself make every su session fail. That is usually the right operational choice because non-graphical sessions have no cookie. If your local PAM policy has a specific control-flag requirement, follow that policy rather than copying this line blindly.

$ sudoedit /etc/pam.d/su
$ grep -n 'pam_xauth' /etc/pam.d/su
53:session  optional  pam_xauth.so

The line number is only an example. The important checkpoint is that the entry appears once and is spelled exactly as shown. Do not add a second copy while troubleshooting.

4. Set an explicit xauth path only when needed

pam_xauth searches /usr/X11R6/bin/xauth, /usr/bin/xauth, and /usr/bin/X11/xauth by default. This machine has /usr/bin/xauth, so the plain module line is sufficient. If your installation keeps the executable elsewhere, add the path as a module argument:

session  optional  pam_xauth.so xauthpath=/absolute/path/to/xauth

Use an absolute path that you have checked with command -v xauth. Do not use a shell variable or a path supplied by an untrusted user in PAM configuration.

5. Restrict the users allowed to exchange cookies

pam_xauth has two per-user policy files. The invoking account's ~/.xauth/export controls which target users may receive cookies. The target account's ~/.xauth/import controls which source users it accepts. A missing import file accepts cookies from any other user. A missing export file permits non-root callers to forward to any other user, while root forwards to nobody by default. Empty files deny all users. Both files support wildcards.

These defaults are easy to misread. In particular, adding the module does not make root's cookies available to every account. Decide the source and target accounts before creating policy. The files are security-sensitive because an X cookie can authorise access to the display.

For a narrow example, suppose the desktop account is alice and the account used for X tools is operator. As each account, create only the rule it needs. The following commands change state and use sudo to write another user's home directory:

$ printf '%s\n' operator | sudo tee /home/alice/.xauth/export >/dev/null
$ printf '%s\n' alice | sudo tee /home/operator/.xauth/import >/dev/null
$ sudo chown alice:alice /home/alice/.xauth/export
$ sudo chown operator:operator /home/operator/.xauth/import
$ sudo chmod 600 /home/alice/.xauth/export /home/operator/.xauth/import

Use the real home directories and account names from getent passwd. If those .xauth directories do not exist, create them with the correct owner and mode before writing the files. To undo this example, remove the two files only if they were created for this test, or edit them back to their previous contents. Do not delete an existing policy file without first preserving it.

6. Test the complete session path

Start with a harmless command that prints the inherited display value. Replace operator with a permitted target account:

$ su operator -c 'printf "user=%s DISPLAY=%s\n" "$USER" "$DISPLAY"'
user=operator DISPLAY=:0

The display number is host-specific. This confirms that su ran the command, but it does not prove that the cookie was accepted.

Now run a real X client available on the machine. Use a short-lived client or a command that exits cleanly. For example, if xmessage is installed:

$ su operator -c 'xmessage -timeout 2 pam_xauth-test'
$ printf 'exit status: %s\n' "$?"
exit status: 0

A zero status means the client exited successfully. A display authentication error points to the cookie path, the import/export policy, the target account's home directory, or the command's own environment. pam_xauth forwards only when xauth can list a key associated with DISPLAY.

7. Diagnose without leaving stale credentials

Add debug temporarily if you need module diagnostics:

session  optional  pam_xauth.so debug

Repeat the short test, inspect the relevant system log for the PAM diagnostic, then remove debug once you have enough evidence. The module creates a temporary target-side database and removes the forwarded key when the session closes. It cannot be configured to retain those keys.

If the test changed access unexpectedly, restore the backed-up PAM file, remove only policy files created for this guide, and start a fresh su session. Do not troubleshoot by copying ~/.Xauthority between users: that bypasses the access controls you just configured and can expose more display credentials than intended.