view release on metacpan or  search on metacpan

lib/App/Dochazka/CLI/Testers.pm  view on Meta::CPAN

    zypper install perl-App-Dochazka-REST 

=item PostgreSQL setup

Follow the instructions at
L<https://metacpan.org/pod/App::Dochazka::REST::Guide#PostgreSQL-setup>.

=item Site configuration

Follow the instructions at
L<https://metacpan.org/pod/App::Dochazka::REST::Guide#Site-configuration>.

=item Database initialization

This step is very simple. Just run the C<dochazka-dbinit> command:

    # dochazka-dbinit
    Dochazka database reset to pristine state

=item Start the server

To actually do anything, the server needs to be running:

    # dochazka-rest
    Starting Web::MREST ver. 0.283
    App distro is App-Dochazka-REST
    App module is App::Dochazka::REST::Dispatch
    Distro sharedir is /usr/lib/perl5/site_perl/5.20.1/auto/share/dist/App-Dochazka-REST
    Local site configuration directory is /etc/dochazka-rest
    Loading configuration parameters from /etc/dochazka-rest
    Setting up logging
    Logging to /home/smithfarm/mrest.log
    Calling App::Dochazka::REST::Dispatch::init()
    Starting server
    HTTP::Server::PSGI: Accepting connections at http://0:5000/

=item Web browser test

After completing the above, you should be able to access the REST server by
pointing your browser at L<http://localhost:5000>. At the login dialog,
enter username "demo" and password "demo".

=back


=head2 Prereq 3: Install Dochazka CLI client

Now that the server part is working, install the CLI:

    zypper install perl-App-Dochazka-CLI

You should now be able to start the CLI and login as "demo" with password
"demo":

    $ dochazka-cli -u demo -p demo
    Loading configuration files from
    /usr/lib/perl5/vendor_perl/5.18.2/auto/share/dist/App-Dochazka-CLI
    Cookie jar: /root/.cookies.txt
    URI base http://localhost:5000 set from site configuration
    Authenticating to server at http://localhost:5000 as user root
    Server is alive
    Dochazka(2016-01-12) demo PASSERBY>

Exit the CLI by issuing the C<exit> command:

    Dochazka(2016-01-12) demo PASSERBY> exit
    $

Congratulations! You have passed the first test.


=head1 SESSION 1: CREATE AN EMPLOYEE

Before you do anything, L<make sure the server is running|"Start the server">.


=head2 Try with insufficient privileges

To create an employee, you will need to be logged in as an administrator.
The "demo" employee is not an administrator, but let's try anyway. First,
log in according to L<"Verify success">, above. Then, issue the C<employee
list> command:

    Dochazka(2016-01-12) demo PASSERBY> employee list
    *** Anomaly detected ***
    Status:      403 Forbidden
    Explanation: ACL check failed for resource employee/list/?:priv (ERR)

This output indicates that the REST server returned a C<403 Forbidden> error,
which is to be expected because the C<demo> employee has insufficient
privileges.

Next, try to create an employee:

    Dochazka(2016-01-12) demo PASSERBY> PUT employee nick george { "fullname" : "King George III" }
    HTTP status: 403 Forbidden
    Non-suppressed headers: {
      'X-Web-Machine-Trace' => 'b13,b12,b11,b10,b9,b8,b7'
    }
    Response:
    {
       "payload" : {
          "http_code" : 403,
          "uri_path" : "employee/nick/george",
          "permanent" : true,
          "found_in" : {
             "file" : "/usr/lib/perl5/vendor_perl/5.22.0/App/Dochazka/REST/Auth.pm",
             "package" : "App::Dochazka::REST::Auth",
             "line" : 431
          },
          "resource_name" : "employee/nick/:nick",
          "http_method" : "PUT"
       },
       "text" : "ACL check failed for resource employee/nick/:nick",
       "level" : "ERR",
       "code" : "DISPATCH_ACL_CHECK_FAILED"
    }

Here, the error is the same C<403 Forbidden> but the output is more detailed.
This is because we used a special type of command that is ordinarily only
used to test the REST API.

=head2 Log in as root

For the rest of this session, we will be logged in as the C<root> employee, 
which has a special status in that it is created when the database is
initialized and it is difficult or impossible to delete. In a freshly
initialized database, the C<root> employee's password is "immutable".

The username and password need not be specified on the command line.
Try it this way:

    $ dochazka-cli
    Loading configuration files from /usr/lib/perl5/vendor_perl/5.18.2/auto/share/dist/App-Dochazka-CLI
    Cookie jar: /root/.cookies.txt
    URI base http://localhost:5000 set from site configuration
    Username: root
    Authenticating to server at http://localhost:5000 as user root
    Password: 
    Server is alive
    Dochazka(2016-01-12) root ADMIN>

=head2 List employees

A list of all employees in the database can be obtained using the C<employee
list> command, which is documented at L<App::Dochazka::CLI::Guide|"Get list of
employees">:

    Dochazka(2016-01-12) root ADMIN> employee list

    List of employees with priv level ->all<-
        demo
        root

Actually, there is no priv level "all" - this just means that all employees are
listed, regardless of their priv level.

You can also try listing employees by priv level as per the documentation.

=head2 Create an employee

