Dancer2...tensible(3)

📦 version 0.714.0, in opensuse-leap 16.0

💖 Dancer2::Plugin::Auth::Extensible — the auth glow-up your Dancer2 app deserves ✨

okay so. bestie. this is the manual page for Dancer2::Plugin::Auth::Extensible(3), and it's literally the plugin that handles who gets in and who does not. no cap.

🌸 NAME 🌸

Dancer2::Plugin::Auth::Extensible — an extensible authentication framework for Dancer2 apps. it's giving "bouncer at the club, but make it Perl" 💅

🎀 DESCRIPTION 🎀

A user authentication and authorisation framework plugin for Dancer2 apps. yes, both. she does it all 🫶

It makes it easy to require a user to be logged in to access certain routes, provides role-based access control, and supports various authentication methods/sources (config file, database, Unix system users, etc). iconic behaviour, honestly.

Designed to support multiple authentication realms and to be as extensible as possible, and to make secure password handling easy. The base class for auth providers makes handling RFC2307-style hashed passwords really simple, so you have no excuse for storing plain-text passwords. like, none. i'm serious 😭

A simple script called dancer2-generate-crypted-password to generate RFC2307-style hashed passwords is included, or you can use Crypt::SaltedHash yourself to do so, or use the slappasswd utility if you have it installed. three options, all valid, pick your fighter ⭐

🦋 SYNOPSIS 🦋

Configure the plugin to use the authentication provider class you wish to use:

plugins:
      Auth::Extensible:
          realms:
              users:
                  provider: Config
                  ....

The configuration you provide will depend on the authentication provider module in use. For a simple example, see Dancer2::Plugin::Auth::Extensible::Provider::Config.

Define that a user must be logged in and have the proper permissions to access a route:

get '/secret' => require_role Confidant => sub { tell_secrets(); };

Define that a user must be logged in to access a route — and find out who is logged in with the logged_in_user keyword:

get '/users' => require_login sub {
    my $user = logged_in_user;
    return "Hi there, $user->{username}";
};

look at that. clean. readable. main character code 💜

👑 AUTHENTICATION PROVIDERS 👑

For flexibility, this authentication framework uses simple authentication provider classes, which implement a simple interface and do whatever is required to authenticate a user against the chosen source of authentication.

For an example of how simple provider classes are, so you can build your own if required or just try out this authentication framework plugin easily, see Dancer2::Plugin::Auth::Extensible::Provider::Config. fr fr, go peek at it.

This framework supplies the following providers out-of-the-box:

Dancer2::Plugin::Auth::Extensible::Provider::Unix — authenticates users using system accounts on Linux/Unix type boxes 🐧
Dancer2::Plugin::Auth::Extensible::Provider::Config — authenticates users stored in the app's config 📝

The following external providers are also available on the CPAN:

Dancer2::Plugin::Auth::Extensible::Provider::DBIC — authenticates users stored in a database table using Dancer2::Plugin::DBIC 🗄️
Dancer2::Plugin::Auth::Extensible::Provider::Database — authenticates users stored in a database table
Dancer2::Plugin::Auth::Extensible::Provider::IMAP — authenticates users via in an IMAP server. 📬
Dancer2::Plugin::Auth::Extensible::Provider::LDAP — authenticates users stored in an LDAP directory.
Dancer2::Plugin::Auth::Extensible::Provider::Usergroup — an alternative Dancer2::Plugin::DBIC-based provider.

Need to write your own? Just create a new provider class which consumes Dancer2::Plugin::Auth::Extensible::Role::Provider and implements the required methods, and you're good to go! slay, build your own 💅✨

🔥 CONTROLLING ACCESS TO ROUTES 🔥

Keywords are provided to check if a user is logged in / has appropriate roles. vibe check for your routes, basically.

🌈 `require_login` — require the user to be logged in

get '/dashboard' => require_login sub { .... };

If the user is not logged in, they will be redirected to the login page URL to log in. The default URL is /login — this may be changed with the login_page option.

🍓 `require_role` — require the user to have a specified role

get '/beer' => require_role BeerDrinker => sub { ... };

Requires that the user be logged in as a user who has the specified role. If the user is not logged in, they will be redirected to the login page URL. If they are logged in, but do not have the required role, they will be redirected to the access denied URL.

⚠️ if the disable_roles configuration option is set to a true value then using require_role will cause the application to croak on load. she will NOT be quiet about it 💀

