Control Flags

To determine continuation or failure behavior from a module during the authentication process, you must select one of four control flags for each entry. The control flags indicate how a successful or a failed attempt through each module is handled. Even though these flags apply to all module types, the following explanation assumes that these flags are being used for authentication modules. The control flags are as follows:

• required - This module must return success in order to have the overall result be successful.

  If all of the modules are labeled as required, then authentication through all modules must succeed for the user to be authenticated.

  If some of the modules fail, then an error value from the first failed module is reported.

  If a failure occurs for a module flagged as required, all modules in the stack are still tried but failure is returned.

  If none of the modules are flagged as required, then at least one of the entries for that service must succeed for the user to be authenticated.

• requisite - This module must return success for additional authentication to occur.

  If a failure occurs for a module flagged as requisite, an error is immediately returned to the application and no additional authentication is done. If the stack does not include prior modules labeled as required that failed, then the error from this module is returned. If a earlier module labeled as required has failed, the error message from the required module is returned.

• optional - If this module fails, the overall result can be successful if another module in this stack returns success.

  The optional flag should be used when one success in the stack is enough for a user to be authenticated. This flag should only be used if it is not important for this particular mechanism to succeed.

  If your users need to have permission associated with a specific mechanism to get their work done, then you should not label it as optional.

• sufficient - If this module is successful, skip the remaining modules in the stack, even if they are labeled as required.

  The sufficient flag indicates that one successful authentication will be enough for the user to be granted access.

  More information about these flags is provided in the section below, which describes the default /etc/pam.conf file.