WWW::Suffit::Plugin::SuffitAuth - The Suffit plugin for Suffit API authentication and authorization providing
sub startup { my $self = shift->SUPER::startup(); $self->plugin('SuffitAuth', { configsection => 'suffitauth', expiration => SESSION_EXPIRATION, public_key_file => 'suffitauth_pub.key', userfile_format => 'user-%s.json', }); # . . . }
... configuration:
# SuffitAuth Client configuration <SuffitAuth> ServerURL https://api.example.com/api Insecure on AuthScheme Bearer Token "eyJhb...1Okw" ConnectTimeout 60 RequestTimeout 60 </SuffitAuth>
The Suffit plugin for Suffit API authentication and authorization providing
This plugin supports the following options
cache_expiration => 300
This option sets default cache expiration time for keep user data in cache
Default: 300 (5 min)
configsection => 'suffitauth'
This option sets a section name of the config file for define namespace of configuration directives for this plugin
Default: 'suffitauth'
expiration => SESSION_EXPIRATION
This option performs set a default expiration time of session
Default: 3600 secs (1 hour)
See "SESSION_EXPIRATION" in WWW::Suffit::Const
public_key_file => 'auth_public.key'
This option sets default public key file location (relative to datadir)
Default: 'auth_public.key'
userfile_format => 'u.%s.json'
This option sets default format of userdata authorization filename
Default: 'u.%s.json'
This plugin provides the following helpers
my $auth = $self->suffitauth->authenticate({ base_url => $self->base_url, referer => $self->req->headers->header("Referer"), username => $username, password => $password, loginpage => 'login', # -- To login-page!! expiration => $remember ? SESSION_EXPIRE_MAX : SESSION_EXPIRATION, realm => "Test zone", options => {}, }); if (my $err = $auth->get('/error')) { if (my $location = $auth->get('/location')) { # Redirect $self->flash(message => $err); $self->redirect_to($location); # 'login' -- To login-page!! } elsif ($auth->get('/status') >= 500) { # Fatal server errors $self->reply->error($auth->get('/status'), $auth->get('/code'), $err); } else { # User errors (show on login page) $self->stash(error => $err); return $self->render; } return; }
This helper performs authentication backend subprocess and returns result object (Mojo::JSON::Pointer) that contains data structure:
{ error => '', # Error message status => 200, # HTTP status code code => 'E0000', # The Suffit error code username => $username, # User name referer => $referer, # Referer loginpage => $loginpage, # Login page for redirects (location) location => undef, # Location URL for redirects }
my $auth = $self->suffitauth->authorize({ referer => $referer, username => $username, loginpage => 'login', # -- To login-page!! options => {}, }); if (my $err = $auth->get('/error')) { if (my $location = $auth->get('/location')) { $self->flash(message => $err); $self->redirect_to($location); # 'login' -- To login-page!! } else { $self->reply->error($auth->get('/status'), $auth->get('/code'), $err); } return; }
This helper performs authorization backend subprocess and returns result object (Mojo::JSON::Pointer) that contains data structure:
{ error => '', # Error message status => 200, # HTTP status code code => 'E0000', # The Suffit error code username => $username, # User name referer => $referer, # Referer loginpage => $loginpage, # Login page for redirects (location) location => undef, # Location URL for redirects user => { # User data address => "127.0.0.1", # User (client) IP address base => "http://localhost:8080", # Base URL of request comment => "No comments", # Comment email => 'test@example.com', # Email address email_md5 => "a84450...366", # MD5 hash of email address method => "ANY", # Current method of request name => "Bob Smith", # Full user name path => "/", # Current query-path of request role => "Regular user", # User role status => true, # User status in JSON::PP::Boolean notation uid => 1, # User ID username => $username, # User name }, }
The 'user' is structure that describes found user. For eg.:
{ "address": "127.0.0.1", "base": "http://localhost:8473", "code": "E0000", "email": "foo@example.com", "email_md5": "b48def645758b95537d4424c84d1a9ff", "expires": 1700490101, "groups": [ "wheel" ], "method": "ANY", "name": "Anon Anonymous", "path": "/", "role": "System Administratot", "status": true, "uid": 1, "username": "admin" }
my $client = $self->suffitauth->client;
Returns authorization client
See WWW::Suffit::Client::V1
my $init = $self->suffitauth->init;
This method returns the init object (Mojo::JSON::Pointer) that contains data of initialization:
{ error => '...', # Error message status => 500, # HTTP status code code => 'E7000', # The Suffit error code }
For example (in your controller):
# Check init status my $init = $self->suffitauth->init; if (my $err = $init->get('/error')) { $self->reply->error($init->get('/status'), $init->get('/code'), $err); return; }
my $options = $self->suffitauth->options;
Returns authorization plugin options as hashref
my $auth = $self->suffitauth->unauthorize(username => $username); if (my $err = $auth->get('/error')) { $self->reply->error($authdata->get('/status'), $authdata->get('/code'), $err); }
This helper performs unauthorize process - remove userdata file from disk and returns result object (Mojo::JSON::Pointer) that contains data structure:
{ error => '', # Error message status => 200, # HTTP status code code => 'E0000', # The Suffit error code username => $username, # User name }
Internal methods
This method register the plugin and helpers in Mojolicious application
E01xx, E02xx, E03xx, E04xx and E05xx are reserved as HTTP errors
E0000 Ok E0100 Continue E0200 OK E0300 Multiple Choices E0400 Bad Request E0500 Internal Server Error
See WWW::Suffit::API
Auth: E70xx
E7000 [403] Access denied E7001 [400] Incorrect username E7002 [503] Can't connect to authorization server E7003 [500] Can't get public key from authorization server E7004 [500] Can't save public key file %s E7005 [*] Authentication error E7006 [*] Authorization error E7007 [500] Can't save file <USERNAME>.json E7008 [500] File <USERNAME>.json not found or incorrect E7009 [400] Incorrect username (while authorize) E7010 [400] Incorrect username (while unauthorize)
* -- this code defines on server side
Mojolicious, WWW::Suffit::Client::V1, WWW::Suffit::Server
Serż Minus (Sergey Lepenkov) https://www.serzik.com <abalama@cpan.org>
Copyright (C) 1998-2024 D&D Corporation. All Rights Reserved
This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.
See LICENSE file and https://dev.perl.org/licenses/
LICENSE
To install WWW::Suffit::Plugin::SuffitAuth, copy and paste the appropriate command in to your terminal.
cpanm
cpanm WWW::Suffit::Plugin::SuffitAuth
CPAN shell
perl -MCPAN -e shell install WWW::Suffit::Plugin::SuffitAuth
For more information on module installation, please visit the detailed CPAN module installation guide.