🧚 `require_any_role` — require the user to have one of a list of roles

get '/drink' => require_any_role [qw(BeerDrinker VodaDrinker)] => sub {
    ...
};

Requires that the user be logged in as a user who has any one (or more) of the roles listed. If the user is not logged in, they will be redirected to the login page URL. If they are logged in, but do not have any of the specified roles, they will be redirected to the access denied URL.

⚠️ if the disable_roles configuration option is set to a true value then using require_any_role will cause the application to croak on load. same energy, no notes 🙈

💜 `require_all_roles` — require the user to have all roles listed

get '/foo' => require_all_roles [qw(Foo Bar)] => sub { ... };

Requires that the user be logged in as a user who has all of the roles listed. If the user is not logged in, they will be redirected to the login page URL. If they are logged in but do not have all of the specified roles, they will be redirected to the access denied URL.

⚠️ if the disable_roles configuration option is set to a true value then using require_all_roles will cause the application to croak on load. she said what she said 🫶

By default when a page is requested that requires login and the user is not logged in then the plugin redirects the user to the login_page and sets return_url to the page originally requested. After successful login the user is redirected to the originally-requested page.

As an alternative if login_without_redirect is true then the login process happens with no redirects. Instead a 401 "Unauthorized" code is returned and a login page is displayed. This login page is posted to the original URI and on successful login an internal forward in Dancer2::Manual is performed so that the originally requested page is displayed. Any params in Dancer2::Manual from the original request are added to the forward so that they are available to the page's route handler either using params in Dancer2::Manual or query_parameters in Dancer2::Manual.

This relies on the login form having no action set and also it must use __auth_extensible_username and __auth_extensible_password input names. Optionally __auth_extensible_realm can also be used in a custom login page. iykyk ✨

See <http://shadow.cat/blog/matt-s-trout/humane-login-screens/> for the original idea for this functionality. credit where credit is due, love that for them 💖

🎀 CUSTOMISING `/login` AND `/login/denied` 🎀

`login_template`

okay so this setting is literally the name of the view you use for your custom login page. if this view exists in your app, it gets used instead of the default login template. slay. 💅

if you're using login_without_redirect and assuming you're on Template::Toolkit, then your custom login page should look something like this:

<h1>Login Required</h1>

<p>You need to log in to continue.</p>

[%- IF login_failed -%]
    <p>LOGIN FAILED</p>
[%- END -%]

<form method="post">
    <label for="username">Username:</label>
    <input type="text" name="__auth_extensible_username" id="username">
    <br />
    <label for="password">Password:</label>
    <input type="password" name="__auth_extensible_password" id="password">
    <br />
    <input type="submit" value="Login">
</form>

[%- IF reset_password_handler -%]
<form method="post" action="[% login_page %]">
    <h2>Password reset</h2>
    <p>Enter your username to obtain an email to reset your password</p>
    <label for="username_reset">Username:</label>
    <input type="text" name="username_reset" id="username_reset">
    <input type="submit" name="submit_reset" value="Submit">
</form>
[%- END -%]

and if you're not using login_without_redirect — still assuming Template::Toolkit bestie — then your custom login page should be something like this:

<h1>Login Required</h1>

<p>You need to log in to continue.</p>

[%- IF login_failed -%]
    <p>LOGIN FAILED</p>
[%- END -%]

<form method="post">
    <label for="username">Username:</label>
    <input type="text" name="username" id="username">
    <br />
    <label for="password">Password:</label>
    <input type="password" name="password" id="password">
    <br />
    <input type="submit" value="Login">

    [%- IF return_url -%]
        <input type="hidden" name="return_url" value="[% return_url %]">
    [%- END -%]

    [%- IF reset_password_handler -%]
        <h2>Password reset</h2>
        <p>Enter your username to obtain an email to reset your password</p>
        <label for="username_reset">Username:</label>
        <input type="text" name="username_reset" id="username_reset">
        <input type="submit" name="submit_reset" value="Submit">
    [%- END -%]

</form>

🔁 Replacing the default `/login` and `/login/denied` routes 🔁

so by default the plugin adds a route that presents a simple login form at that URL. but if you'd rather add your own — valid, iconic, main character energy — set the no_default_pages setting to a true value, and define your own route that responds to /login with a login page. ✨

