using-farmos-aggregator.md

Using farmOS Aggregator

• Dashboard
• Managing farmOS Aggregator Users
• Managing Farm Profiles
  • Add Farms
    • Registering Farm Profiles
    • Requesting Registration
  • Authorizing Farm Profiles
    • Requesting Authorization
    • Authorization Form

See configuration on how to configure farmOS Aggregator.

Dashboard

A dashboard with an overview of information is available at http://localhost/dashboard

Features:

• Displays simple stats showing the total number of farms, active farms, and authorized farms. Useful to quickly see if any farms have become unauthorized.

Managing farmOS Aggregator Users

Managing Farm Profiles

Features:

• Lists all farm profiles in a sortable table.
• Sorts by the farm active flag.
• Displays the authorization status of the farm.
  • Hover over the re-authorize button to see the error.
  • Click on the authorized button to see more info on the __ page.
• Displays tags that can be used to categorize farms.
• Displays last_accessed and created times.
• Button to edit the farm profile - see edit farms.
• Button to quickly refresh farm info. This is useful to diagnose connection problems.

Add Farms

Features:

• Add a farm profile to the aggregator. Note that you can only pre-populate values for the farm. After you add a farm via the admin UI, you will not be able to connect to the farm.
• After adding, the farm must be authorized by requesting authorization from the farmOS server admin.
• The active flag can be configured when adding a farm.

Registering Farm Profiles

The registration page allows farmOS admins to select for which of the configured OAuth scopes they would like to authorize the farmOS Aggregator to access their data.

Features:

• If OPEN_FARM_REGISTRATION is enabled then this page will be accessible to the public. The FARM_ACTIVE_AFTER_REGISTRATION setting allows you to configure if registered farms will be enabled by default. This can be useful to guard against malicious intent if many farm profiles are added.
• If INVITE_FARM_REGISTRATION is enabled then this page will be accessible to users that receive a link with an embedded api_token. See Requesting Registration
• The registration is a multi step process (step 2 is show above):
  1. User inputs farmOS Server Hostname.
  2. User selects which of the configured OAuth Scopes they want to authorize.
  3. The user is redirected to their farmOS server to complete the OAuth Authorization Flow.
  4. Basic farm values are pre-populated in the registration form. The user verifies their information.

Requesting Registration

Features:

• Aggregator admins can request registration by generating a special link users can use to join the aggregator.
  • An email can be supplied to automatically send an email requesting registration, OR
  • The link can be generated and copy/pasted to share with the user manually.

Authorizing Farm Profiles

Authorization is a crucial part of the farmOS Aggregator. Because farmOS server usernames and passwords are not saved in the database, access to farmOS servers must be authorized via the OAuth2 Authorization protocol. There are a few instances when authorization may be required of users:

• After manually adding a farm via the admin UI
• If communication with the farmOS server is ever broken for an extended amount of time, the existing authorization could expire. The server must then be re-authorized.
• If the Aggregator ever wants to request that users authorize with new or additional OAuth Scopes, then admins must request users to re-authorize with those additional scopes.

Requesting Authorization

Features:

• Aggregator admins can request authorization of a farmOS server by generating a special link users can use to authorize their farmOS server. This link is unique to each individual farm profile. It should only be shared with the owner of that farmOS server.
  • An email address can be supplied to automatically send an email to the farmOS admin. (This will default to the email saved in the farm profile, if applicable.)
  • The link can also be generated and copy/pasted to share with the user manually.

Authorization Form

This is the form that users are directed to by the generated authorization links.

• Authorization is a 3 step process:
  1. User selects which of the configured OAuth Scopes they want to authorize.
  2. The user is redirected to their farmOS server to complete the OAuth Authorization Flow.
  3. The user is redirected to the Aggregator showing that the authorization was successful.