{"id":28614171,"url":"https://github.com/perldancer/dancer2-plugin-auth-extensible","last_synced_at":"2025-06-12T01:13:21.699Z","repository":{"id":15888737,"uuid":"18629991","full_name":"PerlDancer/Dancer2-Plugin-Auth-Extensible","owner":"PerlDancer","description":"Extensible authentication framework for Dancer2 apps","archived":false,"fork":false,"pushed_at":"2024-08-29T10:27:32.000Z","size":812,"stargazers_count":9,"open_issues_count":13,"forks_count":20,"subscribers_count":10,"default_branch":"master","last_synced_at":"2024-12-06T20:01:43.597Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"Perl","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/PerlDancer.png","metadata":{"files":{"readme":"README","changelog":"Changes","contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2014-04-10T08:53:01.000Z","updated_at":"2024-08-29T10:27:35.000Z","dependencies_parsed_at":"2023-02-10T06:00:41.601Z","dependency_job_id":null,"html_url":"https://github.com/PerlDancer/Dancer2-Plugin-Auth-Extensible","commit_stats":null,"previous_names":[],"tags_count":34,"template":false,"template_full_name":null,"purl":"pkg:github/PerlDancer/Dancer2-Plugin-Auth-Extensible","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/PerlDancer%2FDancer2-Plugin-Auth-Extensible","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/PerlDancer%2FDancer2-Plugin-Auth-Extensible/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/PerlDancer%2FDancer2-Plugin-Auth-Extensible/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/PerlDancer%2FDancer2-Plugin-Auth-Extensible/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/PerlDancer","download_url":"https://codeload.github.com/PerlDancer/Dancer2-Plugin-Auth-Extensible/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/PerlDancer%2FDancer2-Plugin-Auth-Extensible/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":259374995,"owners_count":22847878,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-06-12T01:13:20.909Z","updated_at":"2025-06-12T01:13:21.687Z","avatar_url":"https://github.com/PerlDancer.png","language":"Perl","funding_links":[],"categories":[],"sub_categories":[],"readme":"NAME\n\n    Dancer2::Plugin::Auth::Extensible - extensible authentication framework\n    for Dancer2 apps\n\nDESCRIPTION\n\n    A user authentication and authorisation framework plugin for Dancer2\n    apps.\n\n    Makes it easy to require a user to be logged in to access certain\n    routes, provides role-based access control, and supports various\n    authentication methods/sources (config file, database, Unix system\n    users, etc).\n\n    Designed to support multiple authentication realms and to be as\n    extensible as possible, and to make secure password handling easy. The\n    base class for auth providers makes handling RFC2307-style hashed\n    passwords really simple, so you have no excuse for storing plain-text\n    passwords. A simple script called dancer2-generate-crypted-password to\n    generate RFC2307-style hashed passwords is included, or you can use\n    Crypt::SaltedHash yourself to do so, or use the slappasswd utility if\n    you have it installed.\n\nSYNOPSIS\n\n    Configure the plugin to use the authentication provider class you wish\n    to use:\n\n      plugins:\n            Auth::Extensible:\n                realms:\n                    users:\n                        provider: Config\n                        ....\n\n    The configuration you provide will depend on the authentication\n    provider module in use. For a simple example, see\n    Dancer2::Plugin::Auth::Extensible::Provider::Config.\n\n    Define that a user must be logged in and have the proper permissions to\n    access a route:\n\n        get '/secret' =\u003e require_role Confidant =\u003e sub { tell_secrets(); };\n\n    Define that a user must be logged in to access a route - and find out\n    who is logged in with the logged_in_user keyword:\n\n        get '/users' =\u003e require_login sub {\n            my $user = logged_in_user;\n            return \"Hi there, $user-\u003e{username}\";\n        };\n\nAUTHENTICATION PROVIDERS\n\n    For flexibility, this authentication framework uses simple\n    authentication provider classes, which implement a simple interface and\n    do whatever is required to authenticate a user against the chosen\n    source of authentication.\n\n    For an example of how simple provider classes are, so you can build\n    your own if required or just try out this authentication framework\n    plugin easily, see Dancer2::Plugin::Auth::Extensible::Provider::Config.\n\n    This framework supplies the following providers out-of-the-box:\n\n    Dancer2::Plugin::Auth::Extensible::Provider::Unix\n\n      Authenticates users using system accounts on Linux/Unix type boxes\n\n    Dancer2::Plugin::Auth::Extensible::Provider::Config\n\n      Authenticates users stored in the app's config\n\n    The following external providers are also available on the CPAN:\n\n    Dancer2::Plugin::Auth::Extensible::Provider::DBIC\n\n      Authenticates users stored in a database table using\n      Dancer2::Plugin::DBIC\n\n    Dancer2::Plugin::Auth::Extensible::Provider::Database\n\n      Authenticates users stored in a database table\n\n    Dancer2::Plugin::Auth::Extensible::Provider::IMAP\n\n      Authenticates users via in an IMAP server.\n\n    Dancer2::Plugin::Auth::Extensible::Provider::LDAP\n\n      Authenticates users stored in an LDAP directory.\n\n    Dancer2::Plugin::Auth::Extensible::Provider::Usergroup\n\n      An alternative Dancer2::Plugin::DBIC-based provider.\n\n    Need to write your own? Just create a new provider class which consumes\n    Dancer2::Plugin::Auth::Extensible::Role::Provider and implements the\n    required methods, and you're good to go!\n\nCONTROLLING ACCESS TO ROUTES\n\n    Keywords are provided to check if a user is logged in / has appropriate\n    roles.\n\n require_login - require the user to be logged in\n\n        get '/dashboard' =\u003e require_login sub { .... };\n\n    If the user is not logged in, they will be redirected to the login page\n    URL to log in. The default URL is /login - this may be changed with the\n    login_page option.\n\n require_role - require the user to have a specified role\n\n        get '/beer' =\u003e require_role BeerDrinker =\u003e sub { ... };\n\n    Requires that the user be logged in as a user who has the specified\n    role. If the user is not logged in, they will be redirected to the\n    login page URL. If they are logged in, but do not have the required\n    role, they will be redirected to the access denied URL.\n\n    If disable_roles configuration option is set to a true value then using\n    \"require_role\" will cause the application to croak on load.\n\n require_any_role - require the user to have one of a list of roles\n\n        get '/drink' =\u003e require_any_role [qw(BeerDrinker VodaDrinker)] =\u003e sub {\n            ...\n        };\n\n    Requires that the user be logged in as a user who has any one (or more)\n    of the roles listed. If the user is not logged in, they will be\n    redirected to the login page URL. If they are logged in, but do not\n    have any of the specified roles, they will be redirected to the access\n    denied URL.\n\n    If disable_roles configuration option is set to a true value then using\n    \"require_any_roles\" will cause the application to croak on load.\n\n require_all_roles - require the user to have all roles listed\n\n        get '/foo' =\u003e require_all_roles [qw(Foo Bar)] =\u003e sub { ... };\n\n    Requires that the user be logged in as a user who has all of the roles\n    listed. If the user is not logged in, they will be redirected to the\n    login page URL. If they are logged in but do not have all of the\n    specified roles, they will be redirected to the access denied URL.\n\n    If disable_roles configuration option is set to a true value then using\n    \"require_all_roles\" will cause the application to croak on load.\n\nNO-REDIRECT LOGIN\n\n    By default when a page is requested that requires login and the user is\n    not logged in then the plugin redirects the user to the \"login_page\"\n    and sets return_url to the page originally requested. After successful\n    login the user is redirected to the originally-requested page.\n\n    As an alternative if \"login_without_redirect\" is true then the login\n    process happens with no redirects. Instead a 401 Unauthorized code is\n    returned and a login page is displayed. This login page is posted to\n    the original URI and on successful login an internal \"forward\" in\n    Dancer2::Manual is performed so that the originally requested page is\n    displayed. Any \"params\" in Dancer2::Manual from the original request\n    are added to the forward so that they are available to the page's route\n    handler either using \"params\" in Dancer2::Manual or \"query_parameters\"\n    in Dancer2::Manual.\n\n    This relies on the login form having no action set and also it must use\n    __auth_extensible_username and __auth_extensible_password input names.\n    Optionally __auth_extensible_realm can also be used in a custom login\n    page.\n\n    See http://shadow.cat/blog/matt-s-trout/humane-login-screens/ for the\n    original idea for this functionality.\n\nCUSTOMISING /login AND /login/denied\n\n login_template\n\n    The \"login_template\" setting determines the name of the view you use\n    for your custom login page. If this view exists in your application\n    then it will be used instead of the default login template.\n\n    If you are using \"login_without_redirect\" and assuming you are using\n    Template::Toolkit then your custom login page should be something like\n    this:\n\n        \u003ch1\u003eLogin Required\u003c/h1\u003e\n    \n        \u003cp\u003eYou need to log in to continue.\u003c/p\u003e\n    \n        [%- IF login_failed -%]\n            \u003cp\u003eLOGIN FAILED\u003c/p\u003e\n        [%- END -%]\n    \n        \u003cform method=\"post\"\u003e\n            \u003clabel for=\"username\"\u003eUsername:\u003c/label\u003e\n            \u003cinput type=\"text\" name=\"__auth_extensible_username\" id=\"username\"\u003e\n            \u003cbr /\u003e\n            \u003clabel for=\"password\"\u003ePassword:\u003c/label\u003e\n            \u003cinput type=\"password\" name=\"__auth_extensible_password\" id=\"password\"\u003e\n            \u003cbr /\u003e\n            \u003cinput type=\"submit\" value=\"Login\"\u003e\n        \u003c/form\u003e\n    \n        [%- IF reset_password_handler -%]\n        \u003cform method=\"post\" action=\"[% login_page %]\"\u003e\n            \u003ch2\u003ePassword reset\u003c/h2\u003e\n            \u003cp\u003eEnter your username to obtain an email to reset your password\u003c/p\u003e\n            \u003clabel for=\"username_reset\"\u003eUsername:\u003c/label\u003e\n            \u003cinput type=\"text\" name=\"username_reset\" id=\"username_reset\"\u003e\n            \u003cinput type=\"submit\" name=\"submit_reset\" value=\"Submit\"\u003e\n        \u003c/form\u003e\n        [%- END -%]\n\n    If you are not using \"login_without_redirect\" and assuming you are\n    using Template::Toolkit then your custom login page should be something\n    like this:\n\n        \u003ch1\u003eLogin Required\u003c/h1\u003e\n    \n        \u003cp\u003eYou need to log in to continue.\u003c/p\u003e\n    \n        [%- IF login_failed -%]\n            \u003cp\u003eLOGIN FAILED\u003c/p\u003e\n        [%- END -%]\n    \n        \u003cform method=\"post\"\u003e\n            \u003clabel for=\"username\"\u003eUsername:\u003c/label\u003e\n            \u003cinput type=\"text\" name=\"username\" id=\"username\"\u003e\n            \u003cbr /\u003e\n            \u003clabel for=\"password\"\u003ePassword:\u003c/label\u003e\n            \u003cinput type=\"password\" name=\"password\" id=\"password\"\u003e\n            \u003cbr /\u003e\n            \u003cinput type=\"submit\" value=\"Login\"\u003e\n    \n            [%- IF return_url -%]\n                \u003cinput type=\"hidden\" name=\"return_url\" value=\"[% return_url %]\"\u003e\n            [%- END -%]\n    \n            [%- IF reset_password_handler -%]\n                \u003ch2\u003ePassword reset\u003c/h2\u003e\n                \u003cp\u003eEnter your username to obtain an email to reset your password\u003c/p\u003e\n                \u003clabel for=\"username_reset\"\u003eUsername:\u003c/label\u003e\n                \u003cinput type=\"text\" name=\"username_reset\" id=\"username_reset\"\u003e\n                \u003cinput type=\"submit\" name=\"submit_reset\" value=\"Submit\"\u003e\n            [%- END -%]\n    \n        \u003c/form\u003e\n\n Replacing the default\t/login\tand  /login/denied  routes\n\n    By default, the plugin adds a route to present a simple login form at\n    that URL. If you would rather add your own, set the no_default_pages\n    setting to a true value, and define your own route which responds to\n    /login with a login page. Alternatively you can let DPAE add the routes\n    and handle the status codes, etc. and simply define the setting\n    login_page_handler and/or permission_denied_page_handler with the name\n    of a subroutine to be called to handle the route. Note that it must be\n    a fully qualified sub. E.g.\n\n        plugins:\n          Auth::Extensible:\n            login_page_handler: 'My::App::login_page_handler'\n            permission_denied_page_handler: 'My::App::permission_denied_page_handler'\n\n    Then in your code you might simply use a template:\n\n        sub login_page_handler {\n            my $return_url = query_parameters-\u003eget('return_url');\n            template\n                'account/login',\n                { title =\u003e 'Sign in',\n                  return_url =\u003e $return_url,\n                },\n                { layout =\u003e 'login.tt',\n                };\n        }\n    \n        sub permission_denied_page_handler {\n            template 'account/login';\n        }\n\n    and your account/login.tt template might look like:\n\n        [% IF vars.login_failed %]\n        \u003cdiv class=\"alert alert-danger\"\u003e\n            \u003cstrong\u003eLogin Failed\u003c/strong\u003e Try again\n            \u003cbutton type=\"button\" class=\"close\" data-dismiss=\"alert\" aria-label=\"Close\"\u003e\n                \u003cspan aria-hidden=\"true\"\u003e\u0026times;\u003c/span\u003e\n            \u003c/button\u003e\n        \u003c/div\u003e\n        [% END %]\n    \n        \u003cform method = \"post\" lpformnum=\"1\" class=\"form-signin\"\u003e\n            \u003ch2 class=\"form-signin-heading\"\u003ePlease sign in\u003c/h2\u003e\n            \u003clabel for=\"username\" class=\"sr-only\"\u003eUsername\u003c/label\u003e\n            \u003cinput type=\"text\" name=\"username\" id=\"username\" class=\"form-control\" placeholder=\"User name\" required autofocus\u003e\n            \u003clabel for=\"password\" class=\"sr-only\"\u003ePassword\u003c/label\u003e\n            \u003cinput type=\"password\" name=\"password\" id=\"password\" class=\"form-control\" placeholder=\"Password\" required\u003e\n            \u003cbutton class=\"btn btn-lg btn-primary btn-block\" type=\"submit\"\u003eSign in\u003c/button\u003e\n            \u003cbr\u003e\n            \u003cinput type=\"hidden\" name=\"return_url\" value=\"[% return_url %]\"\u003e\n        \u003c/form\u003e\n\n    If the user is logged in, but tries to access a route which requires a\n    specific role they don't have, they will be redirected to the\n    \"permission denied\" page URL, which defaults to /login/denied but may\n    be changed using the denied_page option.\n\n    Again, by default a route is added to respond to that URL with a\n    default page; again, you can disable this by setting no_default_pages\n    and creating your own.\n\n    This would still leave the routes post '/login' and any '/logout'\n    routes in place. To disable them too, set the option no_login_handler\n    to a true value. In this case, these routes should be defined by the\n    user, and should do at least the following:\n\n        post '/login' =\u003e sub {\n            my ($success, $realm) = authenticate_user(\n                params-\u003e{username}, params-\u003e{password}\n            );\n            if ($success) {\n                # change session ID if we have a new enough D2 version with support\n                # (security best practice on privilege level change)\n                app-\u003echange_session_id\n                    if app-\u003ecan('change_session_id');\n                session logged_in_user =\u003e params-\u003e{username};\n                session logged_in_user_realm =\u003e $realm;\n                # other code here\n            } else {\n                # authentication failed\n            }\n        };\n        \n        any '/logout' =\u003e sub {\n            app-\u003edestroy_session;\n        };\n\n    If you want to use the default post '/login' and any '/logout' routes\n    you can configure them. See below.\n\n    The default routes also contain functionality for a user to perform\n    password resets. See the \"PASSWORD RESETS\" documentation for more\n    details.\n\nKEYWORDS\n\n    The following keywords are provided in additional to the route\n    decorators specified in \"CONTROLLING ACCESS TO ROUTES\":\n\n logged_in_user\n\n    Returns a hashref of details of the currently logged-in user or some\n    kind of user object, if there is one.\n\n    The details you get back will depend upon the authentication provider\n    in use.\n\n get_user_details\n\n    Returns a hashref of details of the specified user. The realm can\n    optionally be specified as the second parameter. If the realm is not\n    specified, each realm will be checked, and the first matching user will\n    be returned.\n\n    The details you get back will depend upon the authentication provider\n    in use.\n\n user_has_role\n\n    Check if a user has the role named.\n\n    By default, the currently-logged-in user will be checked, so you need\n    only name the role you're looking for:\n\n        if (user_has_role('BeerDrinker')) { pour_beer(); }\n\n    You can also provide the username to check;\n\n        if (user_has_role($user, $role)) { .... }\n\n    If disable_roles configuration option is set to a true value then using\n    \"user_has_role\" will cause the application to croak at runtime.\n\n user_roles\n\n    Returns a list of the roles of a user.\n\n    By default, roles for the currently-logged-in user will be checked;\n    alternatively, you may supply a username to check.\n\n    Returns a list or arrayref depending on context.\n\n    If disable_roles configuration option is set to a true value then using\n    \"user_roles\" will cause the application to croak at runtime.\n\n authenticate_user\n\n    Usually you'll want to let the built-in login handling code deal with\n    authenticating users, but in case you need to do it yourself, this\n    keyword accepts a username and password, and optionally a specific\n    realm, and checks whether the username and password are valid.\n\n    For example:\n\n        if (authenticate_user($username, $password)) {\n            ...\n        }\n\n    If you are using multiple authentication realms, by default each realm\n    will be consulted in turn. If you only wish to check one of them (for\n    instance, you're authenticating an admin user, and there's only one\n    realm which applies to them), you can supply the realm as an optional\n    third parameter.\n\n    In boolean context, returns simply true or false; in list context,\n    returns ($success, $realm).\n\n logged_in_user_lastlogin\n\n    Returns (as a DateTime object) the time of the last successful login of\n    the current logged in user.\n\n    To enable this functionality, set the configuration key\n    record_lastlogin to a true value. The backend provider must support\n    write access for a user and have lastlogin functionality implemented.\n\n update_user\n\n    Updates a user's details. If the authentication provider supports it,\n    this keyword allows a user's details to be updated within the backend\n    data store.\n\n    In order to update the user's details, the keyword should be called\n    with the username to be updated, followed by a hash of the values to be\n    updated. Note that whilst the password can be updated using this\n    method, any new value will be stored directly into the provider as-is,\n    not encrypted. It is recommended to use \"user_password\" instead.\n\n    If only one realm is configured then this will be used to search for\n    the user. Otherwise, the realm must be specified with the realm key.\n\n        # Update user, only one realm configured\n        update_user \"jsmith\", surname =\u003e \"Smith\"\n    \n        # Update a user's username, more than one realm\n        update_user \"jsmith\", realm =\u003e \"dbic\", username =\u003e \"jjones\"\n\n    The updated user's details are returned, as per logged_in_user.\n\n update_current_user\n\n    The same as update_user, but does not take a username as the first\n    parameter, instead updating the currently logged-in user.\n\n        # Update user, only one realm configured\n        update_current_user surname =\u003e \"Smith\"\n\n    The updated user's details are returned, as per logged_in_user.\n\n create_user\n\n    Creates a new user, if the authentication provider supports it.\n    Optionally sends a welcome message with a password reset request, in\n    which case an email key must be provided.\n\n    This function works in the same manner as update_user, except that the\n    username key is mandatory. As with update_user, it is recommended not\n    to set a password directly using this method, otherwise it will be\n    stored in plain text.\n\n    The realm to use must be specified with the key realm if there is more\n    than one realm configured.\n\n        # Create new user\n        create_user username =\u003e \"jsmith\", realm =\u003e \"dbic\", surname =\u003e \"Smith\"\n    \n        # Create new user and send welcome email\n        create_user username =\u003e \"jsmith\", email =\u003e \"john@you.com\", email_welcome =\u003e 1\n\n    On success, the created user's details are returned, as per\n    logged_in_user.\n\n    The text sent in the welcome email can be customised in 2 ways, in the\n    same way as password_reset_send:\n\n    welcome_send\n\n      This can be used to specify a subroutine that will be called to\n      perform the entire message construction and email sending. Note that\n      it must be a fully-qualified sub such as My::App:email_welcome_send.\n      The subroutine will be passed the dsl as the first parameter,\n      followed by a hash with the keys code, email and user, which contain\n      the generated reset code, user email address, and user hashref\n      respectively. For example:\n\n          sub reset_send_handler {\n              my ($dsl, %params) = @_;\n              my $user_email = $params{email};\n              my $reset_code = $params{code};\n              # Send email\n              return $result;\n          }\n\n    welcome_text\n\n      This can be used to generate the text for the welcome email, with\n      this module sending the actual email itself. It must be a\n      fully-qualified sub, as per the previous option. It will be passed\n      the same parameters as welcome_send, and should return a hash with\n      the same keys as password_reset_send_email.\n\n password_reset_send\n\n    \"password_reset_send\" sends a user an email with a password reset link.\n    Along with \"user_password\", it allows a user to reset their password.\n\n    The function must be called with the key username and a value that is\n    the username. The username specified will be sent an email with a link\n    to reset their password. Note that the provider being used must return\n    the email address in the key email, which in the case of a database\n    will normally require that column to exist in the user's table. The\n    provider must be able to write values to the user in order for this\n    function to store the generated code.\n\n    If the username is not found, a value of 0 is returned. If the username\n    is found and the email is sent successfully, 1 is returned. Otherwise\n    undef is returned. Note: if you are displaying a success message, and\n    you do not want people to be able to check the existance of a user on\n    your system, then you should check for the return value being defined,\n    not true. For example:\n\n        say \"Success\" if defined password_reset_send username =\u003e username;\n\n    Note that this still leaves the possibility of checking the existance\n    of a user if the email send mechanism is failing.\n\n    The realm can also be specified using the key realm:\n\n        password_reset_send username =\u003e 'jsmith', realm =\u003e 'dbic'\n\n    Default text for the email is automatically produced and emailed. This\n    can be customized with one of 2 config parameters:\n\n    password_reset_send_email\n\n      This can be used to specify a subroutine that will be called to\n      perform the entire message construction and email sending. Note that\n      it must be a fully-qualified sub such as My::App:reset_send_handler.\n      The subroutine will be passed the dsl as the first parameter,\n      followed by a hash with the keys code and email, which contain the\n      generated reset code and user email address respectively. For\n      example:\n\n          sub reset_send_handler {\n              my ($dsl, %params) = @_;\n              my $user_email = $params{email};\n              my $reset_code = $params{code};\n              # Send email\n              return $result;\n          }\n\n    password_reset_text\n\n      This can be used to generate the text for the email, with this module\n      sending the actual email itself. It must be a fully-qualified sub, as\n      per the previous option. It will be passed the same parameters as\n      password_reset_send_email, and should return a hash with the\n      following keys:\n\n      subject\n\n\tThe subject of the email message.\n\n      from\n\n\tThe sender of the email message (optional, can also be specified\n\tusing mail_from.\n\n      plain\n\n\tPlain text for the email. Either this, or html, or both should be\n\treturned.\n\n      html\n\n\tHTML text for the email (optional, as per plain).\n\n      Here is an example subroutine:\n\n          sub reset_text_handler {\n              my ($dsl, %params) = @_;\n              return (\n                  from    =\u003e '\"My name\" \u003cmyapp@example.com',\n                  subject =\u003e 'the subject',\n                  plain   =\u003e \"reset here: $params{code}\",\n              );\n          }\n\n      # Example configuration\n\n          Auth::Extensible:\n              mailer:\n                  module: Mail::Message # Module to send email with\n                  options:              # Module options\n                      via: sendmail\n              mail_from: '\"My app\" \u003cmyapp@example.com\u003e'\n              password_reset_text: MyApp::reset_send\n\n user_password\n\n    This provides various functions to check or reset a user's password,\n    either from a reset code that was previously send by\n    password_reset_send or directly by specifying a username and password.\n    Functions that update a password rely on a provider that has write\n    access to a user's details.\n\n    By default, the user to update is the currently logged-in user. A\n    specific user can be specified with the key username for a certain\n    username, or code for a previously sent reset code. Using these\n    parameters on their own will return the username if it is a valid\n    request.\n\n    If the above parameters are specified with the additional parameter\n    new_password, then the password will be set to that value, assuming\n    that it is a valid request.\n\n    The realm can be optionally specified with the keyword realm.\n\n    Examples:\n\n    Check the logged-in user's password:\n\n        user_password password =\u003e 'mysecret'\n\n    Check a specific user's password:\n\n        user_password username =\u003e 'jsmith', password =\u003e 'bigsecret'\n\n    Check a previously sent reset code:\n\n        user_password code =\u003e 'XXXX'\n\n    Reset a password with a previously sent code:\n\n        user_password code =\u003e 'XXXX', new_password =\u003e 'newsecret'\n\n    Change a user's password (username optional)\n\n        user_password username =\u003e 'jbloggs', password =\u003e 'old', new_password =\u003e 'secret'\n\n    Force set a specific user's password, without checking existing\n    password:\n\n        user_password username =\u003e 'jbloggs', new_password =\u003e 'secret'\n\n logged_in_user_password_expired\n\n    Returns true if the password of the currently logged in user has\n    expired. To use this functionality, the provider must support the\n    password_expired function, and must be configured accordingly. See the\n    relevant provider for full configuration details.\n\n    Note that this functionality does not prevent the user accessing any\n    protected pages, even if the password has expired. This is so that the\n    developer can still leave some protected routes available, such as a\n    page to change the password. Therefore, if using this functionality, it\n    is suggested that a check is done in the before hook:\n\n        hook before =\u003e sub {\n            if (logged_in_user_password_expired)\n            {\n                # Redirect to user details page if password expired, but only if that\n                # is not the currently request page to prevent redirect loops\n                redirect '/password_update' unless request-\u003euri eq '/password_update';\n            }\n        }\n\n PASSWORD RESETS\n\n    A variety of functionality is provided to make it easier to manage\n    requests from users to reset their passwords. The keywords\n    password_reset_send and user_password form the core of this\n    functionality - see the documentation of these keywords for full\n    details. This functionality can only be used with a provider that\n    supports write access.\n\n    When utilising this functionality, it is wise to only allow passwords\n    to be reset with a POST request. This is because some email scanners\n    \"open\" links before delivering the email to the end user. With only a\n    single-use GET request, this will result in the link being \"used\" by\n    the time it reaches the end user, thus rendering it invalid.\n\n    Password reset functionality is also built-in to the default route\n    handlers. To enable this, set the configuration value\n    reset_password_handler to a true value (having already configured the\n    mail handler, as per the keyword documentation above). Once this is\n    done, the default login page will contain additional form controls to\n    allow the user to enter their username and request a reset password\n    link.\n\n    By default, the default handlers will generate a random 8 character\n    password using Session::Token. To use your own function, set\n    password_generator in your configuration. See the \"SAMPLE\n    CONFIGURATION\" for an example.\n\n    If using login_page_handler to replace the default login page, you can\n    still use the default password reset handlers. Add 2 controls to your\n    form for submitting a password reset request: a text input called\n    username_reset for the username, and submit_reset to submit the\n    request. Your login_page_handler is then passed the following\n    additional params:\n\n    new_password\n\n      Contains the new automatically-generated password, once the password\n      reset has been performed successfully.\n\n    reset_sent\n\n      Is true when a password reset has been emailed to the user.\n\n    password_code_valid\n\n      Is true when a valid password reset code has been submitted with a\n      GET request. In this case, the user should be given the chance to\n      confirm with a POST request, with a form control called\n      confirm_reset.\n\n      For a full example, see the default handler in this module's code.\n\n SAMPLE CONFIGURATION\n\n    In your application's configuation file:\n\n        session: simple\n        plugins:\n            Auth::Extensible:\n                # Set to 1 if you want to disable the use of roles (0 is default)\n                # If roles are disabled then any use of role-based route decorators\n                # will cause app to croak on load. Use of 'user_roles' and\n                # 'user_has_role' will croak at runtime.\n                disable_roles: 0\n                # Set to 1 to use the no-redirect login functionality\n                login_without_redirect: 0\n                # Set the view name for a custom login page, defaults to 'login'\n                login_template: login\n                # After /login: If no return_url is given: land here ('/' is default)\n                user_home_page: '/user'\n                # After /logout: If no return_url is given: land here (no default)\n                exit_page: '/'\n    \n                # Mailer options for reset password and welcome emails\n                mailer:\n                    module: Mail::Message # Email module to use\n                    options:              # Options for module\n                        via: sendmail     # Options passed to $msg-\u003esend\n                mail_from: '\"App name\" \u003cmyapp@example.com\u003e' # From email address\n    \n                # Set to true to enable password reset code in the default handlers\n                reset_password_handler: 1\n                password_generator: My::App::random_pw # Optional random password generator\n    \n                # Set to a true value to enable recording of successful last login times\n                record_lastlogin: 1\n    \n                # Password reset functionality\n                password_reset_send_email: My::App::reset_send # Customise sending sub\n                password_reset_text: My::App::reset_text # Customise reset text\n    \n                # create_user options\n                welcome_send: My::App::welcome_send # Customise welcome email sub\n                welcome_text: My::App::welcome_text # Customise welcome email text\n    \n                # List each authentication realm, with the provider to use and the\n                # provider-specific settings (see the documentation for the provider\n                # you wish to use)\n                realms:\n                    realm_one:\n                        priority: 3 # Defaults to 0. Realms are checked in descending order\n                        provider: Database\n                            db_connection_name: 'foo'\n                    realm_two:\n                        priority: 0 # Will be checked after realm_one\n                        provider: Config\n\n    Please note that you must have a session provider configured. The\n    authentication framework requires sessions in order to track\n    information about the currently logged in user. Please see\n    Dancer2::Core::Session for information on how to configure session\n    management within your application.\n\nMETHODS\n\n auth_provider($dsl, $realm)\n\n    Given a realm, returns a configured and ready to use instance of the\n    provider specified by that realm's config.\n\nHOOKS\n\n    This plugin provides the following hooks:\n\n before_authenticate_user\n\n    Called at the start of \"authenticate_user\".\n\n    Receives a hash reference of username, password and realm.\n\n after_authenticate_user\n\n    Called at the end of \"authenticate_user\".\n\n    Receives a hash reference of username, password, realm, errors and\n    success.\n\n    realm is the realm that the user authenticated against of undef if auth\n    failed.\n\n    The value of errors is an array reference of any errors thrown by\n    authentication providers (if any).\n\n    The value of success is either 1 or 0 to show whether or not\n    authentication was successful.\n\n before_create_user\n\n    Called at the start of \"create_user\".\n\n    Receives a hash reference of the arguments passed to \"create_user\".\n\n after_create_user\n\n    Called at the end of \"create_user\".\n\n    Receives the requested username, the created user (or undef) and an\n    array reference of any errors from the main method or from the\n    provider.\n\n login_required\n\n permission_denied\n\n after_login_success\n\n    Called after successful login just before redirect is called.\n\n before_logout\n\n    Called just before the session gets destroyed on logout.\n\nAUTHOR\n\n    David Precious, \u003cdavidp at preshweb.co.uk\u003e\n\n    Dancer2 port of Dancer::Plugin::Auth::Extensible by:\n\n    Stefan Hornburg (Racke), \u003cracke at linuxia.de\u003e\n\n    Conversion to Dancer2's new plugin system plus much cleanup \u0026 reorg:\n\n    Peter Mottram (SysPete), \u003cpeter at sysnix.com\u003e\n\nBUGS / FEATURE REQUESTS\n\n    This is an early version; there may still be bugs present or features\n    missing.\n\n    This is developed on GitHub - please feel free to raise issues or pull\n    requests against the repo at:\n    https://github.com/PerlDancer/Dancer2-Plugin-Auth-Extensible\n\nACKNOWLEDGEMENTS\n\n    Valuable feedback on the early design of this module came from many\n    people, including Matt S Trout (mst), David Golden (xdg), Damien\n    Krotkine (dams), Daniel Perrett, and others.\n\n    Configurable login/logout URLs added by Rene (hertell)\n\n    Regex support for require_role by chenryn\n\n    Support for user_roles looking in other realms by Colin Ewen (casao)\n\n    LDAP provider added by Mark Meyer (ofosos)\n\n    Documentation fix by Vince Willems.\n\n    Henk van Oers (GH #8, #13, #55).\n\n    Andrew Beverly (GH #6, #7, #10, #17, #22, #24, #25, #26, #54). This\n    includes support for creating and editing users and manage user\n    passwords.\n\n    Gabor Szabo (GH #11, #16, #18).\n\n    Evan Brown (GH #20, #32).\n\n    Jason Lewis (Unix provider problem, GH#62).\n\n    Matt S. Trout (mst) for Zero redirect login the easy and friendly way\n    \u003chttp://shadow.cat/blog/matt-s-trout/humane-login-screens/\u003e.\n\n    Ben Kaufman \"whosgonna\" (GH#79)\n\n    Dominic Sonntag (GH#70)\n\nLICENSE AND COPYRIGHT\n\n    Copyright 2012-16 David Precious.\n\n    This program is free software; you can redistribute it and/or modify it\n    under the terms of either: the GNU General Public License as published\n    by the Free Software Foundation; or the Artistic License.\n\n    See http://dev.perl.org/licenses/ for more information.\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fperldancer%2Fdancer2-plugin-auth-extensible","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fperldancer%2Fdancer2-plugin-auth-extensible","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fperldancer%2Fdancer2-plugin-auth-extensible/lists"}