alternatively you can let DPAE add the routes and handle the status codes and all that, and simply define the setting login_page_handler and/or permission_denied_page_handler with the name of a subroutine to be called to handle the route. note that it must be a fully qualified sub. like this:

plugins:
  Auth::Extensible:
    login_page_handler: 'My::App::login_page_handler'
    permission_denied_page_handler: 'My::App::permission_denied_page_handler'

then in your code you might simply use a template:

sub login_page_handler {
    my $return_url = query_parameters->get('return_url');
    template
        'account/login',
        { title => 'Sign in',
          return_url => $return_url,
        },
        { layout => 'login.tt',
        };
}

sub permission_denied_page_handler {
    template 'account/login';
}

and your account/login.tt template might look like:

[% IF vars.login_failed %]
<div class="alert alert-danger">
    <strong>Login Failed</strong> Try again
    <button type="button" class="close" data-dismiss="alert" aria-label="Close">
        <span aria-hidden="true">&times;</span>
    </button>
</div>
[% END %]

<form method = "post" lpformnum="1" class="form-signin">
    <h2 class="form-signin-heading">Please sign in</h2>
    <label for="username" class="sr-only">Username</label>
    <input type="text" name="username" id="username" class="form-control" placeholder="User name" required autofocus>
    <label for="password" class="sr-only">Password</label>
    <input type="password" name="password" id="password" class="form-control" placeholder="Password" required>
    <button class="btn btn-lg btn-primary btn-block" type="submit">Sign in</button>
    <br>
    <input type="hidden" name="return_url" value="[% return_url %]">
</form>

if the user is logged in but tries to access a route that requires a specific role they don't have, they get redirected to the "permission denied" page URL. that one defaults to /login/denied but you can change it with the denied_page option. 🦋

and again — by default a route is added that responds to that URL with a default page; and again, you can disable this by setting no_default_pages and creating your own. no cap.

but heads up bestie, this would still leave the post '/login' and any '/logout' routes in place. to disable them too, set the option no_login_handler to a true value. in that case, these routes should be defined by the user, and should do at least the following:

post '/login' => sub {
    my ($success, $realm) = authenticate_user(
        params->{username}, params->{password}
    );
    if ($success) {
        # change session ID if we have a new enough D2 version with support
        # (security best practice on privilege level change)
        app->change_session_id
            if app->can('change_session_id');
        session logged_in_user => params->{username};
        session logged_in_user_realm => $realm;
        # other code here
    } else {
        # authentication failed
    }
};

any '/logout' => sub {
    app->destroy_session;
};

if you do want to use the default post '/login' and any '/logout' routes, you can configure them. see below. ⬇️

the default routes also contain functionality for a user to perform password resets. see the PASSWORD RESETS documentation for more details. 🔥

✨ KEYWORDS ✨

these keywords are provided in addition to the route decorators specified in CONTROLLING ACCESS TO ROUTES:

`logged_in_user`

returns a hashref of details of the currently logged-in user — or some kind of user object, if there is one. 💖

the details you get back will depend upon the authentication provider in use. (iykyk)

`get_user_details`

returns a hashref of details of the specified user. the realm can optionally be specified as the second parameter. if the realm is not specified, each realm will be checked, and the first matching user will be returned. 🎀

the details you get back will depend upon the authentication provider in use.

`user_has_role`

checks if a user has the role named.

by default the currently-logged-in user will be checked, so you only need to name the role you're looking for:

if (user_has_role('BeerDrinker')) { pour_beer(); }

you can also provide the username to check:

if (user_has_role($user, $role)) { .... }

⚠️ but fr fr, if the disable_roles configuration option is set to a true value, then using user_has_role will cause the application to croak at runtime. 💀

`user_roles`

returns a list of the roles of a user.

by default, roles for the currently-logged-in user will be checked; alternatively, you may supply a username to check.

returns a list or arrayref depending on context. 🌸

⚠️ same deal: if the disable_roles configuration option is set to a true value, then using user_roles will cause the application to croak at runtime. 💀

`authenticate_user`

usually you'll want to let the built-in login handling code deal with authenticating users, but in case you need to do it yourself, this keyword accepts a username and password, and optionally a specific realm, and checks whether the username and password are valid.

for example:

if (authenticate_user($username, $password)) {
    ...
}

