Cataly...::Realm(3pm)

💖 NAME 💖

Catalyst::Authentication::Realm — Base class for realm objects. This is the Cataly...::Realm(3pm) page from the User Contributed Perl Documentation crew, bestie ✨

🌸 DESCRIPTION 🌸

This section is literally empty in the original — no cap, the tea starts in CONFIGURATION. 💅

🎀 CONFIGURATION 🎀

Okay so these are the config knobs, and yes they are important:

• class — By default this class is used by Catalyst::Plugin::Authentication for all realms. The class parameter allows you to choose a different class to use for this realm. Creating a new Realm class can allow for authentication methods that fall outside the normal credential/store methodology. main character energy for custom auth, fr fr 👑
• auto_create_user — Set this to true if you wish this realm to auto-create user accounts when the user doesn't exist (most useful for remote authentication schemes). very remote-auth coded ✨
• auto_update_user — Set this to true if you wish this realm to auto-update user accounts after authentication (most useful for remote authentication schemes). same remote-auth vibe, but update-y 🦋
• use_session — Sets session usage for this particular realm — overriding the global use_sesion setting. yes, that spelling is in the original, bestie 😭

---

💅 METHODS 💅

Here’s where the realm actually does stuff. Slay. 🫶

✨ new( $realmname, $config, $app ) ✨

Instantiates this realm, plus the specified store and credential classes.

🛠️ store( ) 🛠️

Returns an instance of the store object for this realm.

🔑 credential( ) 🔑

Returns an instance of the credential object for this realm.

🕵️ find_user( $authinfo, $c ) 🕵️

Retrieves the user given the authentication information provided. This is most often called from the credential. The default realm class simply delegates this call to the store object. If enabled, auto-creation and auto-updating of users is also handled here.

🪄 authenticate( $c, $authinfo) 🪄

Performs the authentication process for the current realm. The default realm class simply delegates this to the credential and sets the authenticated user on success. Returns the authenticated user object;

---

🦋 USER PERSISTENCE 🦋

The Realm class allows complete control over the persistance of users between requests. By default the realm attempts to use the Catalyst session system to accomplish this. By overriding the methods below in a custom Realm class, however, you can handle user persistance in any way you see fit.

🍓 persist_user($c, $user) 🍓

persist_user is the entry point for saving user information between requests. In most cases this will utilize the session. By default this uses the catalyst session system to store the user by calling for_session on the active store. The user object must be a subclass of Catalyst::Authentication::User. If you have updated the user object, you must call persist_user again to ensure that the persisted user object reflects your updates.

🧚 remove_persisted_user($c) 🧚

Removes any persisted user data. By default, removes the user from the session.

🌈 user_is_restorable( $c ) 🌈

Returns whether there is a persisted user that may be restored. Returns a token used to restore the user. With the default session persistance it returns the raw frozen user information.

⭐ restore_user($c, [$frozen_user]) ⭐

Restores the user from the given frozen_user parameter, or if not provided, using the response from $self->user_is_restorable(); Uses $self->from_session() to decode the frozen user.

💀 failed_user_restore($c) 💀

If there is a session to restore, but the restore fails for any reason then this method is called. This method supplied just removes the persisted user, but can be overridden if required to have more complex logic (e.g. finding a the user by their 'old' username).

💜 from_session($c, $frozenuser ) 💜

Decodes the frozenuser information provided and returns an instantiated user object. By default, this call is delegated to $store->from_session().

🔥 save_user_in_session($c, $user) 🔥

DEPRECATED. Use persist_user instead. (this simply calls persist_user)

---

💖 okay that’s the whole page, bestie — source/version perl v5.40.1, dated 2026-05-22, from Cataly...::Realm(3pm). now go be the main character of your auth stack 🫶✨