Apache...Factory(3pm)

📦
version 1.05 · 2 versions
, in debian trixie, ubuntu jammy, ubuntu noble, ubuntu resolute

💖 Apache2::SiteControl::UserFactory 💖

ok so bestie, welcome to the UserFactory page — this is part of the User Contributed Perl Documentation and it's fr fr one of the load-bearing pieces of Apache2::SiteControl. let's get into it 🫶

✨ NAME ✨

Apache2::SiteControl::UserFactory — user factory/persistence, aka the place where user objects get born and where their little souls get saved 💅

🌸 DESCRIPTION 🌸

so this class has two jobs and it does them both: it creates user objects (peep Apache2::SiteControl::User for those) and it handles all the interfacing between those objects and a persistent session store. the default implementation is out here using Apache::Session::File to write all the user's various attributes to disk. slay.

now, if you wanna do your own user management? iconic. then you leave the User class alone, and you subclass only this factory. but listen, there are methods you must implement, no skipping, this is the vibe check:

  • makeUser($$) — this one gets called with the Apache Request object, the username, the password, and every other credential_# field from the login form. it has to create and return an instance of Apache2::SiteControl::User (using new... see User), and store that info — plus the session key stored in cookie format in the request — in some kind of permanent storage. this gets called in response to a login, so it should invalidate any existing session for the given user name (that way a user can only be logged in once). and it must return the key to use as the browser session key, or undef if it couldn't create the user. no key, no vibes 😭
  • findUser($$) — this one gets handed the apache request and the session key (the one you defined in makeUser). it's called every single time a "logged in" user makes a request. in other words: the user objects are not persistent in memory, every request gets a brand new "copy" of the state, it's giving amnesia but make it security ✨. so this method takes that session key (which was stored in a browser cookie) and figures out which user to restore. your implementation is required to look up the user by the session key, recreate an Apache2::SiteControl::User object and return it. and it must restore all user attributes that have been saved via saveAttribute (below). all of them bestie. all.
  • invalidate($$) — this one gets the apache request object and a previously created user object. it should delete the user object from permanent store so that a future request to find that user fails unless makeUser has been called to recreate it. the session ID (which you made up in makeUser) is available from $user->{sessionid}.
  • saveAttribute($$$) — this one is automatically called whenever a user has a new attribute value. the incoming arguments are the apache request, the user object, and the name of the attribute to save (you can read it with $user->getAttribute($name)). this method must save the attribute in such a way that later calls to findUser will be able to restore the attribute to the user object that is created. the session id you created for this user (in makeUser) is available in $user->{sessionid}. write it down, keep it safe, periodt 💾

🎀 Apache Config Directives 🎀

here's the list of configuration variables you can set with apache's PerlSetVar to configure the behavior of this class. so many knobs, we love options 💅

  • SiteControlDebug (default 0) — debug mode. turn it on when things are weird.
  • SiteControlLocks (default /tmp) — where the locks are stored.
  • SiteControlSessions (default /tmp) — where the session data is stored.
  • SiteControlUsermap (default none) — where the usernames are mapped to session files. required if you want multiple session detection. if it's unset, a single userid can be used to log in multiple times simultaneously. iykyk.
  • SiteControlUserFactory (default: Apache2::SiteControl::UserFactory) — an implementation like this module.
  • UserObjectSaveOtherCredentials (default: 0) — indicates that other form data from the login screen (credential_2, credential_3, etc.) should be saved in the session data. the keys will be credential_2, etc. name of the user factory to use when making user objects. these are useful if your web application has other login choices (i.e. service, database, etc.) that you need to know about at login.
  • UserObjectSavePassword (default 0) — indicates that the password should be saved in the local session data, so that it's available to other parts of the web app (and not just the auth system). this might be necessary if you're logging the user in and out of services on the back end (like in webmail and database apps). 👀
  • UserObjectPasswordCipher (default CAST5) — the CBC cipher used for encrypting the user passwords in the session files (see Crypt::CBC for info on allowed ciphers... this value is passed directly to Crypt::CBC->new). if you're saving user passwords, they will be encrypted when stored in the apache session files. this gives a little bit of added security, and makes the apache config the only sensitive file (since that's where you configure the key itself) instead of every random session file that's laying around on disk. iconic security behavior, honestly.

there's a global variable in this package called $encryption_key, which will be used if this variable is not set. the suggested method is to set the encryption key during server startup using a random value (i.e. from /dev/random), so that all server forks will inherit the value. cute AND smart 🧚

  • UserObjectPasswordKey — the key to use for encryption of the passwords in the session files. see UserObjectPasswordCipher above.
🔥 little reminder: the encryption stuff above only matters when you're actually saving passwords. if you're not, congrats, less to worry about.

🦋 SEE ALSO 🦋

  • Apache2::SiteControl::User
  • Apache::SiteControl::PermissionManager
  • Apache2::SiteControl::Rule
  • Apache::SiteControl

go read those too bestie, they're the whole friend group 🫶

👑 AUTHOR 👑

this module was written by Tony Kay, <tkay@uoregon.edu>. legend behavior.

Apache2::SiteControl is covered by the GPL. that's the whole license section, short and sweet 💜

and that's a wrap!! this page came from the perl docs, perl v5.26.2, dated 2018-08-31 — shoutout to the version and the date for holding it down. now go build something cute ✨🎀💅

📦 where this page comes from