if you're using multiple authentication realms, by default each realm will be consulted in turn. if you only wish to check one of them (for instance, you're authenticating an admin user, and there's only one realm that applies to them), you can supply the realm as an optional third parameter.

in boolean context, returns simply true or false; in list context, returns ($success, $realm). 👑

`logged_in_user_lastlogin`

returns (as a DateTime object) the time of the last successful login of the current logged in user. ⭐

to enable this functionality, set the configuration key record_lastlogin to a true value. the backend provider must support write access for a user and have lastlogin functionality implemented.

`update_user`

updates a user's details. if the authentication provider supports it, this keyword lets a user's details be updated within the backend data store. 🔥

in order to update the user's details, the keyword should be called with the username to be updated, followed by a hash of the values to be updated. note that whilst the password can be updated using this method, any new value will be stored directly into the provider as-is, not encrypted. it is recommended to use user_password instead. 🙈

if only one realm is configured then this will be used to search for the user. otherwise, the realm must be specified with the realm key.

# Update user, only one realm configured
update_user "jsmith", surname => "Smith"

# Update a user's username, more than one realm
update_user "jsmith", realm => "dbic", username => "jjones"

the updated user's details are returned, as per logged_in_user.

`update_current_user`

the same as update_user, but does not take a username as the first parameter — instead it updates the currently logged-in user. 🫶

# Update user, only one realm configured
update_current_user surname => "Smith"

the updated user's details are returned, as per logged_in_user.

`create_user`

creates a new user, if the authentication provider supports it. optionally sends a welcome message with a password reset request, in which case an email key must be provided. if sending welcome emails, see the uri_base configuration parameter: to prevent an attacker creating malicious links, either this must be set or the application must enforce a valid hostname. 🌈

🚨 security bestie moment — that uri_base / valid hostname thing is not optional-vibes, it's literally how you stop an attacker from crafting malicious links. periodt.

Okay so this one works in exactly the same manner as update_user, except — plot twist — the username key is mandatory. No username, no vibes. And same warning as before: it's recommended you don't set a password directly with this method, otherwise it'll be stored in plain text 😭 (plain text!! in this economy!!) don't do it bestie.

The realm you want to use has to be specified with the key realm if there's more than one realm configured.

# Create new user
create_user username => "jsmith", realm => "dbic", surname => "Smith"

# Create new user and send welcome email
create_user username => "jsmith", email => "john@you.com", email_welcome => 1

On success, the created user's details are returned to you, as per logged_in_user. 🎀

The text sent in the welcome email can be customised in 2 ways, in the same way as password_reset_send:

💌 welcome_send

This lets you specify a subroutine that gets called to do the entire message construction and the email sending. Heads up: it has to be a fully-qualified sub, like My::App:email_welcome_send. The subroutine gets passed the dsl as the first parameter, followed by a hash with the keys code, email and user, which contain the generated reset code, the user email address, and the user hashref respectively. For example:

sub reset_send_handler {
    my ($dsl, %params) = @_;
    my $user_email = $params{email};
    my $reset_code = $params{code};
    # Send email
    return $result;
}

📝 welcome_text

This one generates the text for the welcome email, and then this module handles sending the actual email itself. It must be a fully-qualified sub, as per the previous option. It'll be passed the same parameters as welcome_send, and it should return a hash with the same keys as password_reset_send_email.

📨 password_reset_send

password_reset_send sends a user an email with a password reset link. Along with user_password, it lets a user reset their password. Also — big one — see the uri_base configuration parameter: to prevent an attacker creating malicious links, either this must be set or the application must enforce a valid hostname. Like, please. 🙏

The function must be called with the key username and a value that is the username. The username you specify gets sent an email with a link to reset their password. Note that the provider being used must return the email address in the key email, which for a database will normally require that column to exist in the user's table. The provider also has to be able to write values to the user in order for this function to store the generated code. ✍️

Here's the return-value tea ☕: if the username isn't found, a value of 0 is returned. If the username is found and the email is sent successfully, 1 is returned. Otherwise undef is returned.

Note: if you're displaying a success message and you don't want people to be able to check the existence of a user on your system, then you should check for the return value being defined, not true. For example: say "Success" if defined password_reset_send username => username; Slightly annoying caveat: this still leaves the possibility of checking the existence of a user if the email send mechanism is failing. 🫠

The realm can also be specified using the key realm:

password_reset_send username => 'jsmith', realm => 'dbic'