At the moment there is no CLI command to create a new employee. Hence we use
the REST API testing command as described in
L<App::Dochazka::CLI::Guide|"Create a new employee">:

    Dochazka(2016-01-12) root ADMIN> PUT employee nick george { "fullname" : "King George III" }
    HTTP status: 200 OK
    Non-suppressed headers: {
      'X-Web-Machine-Trace' => 'b13,b12,b11,b10,b9,b8,b7,b6,b5,b4,b3,c3,c4,d4,e5,f6,g7,g8,h10,i12,l13,m16,n16,o16,o14,p11,o20,o18,o18b'
    }
    Response:
    {
       "code" : "DOCHAZKA_CUD_OK",
       "count" : 1,
       "payload" : {
          "email" : null,
          "remark" : null,
          "eid" : 3,
          "passhash" : null,
          "supervisor" : null,
          "sec_id" : null,
          "salt" : null,
          "nick" : "george",
          "fullname" : "King George III"
       },
       "text" : "DOCHAZKA_CUD_OK",
       "DBI_return_value" : 1,
       "level" : "OK"
    }

=head2 Employee profile

The properties, or attributes, of the C<employee> class can be seen in the
output of the previous command (under "payload"). A more comfortable way to
display the properties of any employee is the C<employee profile> command:

    Dochazka(2016-01-12) root ADMIN> employee profile

    Full name:    Root Immutable
    Nick:         root

lib/App/Dochazka/CLI/Testers.pm  view on Meta::CPAN

    Full name:    King George III
    Nick:         george
    Email:        (not set)
    Secondary ID: (not set)
    Dochazka EID: 5
    Reports to:   (not set)

This only tells us the state of the employee object. Most objects in the
Dochazka database are associated with an employee via the Dochazka EID
value (5 in this example). We can get the same information by typing:

    Dochazka(2016-01-27) root ADMIN> eid=5 profile

    Full name:    King George III
    Nick:         george
    Email:        (not set)
    Secondary ID: (not set)
    Dochazka EID: 5
    Reports to:   (not set)


=head2 Log in as george

Now, exit the CLI and run it again as C<george>, our new employee.

    $ dochazka-cli 
    ...
    Username: george
    Authenticating to server at http://localhost:5000 as user george
    Password: 
    MREST_CLI_UNAUTHORIZED (ERR) MREST_CLI_UNAUTHORIZED
    Response: '401 Unauthorized'

This happens because there is no password set for C<george>.


=head2 Assign george a password

Fortunately, Dochazka admins can assign any password to any user. This
capability may or may not be useful, depending on whether LDAP
authentication is active at the site. In our current testing scenario, LDAP
authentication is disabled, so the password is taken from the Dochazka
database. So, let's give george a password:

    $ dochazka-cli -u root -p immutable
    ...
    Dochazka(2016-01-27) root ADMIN> emp=george password
    It is important that the new password really be what you intended.
    Therefore, we are going to ask you to enter the desired password
    twice, so you have a chance to double-check. 

    New password      : <type george>
    New password again: <type george again>
    Password changed

Now you can log in with credentials C<george/george>:

    $ dochazka-cli -u george -p george
    ...
    Authenticating to server at http://localhost:5000 as user george
    Server is alive
    Dochazka(2016-01-27) george PASSERBY>




=head1 SESSION 3: EMPLOYEE PRIVILEGE HISTORY

Before you do anything, L<make sure the server is running|"Start the server">.


=head2 Verify state

If you are continuing from Session 2, you can skip this step.

If you are starting over (or from scratch), run the following script to
bring your database into the proper state:

    #!/bin/sh
    cat <<EOF | dochazka-cli -u root -p immutable
    PUT employee nick george { "fullname" : "King George III", "salt" : "a054d158a23c3a07ad0163107ad72a8649597d71", "passhash" : "5cf2c3a23de9db43d2d846172966150e9197717ecd0304bafef3f23fc159df942021dd3aec7b4dbcde87d8a44c1bd905bbba3862989065d012bb46a1...
    EOF


=head2 Log in as the test employee

This just demonstrates that the test employee can log in.

    $ dochazka-cli -u george -p george
    ...
    Authenticating to server at http://localhost:5000 as user george
    Server is alive
    Dochazka(2016-01-27) george PASSERBY>


=head2 Concepts (Dochazka prompt, employee priv levels)

Let's review the information presented in the prompt:

=over

=item Prompt date in parentheses (defaults to current date)

=item Logged-in employee (george)

=item Privilege level of logged-in employee (passerby)

=back

The privilege level deserves closer attention. Dochazka has four privilege
levels:

=over

=item passerby

=item inactive

=item active

=item admin

=back


=head2 George the passerby

The current privilege level is determined by consulting the employee's
privilege history, which is a database table containing records for each
change in the employee's status. Employee status changes, for example, when
the employee is hired, leaves the company, goes on parental leave, etc.

Now, our test employee "george" has a password and can log in. However, he
has no privilege history so his priv level defaults to "passerby" - the
lowest possible level.

In this section, we see that passers-by cannot do much at all in Dochazka:

    $ dochazka-cli -u george -p george
    Dochazka(2016-01-29) george PASSERBY> emp=root profile
    *** REST ERROR ***

    Error encountered on attempted operation "Employee lookup"
    REST operation: GET employee/nick/root/minimal
    HTTP status: 403 Forbidden
    Explanation: DISPATCH_KEEP_TO_YOURSELF: Detected attempt by
    insufficiently privileged user to meddle in another user's affairs
    Permanent? YES

    Dochazka(2016-01-29) george PASSERBY> interval
    *** REST ERROR ***