Doorman is a collection of PSGI middlewares that are designed to perform authentication jobs. It stores authentication info in the session or env, you just configure it properly.
builder { enable "DoormanOpenID"; enable "DoormanTwitter"; enable "DoormanAuthentication", authenticator => \&auth; sub { my $env = shift; my $doorman = Doorman->new($env); # "user" and "admin" are scope names # current_<scope> are dynamic methods. # return undef value when the scope is not authenticated. my $user = $doorman->current_user; my $admin = $doorman->current_admin; $doorman->is_user_sign_in; } }
Doorman put a lot of objects to $env in the request life cycle. They are named like this:
$env
- doorman.${scope} - doorman.${scope}.${middleware} - doorman.${scope}.${middleware}.${name}
${scope} is, by default, "users" if not specified. Mulptile scopes can exist in the same time. For example, "users" and "admin" scopes will take $env-{"doorman.users"}> and $env-{"doorman.admin"}>, respectively. They are objects of Doorman::Scope class. These Doorman::Scope objects are responsible to provide URI paths that are responsive by middleware objects.
${scope}
"users"
"admin"
$env-
Doorman::Scope
Scope objects have 3 methods:
sign_up_path sign_in_path sign_out_path
These paths are named after the scope name. The scope name "users" will provide these paths
/users/sign_up /users/sign_in /users/sign_out
And for the scope "admins", they will be
/admins/sign_up /admins/sign_in /admins/sign_out
Your PSGI app can enable multiple doorman authentication middlewares to allow your app visitor to sign in with one of them.
enable "DoormanAuthentication", authenticator => \&my_authenticator; enable "DoormanOpenID";
When it is about to authenticae the session, Doorman middlewares are all implemented following these policies:
1. If all the required parameters are missing, skip. 2. Otherwise, perform the real authentication event though it is likely to fail 3. If it does fail, store the error status and message in C<$env>
The authentication chain is iterated in the same order you specify in the code.
Depending on your sign-in form design, you may choose to have multiple forms for each authentication method, or you may design to have one big form with all credential fields, say, username, password, and openid. Visitors either fill openid, or username and password, or maybe all of them.
If so, it is recommended that you put DoormanOpenID at the end, for the response of POSTing a openid URL, is to perform a redirect to openid server. The original username and password will be missing by the time it is redirected back from the openid server.
DoormanOpenID
For example code that facilitate chaining, see examples/openid-with-local.psgi in the distribution tarball.
examples/openid-with-local.psgi
To install Doorman, copy and paste the appropriate command in to your terminal.
cpanm
cpanm Doorman
CPAN shell
perl -MCPAN -e shell install Doorman
For more information on module installation, please visit the detailed CPAN module installation guide.