docs: initial/basic project docs

docs/narr/auth.rst

@@ -0,0 +1,52 @@
+
+==============
+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.