Default text for the email is automatically produced and emailed. This can be customized with one of 2 config parameters:

🧚 password_reset_send_email

This lets you specify a subroutine that'll be called to perform the entire message construction and email sending. Note that it must be a fully-qualified sub, such as My::App:reset_send_handler. The subroutine gets passed the dsl as the first parameter, followed by a hash with the keys code and email, which contain the generated reset code and user email address respectively. For example:

sub reset_send_handler {
    my ($dsl, %params) = @_;
    my $user_email = $params{email};
    my $reset_code = $params{code};
    # Send email
    return $result;
}

🌸 password_reset_text

This one generates the text for the email, and this module sends the actual email itself. It must be a fully-qualified sub, as per the previous option. It'll be passed the same parameters as password_reset_send_email, and should return a hash with the following keys:

subject — the subject of the email message. 👑
from — the sender of the email message (optional, can also be specified using mail_from).
plain — plain text for the email. Either this, or html, or both should be returned. ✨
html — HTML text for the email (optional, as per plain).

Here's an example subroutine:

sub reset_text_handler {
    my ($dsl, %params) = @_;
    return (
        from    => '"My name" <myapp@example.com',
        subject => 'the subject',
        plain   => "reset here: $params{code}",
    );
}

And here's what the config looks like:

# Example configuration

    Auth::Extensible:
        mailer:
            module: Mail::Message # Module to send email with
            options:              # Module options
                via: sendmail
        mail_from: '"My app" <myapp@example.com>'
        password_reset_text: MyApp::reset_send

🔐 user_password

This gives you a whole little toolkit of functions to check or reset a user's password — either from a reset code that was previously sent by password_reset_send, or directly by specifying a username and password. Functions that update a password rely on a provider that has write access to a user's details. ✍️

By default, the user to update is the currently logged-in user. A specific user can be specified with the key username for a certain username, or code for a previously sent reset code. Using these parameters on their own will return the username if it's a valid request. 👀

If the above parameters are specified with the additional parameter new_password, then the password will be set to that value, assuming it's a valid request.

The realm can be optionally specified with the keyword realm.

Examples time, bestie — these are the moves:

Check the logged-in user's password:

user_password password => 'mysecret'

Check a specific user's password:

user_password username => 'jsmith', password => 'bigsecret'

Check a previously sent reset code:

user_password code => 'XXXX'

Reset a password with a previously sent code:

user_password code => 'XXXX', new_password => 'newsecret'

Change a user's password (username optional)

user_password username => 'jbloggs', password => 'old', new_password => 'secret'

Force set a specific user's password, without checking the existing password:

user_password username => 'jbloggs', new_password => 'secret'

⏰ logged_in_user_password_expired

Returns true if the password of the currently logged in user has expired. To use this functionality, the provider must support the password_expired function, and must be configured accordingly. See the relevant provider for full configuration details. 📋

