Replacing the Default " /login " and " /login/denied " Routes

By default, the plugin adds a route to present a simple login form at that URL. If you would rather add your own, set the "no_default_pages" setting to a true value, and define your own route which responds to "/login" with a login page. Alternatively you can let DPAE add the routes and handle the status codes, etc. 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. E.g.

    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 permission_denied_page_handler {
        template 'account/login';
    }

If the user is logged in, but tries to access a route which requires a specific role they don't have, they will be redirected to the "permission denied" page URL, which defaults to "/login/denied" but may be changed using the "denied_page" option.

Again, by default a route is added to respond to that URL with a default page; again, you can disable this by setting "no_default_pages" and creating your own.

This would still leave the routes "post '/login'" and "any '/logout'" routes in place. To disable them too, set the option "no_login_handler" to a true value. In this 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) {
            session logged_in_user => params->{username};
            session logged_in_user_realm => $realm;
            # other code here
        } else {
            # authentication failed
        }
    };
    
    any '/logout' => sub {
        session->destroy;
    };

If you want to use the default "post '/login'" and "any '/logout'" routes you can configure them. See below.

Keywords

require_login

Used to wrap a route which requires a user to be logged in order to access it.

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

require_role

Used to wrap a route which requires a user to be logged in as a user with the specified role in order to access it.

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

You can also provide a regular expression, if you need to match the role using a regex - for example:

    get '/beer' => require_role qr/Drinker$/ => sub { ... };
    

require_any_role

Used to wrap a route which requires a user to be logged in as a user with any one (or more) of the specified roles in order to access it.

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

require_all_roles

Used to wrap a route which requires a user to be logged in as a user with all of the roles listed in order to access it.

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

logged_in_user

Returns a hashref of details of the currently logged-in user, if there is one.

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

user_has_role

Check if a user has the role named.

By default, the currently-logged-in user will be checked, so you need only 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)) { .... }
    

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.

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 are 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 which 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)".

SAMPLE CONFIGURATION

In your application's configuration file:

    session: simple
    plugins:
        Auth::Extensible:
            # Set to 1 if you want to disable the use of roles (0 is default)
            disable_roles: 0
            # 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: '/'
            
            # 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:
                    provider: Database
                        db_connection_name: 'foo'

Please note that you must have a session provider configured. The authentication framework requires sessions in order to track information about the currently logged in user. Please see Dancer::Session for information on how to configure session management within your application.