AUTHSELECT-PROFILES(5)

📦
version 1.7.1 · 2 versions
, in centos-stream 10, fedora 43, fedora 44

✨ AUTHSELECT-PROFILES ✨

okay bestie, sit down, grab a strawberry 🍓 — this is the authselect-profiles manual, aka the glow-up guide for authselect profiles. it's a page in section 5 (file formats, iykyk), and it's here to spill how authselect profiles are organized and how you go make a brand new one. no cap.

💖 DESCRIPTION 💖

this page explains how authselect profiles are organized and how to create new profiles. that's it, that's the whole assignment. but like... in detail. so much detail. stay with me. 🫶

🌸 PROFILE DIRECTORIES 🌸

so a profile can live in one of three places. three. like a little trio of homes.

  • /usr/share/authselect/default — a read-only directory holding the profiles that ship together with authselect. it's giving "factory settings", and you cannot touch, periodt.
  • /usr/share/authselect/vendor — a read-only directory for vendor-specific profiles. these can override the ones in the default directory. vendor said "i'll handle this one" 💅
  • /etc/authselect/custom — the place for administrator-defined profiles. this is your room, bestie. decorate it. 🎀

🦋 PROFILE FILES 🦋

each profile is made of one or more of these files. together they give you a mandatory profile description, plus describe the changes that get done to the system.

  • README — the description of the profile. the first line must be the name of the profile. mandatory, no skips, no notes app draft energy.
  • system-auth — the PAM stack that gets included from nearly all individual service configuration files. it's the main character of PAM stacks, fr fr.
  • password-auth, smartcard-auth, fingerprint-auth — these PAM stacks are for applications that handle authentication from different types of devices via simultaneously running individual conversations instead of one aggregate conversation. group chat, not one big phone call. 📱
  • postlogin — the whole point of this PAM stack is to give a common place for all PAM modules that should be called after the stack configured in system-auth or the other common PAM configuration files. it's included from all individual service configuration files that provide login service with shell or file access.
⚠️ NOTE: the modules in the postlogin configuration file are executed regardless of the success or failure of the modules in the system-auth configuration file. they do not care. they show up anyway. iconic but also a little scary.
  • nsswitch.conf — the Name Service Switch configuration file.
  • dconf-db — changes to the dconf database. the main use case of this file is to set changes for the gnome login screen in order to enable or disable smartcard and fingerprint authentication.
  • dconf-locks — this file defines locks on values set in the dconf database. 🔒

🧚 CONDITIONAL LINES 🧚

each of these files is a template, bestie. a template is just a plain text file, but with optional usage of several operators that can give you some optional profile features. this is where it gets fun. 🌈

  • {continue if "feature"} — immediately stop processing of the file unless feature is defined (the rest of the file content will be removed). if feature is defined, the whole line with this operator gets removed and the rest of the template keeps processing. so it's like "continue only if you're invited". 🎟️
  • {stop if "feature"} — the opposite of continue if. immediately stop processing of the file if feature is defined (the rest of the file content will be removed). if feature is not defined, the whole line with this operator gets removed and the rest of the template keeps processing.
  • {include if "feature"} — include the line where this operator is placed only if feature is defined.
  • {exclude if "feature"} — opposite to include-if. include the line where this operator is placed only if feature is not defined.
  • {imply "implied-feature" if "feature"} — enable feature implied-feature if feature feature is enabled. the whole line with this operator is removed, so it is not possible to add anything else around this operator on the same line. that line is spoken for. 💀
  • {if "feature":true|false} — if feature is defined, replace this operator with the string true, otherwise with the string false.
  • {if "feature":true} — if feature is defined, replace this operator with the string true, otherwise with an empty string.

it's also possible to use a logical expression in a conditional line instead of specifying a single feature name. in that case the expression will evaluate to true or false and the conditional operator will act upon the result. yes bestie, it's a whole boolean situation. 🧠✨

the expression syntax is made of feature names (e.g. "feature"), which return true if the feature is defined or false if it is not defined, plus these logical operators: and, or and not. the expression may also be enclosed in parentheses and contain multiple subexpressions. nesting? we love nesting.

for example:

  • {if "feature1" or "feature2":true} — if feature1 or feature2 is defined, replace this operator with the string true, otherwise with an empty string.
  • {if not "feature":true|false} — if feature is not defined, replace this operator with the string true, otherwise with the string false.
  • {if not "feature":true} — if feature is not defined, replace this operator with the string true, otherwise with an empty string.
  • {if "feature1" and ("feature2" or "feature3"):true} — if feature1 is defined, and one of feature2 and feature3 is defined, replace this operator with the string true, otherwise with an empty string.