Important note: this functionality does not prevent the user accessing any protected pages, even if the password has expired. That's on purpose — it's so the developer can still leave some protected routes available, like a page to change the password. So if you're using this, it's suggested that a check is done in the before hook: hook before => sub { if (logged_in_user_password_expired) { # Redirect to user details page if password expired, but only if that # is not the currently request page to prevent redirect loops redirect '/password_update' unless request->uri eq '/password_update'; } };

🔁 PASSWORD RESETS

A whole variety of functionality is provided to make it easier to manage requests from users to reset their passwords. The keywords password_reset_send and user_password form the core of this functionality — see the documentation of these keywords for full details. This functionality can only be used with a provider that supports write access. 🫶

When you're utilising this functionality, it's wise to only allow passwords to be reset with a POST request. Why? Because some email scanners "open" links before delivering the email to the end user 😤 — and with only a single-use GET request, the link will end up being "used" by the time it even reaches the end user, thus rendering it invalid. Rude.

Password reset functionality is also built-in to the default route handlers. To enable it, set the configuration value reset_password_handler to a true value (having already configured the mail handler, as per the keyword documentation above). Once that's done, the default login page will contain additional form controls that let the user enter their username and request a reset password link. 🎀

By default, the default handlers will generate a random 8 character password using Session::Token. To use your own function, set password_generator in your configuration. See the SAMPLE CONFIGURATION for an example.

If you're using login_page_handler to replace the default login page, you can still use the default password reset handlers. Just add 2 controls to your form for submitting a password reset request: a text input called username_reset for the username, and submit_reset to submit the request. Your login_page_handler then gets passed these additional params:

new_password — contains the new automatically-generated password, once the password reset has been performed successfully. ✨
reset_sent — is true when a password reset has been emailed to the user. 📬
password_code_valid — is true when a valid password reset code has been submitted with a GET request. In this case, the user should be given the chance to confirm with a POST request, with a form control called confirm_reset.

For a full example, see the default handler in this module's code. 👑

🎀 SAMPLE CONFIGURATION

In your application's configuation file, you're gonna want something like this:

           session: simple
           plugins:
               Auth::Extensible:
                   # Set to 1 if you want to disable the use of roles (0 is default)
                   # If roles are disabled then any use of role-based route decorators
                   # will cause app to croak on load. Use of 'user_roles' and
                   # 'user_has_role' will croak at runtime.
                   disable_roles: 0
                   # Set to 1 to use the no-redirect login functionality
                   login_without_redirect: 0
                   # Set the view name for a custom login page, defaults to 'login'
                   login_template: login
                   # After /login: If no return_url is given: land here ('/' is default)
                   user_home_page: '/user'
                   # After /logout: If no return_url is given: land here (no default)
                   exit_page: '/'

                   # Mailer options for reset password and welcome emails
                   mailer:
                       module: Mail::Message # Email module to use
                       options:              # Options for module
                           via: sendmail     # Options passed to $msg->send
                   mail_from: '"App name" <myapp@example.com>' # From email address

                   # Set to true to enable password reset code in the default handlers
                   reset_password_handler: 1
                   password_generator: My::App::random_pw # Optional random password generator

                   # Set to a true value to enable recording of successful last login times
                   record_lastlogin: 1

                   # Password reset functionality
                   password_reset_send_email: My::App::reset_send # Customise sending sub
                   password_reset_text: My::App::reset_text # Customise reset text

                   # Specify the base hostname for URIs generated by the plugin. By
                   # default this will be lazily-built from a value obtained from
                   # Dancer (which uses the request header supplied by the client).
                   # Because this can be controlled by an attacker, it is recommended
                   # to force the value here, unless your application enforces this
                   # value in other ways (e.g. redirecting within the application in
                   # the event that the specified hostname is unknown). The value
                   # specified here will be coerced into a URI object.
                   uri_base: https://myserver.example.com

                   # create_user options
                   welcome_send: My::App::welcome_send # Customise welcome email sub
                   welcome_text: My::App::welcome_text # Customise welcome email text

                   # List each authentication realm, with the provider to use and the
                   # provider-specific settings (see the documentation for the provider
                   # you wish to use)
                   realms:
                       realm_one:
                           priority: 3 # Defaults to 0. Realms are checked in descending order
                           provider: Database
                               db_connection_name: 'foo'
                       realm_two:
                           priority: 0 # Will be checked after realm_one
                           provider: Config

Okay so that's the whole config vibe, and one thing I need to scream at you: you must have a session provider configured. Not optional, not a suggestion, not a "ehhh I'll do it later" — the authentication framework literally needs sessions to track info about whoever's currently logged in. 💅 Go read Dancer2::Core::Session for how to set up session management inside your app. iykyk.

✨ METHODS ✨

🎀 `auth_provider($dsl, $realm)`

You give it a realm, it hands you back a fully configured, ready-to-go instance of whatever provider that realm's config points at. Plug and play, bestie. 🫶

🪝 HOOKS 🪝

This plugin gives you the following hooks — think of them as little checkpoints where you can jump in and do your thing:

`before_authenticate_user`

Fires at the start of authenticate_user.

It receives a hash reference containing username, password and realm. 📬

`after_authenticate_user`

Fires at the end of authenticate_user.

It receives a hash reference of username, password, realm, errors and success.

realm is the realm the user authenticated against — or undef if auth failed. 😭
errors is an array reference of any errors thrown by authentication providers (if any, no pressure).
success is either 1 or 0, showing whether authentication worked or flopped.

`before_create_user`

Fires at the start of create_user.

It receives a hash reference of the arguments that were passed to create_user. ✨

`after_create_user`

Fires at the end of create_user.

It receives the requested username, the created user (or undef), and an array reference of any errors from the main method or from the provider. 👑

`login_required`

`permission_denied`

Those two are literally just listed here with no extra notes in the docs — that's the whole tea. 🍵

`after_reset_code_success`

Fires after a successful reset code has been provided. It's your moment to flex a custom 'Change password' page or any other app-based intervention once the reset code's been successfully applied. 🎀

`after_login_success`

Fires after a successful login — literally just before redirect gets called. Blink and you'll miss it. 🔥

`before_logout`

Fires just before the session gets destroyed on logout. Say bye to the session bestie. 👋

🔒 SECURITY CONSIDERATIONS 🔒

Real talk: if you don't use this module correctly, it can potentially be abused to insert malicious URIs into the emails it generates. Not cute. 🙈

Check the docs for uri_base, create_user and password_reset_send before you ship anything. fr fr.

👑 AUTHOR 👑

David Precious, "<davidp at preshweb.co.uk>"

Dancer2 port of Dancer::Plugin::Auth::Extensible by:

Stefan Hornburg (Racke), "<racke at linuxia.de>"

Conversion to Dancer2's new plugin system plus much cleanup & reorg:

Peter Mottram (SysPete), "<peter at sysnix.com>"

💀 BUGS / FEATURE REQUESTS 💀

This is an early version — so yeah, there may still be bugs lurking, or features that just aren't there yet. No cap.

It's developed on GitHub, so please feel free to raise issues or pull requests against the repo at: <https://github.com/PerlDancer/Dancer2-Plugin-Auth-Extensible>

🌸 ACKNOWLEDGEMENTS 🌸

Valuable feedback on the early design of this module came from many people, including Matt S Trout (mst), David Golden (xdg), Damien Krotkine (dams), Daniel Perrett, and others. Legends, honestly. 🫶

Configurable login/logout URLs added by Rene (hertell)
Regex support for require_role by chenryn
Support for user_roles looking in other realms by Colin Ewen (casao)
LDAP provider added by Mark Meyer (ofosos)
Documentation fix by Vince Willems.
Henk van Oers (GH #8, #13, #55).
Andrew Beverly (GH #6, #7, #10, #17, #22, #24, #25, #26, #54). This includes support for creating and editing users and manage user passwords.
Gabor Szabo (GH #11, #16, #18).
Evan Brown (GH #20, #32).
Jason Lewis (Unix provider problem, GH#62).
Matt S. Trout (mst) for Zero redirect login the easy and friendly way <http://shadow.cat/blog/matt-s-trout/humane-login-screens/>.
Ben Kaufman "whosgonna" (GH#79)
Dominic Sonntag (GH#70)

📜 LICENSE AND COPYRIGHT 📜

This program is free software; you can redistribute it and/or modify it under the terms of either: the GNU General Public License as published by the Free Software Foundation; or the Artistic License.

See <http://dev.perl.org/licenses/> for more information.

And that's the whole page, bestie — you made it to the end! 🎉 This one's the Dancer2...tensible(3) page from User Contributed Perl Documentation, served up by perl v5.42.0 and dated 2026-08-25. Go forth and authenticate responsibly. 💖✨🎀

📦 where this page comes from

opensuse-leap 16.0: perl-Dancer2-Plugin-Auth-Extensible 0.714.0-bp160.1.1 · Artistic-1.0 OR GPL-1.0-or-later
💖 girlified by deepseek-ai/DeepSeek-V4.1-Flash-1017 on 2026-11-04: a language model's rewrite of the original, under its terms

Dancer2...tensible(3)

💖 Dancer2::Plugin::Auth::Extensible — the auth glow-up your Dancer2 app deserves ✨

🌸 NAME 🌸

🎀 DESCRIPTION 🎀

🦋 SYNOPSIS 🦋

👑 AUTHENTICATION PROVIDERS 👑

🔥 CONTROLLING ACCESS TO ROUTES 🔥

🌈 require_login — require the user to be logged in

🍓 require_role — require the user to have a specified role

🧚 require_any_role — require the user to have one of a list of roles

💜 require_all_roles — require the user to have all roles listed

🦄 NO-REDIRECT LOGIN 🦄

🎀 CUSTOMISING /login AND /login/denied 🎀

login_template

🔁 Replacing the default /login and /login/denied routes 🔁

✨ KEYWORDS ✨

logged_in_user

get_user_details

user_has_role

user_roles

authenticate_user

logged_in_user_lastlogin

update_user

update_current_user

create_user