pam_succeed_if

pam_module_type control_flag pam_succeed_if.so [options]

user=[name|!name]
    Checks if the current user's name matches or does not match the given name.

uid=[id|!id]
    Checks if the current user's UID matches or does not match the given ID.

group=[name|!name]
    Checks if the current user's primary group name matches or does not match.

gid=[id|!id]
    Checks if the current user's primary GID matches or does not match.

shell=[path|!path]
    Checks if the current user's login shell path matches or does not match the specified path.

service=[name|!name]
    Checks if the PAM service name (e.g., login, sshd) matches or does not match.

tty=[name|!name]
    Checks if the terminal name (e.g., tty1, pts/0) matches or does not match.

ruser=[name|!name]
    Checks if the remote user name matches or does not match (if available from the application).

rhost=[host|!host]
    Checks if the remote hostname matches or does not match (if available from the application).

luser=[name|!name]
    Checks if the local user name matches or does not match (same as user).

sgroup=[name|!name]
    Checks if the current user is a member of the specified supplementary group or not.

euid=[id|!id]
    Checks if the effective user ID matches or does not match.

egid=[id|!id]
    Checks if the effective group ID matches or does not match.

and
    Specifies that all specified conditions must be true for the module to succeed (this is the default behavior).

or
    Specifies that at least one of the specified conditions must be true for the module to succeed.

quiet
    Suppresses informational messages from being logged to syslog (e.g., when conditions are not met).

debug
    Logs additional debug information to syslog, useful for troubleshooting.

fail
    Reverses the module's default return logic: if conditions are met, the module returns PAM_AUTH_ERR (or PAM_ACCT_EXPIRED for account modules); otherwise, it returns PAM_SUCCESS.

The pam_succeed_if.so module is a crucial component of the Linux-PAM (Pluggable Authentication Modules) framework, designed to implement conditional access policies. It evaluates a set of criteria (such as user name, UID, group membership, service name, TTY, etc.) and, based on the evaluation result, dictates whether the module should succeed or fail. By default, if all specified conditions are met, the module returns PAM_SUCCESS; otherwise, it fails.

This module is highly versatile and is commonly used in PAM configuration files (e.g., /etc/pam.d/sshd, /etc/pam.d/login) to enforce specific security rules. For instance, it can restrict SSH access to certain users, allow login only from specific TTYs, or grant elevated privileges based on group membership. Its power lies in its ability to combine multiple conditions using and (default) or or logic, providing fine-grained control over authentication and account management flows.

The order of pam_succeed_if within the PAM configuration file is critical, as PAM processes modules sequentially. Misconfiguration can lead to unexpected access behavior or even lockout. Always test PAM changes in a controlled environment.

The module evaluates all conditions on a single line; if multiple conditions are given, they are implicitly combined with and logic unless or is explicitly specified. Only one instance of a specific condition type (e.g., user=) is permitted per line. The quiet option should be used with caution, as it can hide important failure messages.

pam_succeed_if is typically used in the auth and account module types. The control_flag (e.g., required, sufficient, optional, requisite) determines how PAM reacts to the module's success or failure.

For instance, if used as required, the module must succeed for the overall PAM stack to succeed. If used as sufficient, its success can short-circuit the stack, bypassing subsequent modules. Understanding these flags is paramount to correctly implementing policies with pam_succeed_if.

By default, if multiple conditions are specified on a single line (e.g., user=john group=dev), they are implicitly combined with an and operator. This means all conditions must be true for the module to succeed. The or option changes this behavior, requiring only one of the specified conditions to be true for success. For example, user=john or user=jane means success if either John or Jane logs in. Careful planning of and/or logic is crucial for complex policies.

Most condition options can be negated by prefixing the value with an exclamation mark (!). For example, user=!root means 'if the user is NOT root'. This allows for expressing 'deny if' or 'allow if NOT' scenarios, greatly enhancing the module's flexibility in policy enforcement.

The pam_succeed_if module has been a fundamental part of the Linux-PAM framework since its early development. It was designed to provide administrators with a flexible and declarative way to define security policies based on various system and user attributes. Its existence highlights PAM's goal of modularity and extensibility, allowing for dynamic and granular control over authentication and authorization processes without modifying core application code. It has been a stable and widely used module for enforcing access controls across diverse Linux environments.

pam.conf(5), pam(8), pam_deny(8), pam_permit(8), pam_unix(8)