🎀 EXAMPLE 🎀

here's an example of using the if operator. if the with-sudo feature is enabled, it will add sss to the sudoers line. 🫡

passwd:     sss files
group:      sss files
netgroup:   sss files
automount:  sss files
services:   sss files
sudoers:    files {if "with-sudo":sss}

here's an example of the continue-if and include-if operators. the resulting file will be empty unless the with-smartcard feature is enabled. and if it is enabled, and the with-faillock feature is also enabled, it will also enable support for pam_faillock. combo meal. 🍔

{continue if "with-smartcard"}
auth        required                                     pam_env.so
auth        required                                     pam_faildelay.so delay=2000000
auth        required                                     pam_faillock.so preauth silent deny=4 unlock_time=1200 {include if "with-faillock"}
auth        [default=1 ignore=ignore success=ok]         pam_succeed_if.so uid >= 1000 quiet
auth        [default=1 ignore=ignore success=ok]         pam_localuser.so
auth        sufficient                                   pam_unix.so nullok
auth        requisite                                    pam_succeed_if.so uid >= 1000 quiet_success
auth        sufficient                                   pam_sss.so forward_pass
auth        required                                     pam_faillock.so authfail deny=4 unlock_time=1200       {include if "with-faillock"}
auth        required                                     pam_deny.so
...

here's an example of continue-if using a logical expression. the file will be empty unless with-smartcard or with-smartcard-required is set. this simplifies the call of the authselect select command, which does not have to include both features — only with-smartcard-required is necessary. one feature doing the job of two? efficiency queen. 👑

{continue if "with-smartcard" or "with-smartcard-required"}
auth        required                                     pam_env.so
auth        required                                     pam_faildelay.so delay=2000000
auth        required                                     pam_faillock.so preauth silent deny=4 unlock_time=1200 {include if "with-faillock"}
auth        [default=1 ignore=ignore success=ok]         pam_succeed_if.so uid >= 1000 quiet
auth        [default=1 ignore=ignore success=ok]         pam_localuser.so
auth        sufficient                                   pam_unix.so nullok
auth        requisite                                    pam_succeed_if.so uid >= 1000 quiet_success
auth        sufficient                                   pam_sss.so forward_pass
auth        required                                     pam_faillock.so authfail deny=4 unlock_time=1200       {include if "with-faillock"}
auth        required                                     pam_deny.so
...

here's an example of the imply-if operator. enabling the feature with-smartcard-required will also enable with-smartcard, making sure that all relevant PAM modules are used. this achieves the same behavior as the previous example. same energy, different font. 💅

{imply "with-smartcard" if "with-smartcard-required"}
auth        required                                     pam_env.so
auth        required                                     pam_faildelay.so delay=2000000
auth        [success=1 default=ignore]                   pam_succeed_if.so service notin login:gdm:xdm:kdm:kde:xscreensaver:gnome-screensaver:kscreensaver quiet use_uid {include if "with-smartcard-required"}
auth        [success=done ignore=ignore default=die]     pam_sss.so require_cert_auth ignore_authinfo_unavail             {include if "with-smartcard-required"}
auth        [default=1 ignore=ignore success=ok]         pam_succeed_if.so uid >= 1000 quiet
auth        [default=1 ignore=ignore success=ok]         pam_localuser.so                                                 {exclude if "with-smartcard"}
auth        [default=2 ignore=ignore success=ok]         pam_localuser.so                                                 {include if "with-smartcard"}
auth        [success=done authinfo_unavail=ignore user_unknown=ignore ignore=ignore default=die] pam_sss.so try_cert_auth {include if "with-smartcard"}
auth        sufficient                                   pam_unix.so {if not "without-nullok":nullok}
auth        requisite                                    pam_succeed_if.so uid >= 1000 quiet_success
auth        sufficient                                   pam_sss.so forward_pass
auth        required                                     pam_deny.so
...

👑 CREATING A NEW PROFILE 👑

to register a new profile within authselect, create a directory in one of the authselect profile locations with the files listed above. not all of the files must be present — only README is mandatory. the other files can be created on a per-need basis. build the profile you need, not the profile society expects. 🌱

you may find the authselect create-profile command helpful when creating a new profile. see the authselect(8) manual page or authselect create-profile --help for more information. it's literally right there, bestie, it'll hold your hand. 🤝

🌈 SEE ALSO 🌈

and that's the whole page!! 🎉 this little gem is from 2018-02-17 (a vintage, honestly) and it belongs to the AUTHSELECT-PROFILES(5) page of the authselect project. go forth and build profiles, you absolute legend. mwah. 💋💖✨

📦 where this page comes from