==============
Authentication
==============

At the moment, the expected user login process is as follows:


First Launch
------------

When you first visit the app, it will not have any user accounts so
you will be shown a form to create one.

The username should ideally match your main (daily driver) username
within farmOS.  The password you give can be anything though, does not
need to (and perhaps should not) match farmOS.

This account will belong to the Administrator role within WuttaFarm,
which means it can "become root" (same concept as ``sudo`` basically).

Once the account is created you will be shown the normal login page.
Go ahead and login with this account using the username and password
you gave it.  But then you should logout again, for the next step.


OAuth2
------

The assumption (for now) is that users will login via farmOS / OAuth2
for normal operations.  Doing so will embed the access token within
the WuttaFarm app user session, which means the user can actually
browse farmOS data within the WuttaFarm views.

.. note::

   If you login to WuttaFarm directly with username/password, then
   your user session will not have a farmOS access token and so the
   farmOS data views in WuttaFarm will not work.

On the login page, click the "Login via farmOS / OAuth2" button.  This
will initiate the OAuth2 workflow, at which point you may be asked to
login to farmOS (if you're not already) and if you wish to grant
access to the 3rd party app (WuttaFarm; if you didn't already).

If all goes well you should be back in WuttaFarm, logged in as the
same username you have in farmOS.

Note that your first admin user in WuttaFarm ideally *should* have the
same username as farmOS, but regardless when you login via OAuth2, a
user account will be automatically created if necessary in WuttaFarm,
with that same username.