clean install

web/profiles/farm/docs/development/module/oauth.md

@@ -0,0 +1,136 @@
+# OAuth
+
+The [Simple OAuth](https://www.drupal.org/project/simple_oauth) module is used
+to provide an [OAuth2 standard](https://oauth.net/2/) authorization server.
+
+For documentation on using and authenticating with the farmOS API see [API](/api).
+
+## Providing OAuth Scopes
+
+OAuth Scopes define different levels of access. The farmOS server
+implements scopes that represent individual roles or permissions. Users will
+authorize clients with one or more scopes that determine how much access they
+have to data on the server.
+
+OAuth scopes are provided to the server using scope provider plugins. Each
+scope provider determines how scopes are implemented and created. The OAuth
+server must choose a single scope provider to provide all the scopes
+necessary for the server's authorization needs. All scopes use the same
+configuration and provide the same features regardless of the scope provider.
+
+The [Simple OAuth](https://www.drupal.org/project/simple_oauth) module
+provides two scope providers: `static` and `dynamic`. The `static` scope
+provider implements scopes as a `yaml` plugin that must be provided by modules
+and prevents scopes from being modified. The `dynamic` scope provider
+implements scopes as a config entity and allows scopes to be created and
+modified via the UI. Modules can provide `dynamic` scopes as well but there are
+no guarantees that these scopes will remain unmodified.
+
+farmOS defaults to using the `static` scope provider. This allows modules
+providing OAuth scopes to guarantee that their scopes exist unmodified within
+the server. The farmOS administrator can change to using the `dynamic` scope
+provider if necessary, but may need to re-create any `static` scopes that
+are needed for integrations provided by other modules.
+
+The farmOS Default Roles module provides a `static` OAuth scope for each of the
+default roles: `farm_manager`, `farm_worker`, and `farm_viewer`.
+
+### Scope Configuration
+
+All scopes use the same configuration and provide the same features
+regardless of the scope provider:
+- Scopes must provide a `name` to uniquely identify the scope
+- Scopes must provide a `description`
+- Scopes must specify if they are an `umbrella` scope. Umbrella scopes are
+  only used as parent for child scopes to reference and do not specify a
+  `granularity`.
+- Scopes must configure which `grant_types` they allow. Each grant type can
+  include an optional `description` to describe how the scope is used in the
+  context of each grant type.
+- Scopes can optionally specify a `parent` scope that the scope is a part of.
+  When the parent scope is requested, all of its child scopes are granted as
+  well.
+- Scopes must specify a `granularity` if they are not an `umbrella` scope.
+  This value must be equal to `permission` or `role`. The scope must
+  provide a single value for the `permission` or `role` it is associated with.
+
+This configuration is most easily demonstrated with
+`static` scopes that are provided in a `module.oauth2_scopes.yml` plugin file.
+
+```yaml
+"scope:name":
+  description: string (required)
+  umbrella: boolean (required)
+  grant_types: (required)
+    GRANT_TYPE_PLUGIN_ID: (required: only known grant types)
+      status: boolean (required)
+      description: string
+  parent: string
+  granularity: string (required: if umbrella is FALSE, values: permission or role)
+  permission: string (required: if umbrella is FALSE and granularity set to permission)
+  role: string (required: if umbrella is FALSE and granularity set to role)
+```
+
+An example of the static `farm_manager` scope provided by the farmOS Role
+Roles mdoule:
+```yaml
+farm_manager:
+  description: 'Grants access to the Farm Manager role.'
+  umbrella: false
+  grant_types:
+    authorization_code:
+      status: true
+    refresh_token:
+      status: true
+    password:
+      status: true
+  granularity: 'role'
+  role: 'farm_manager'
+```
+
+## Providing OAuth Clients
+
+OAuth clients are modeled as "Consumer" entities (provided by the
+[Consumers](https://www.drupal.org/project/consumers) module. To create
+integrations with farmOS a `consumer` entity must be created that
+identifies the integration and configures the OAuth Client for the desired
+authorization behavior.
+
+The core `farm_api_default_consumer` module provides a default client with
+`client_id = farm` that can use the `password` and `refresh_token` grant. You
+can use this client for general usage of the API, like writing a script that
+communicates with *your* farmOS server, but it comes with limitations.
+
+## Client Configuration
+
+Standard Consumer configuration:
+
+- `consumer.label` - A label used to identify the third party integration.
+- `consumer.client_id` - An optional `client_id` machine name to identify the
+  consumer. The `simple_oauth` module uses a UUID by default, but a machine
+  name makes it easier to identify clients across multiple farmOS servers.
+- `consumer.secret` - A `client_secret` used to secure the OAuth client.
+- `consumer.confidential` - A boolean indicating whether the client secret
+  needs to be validated.
+    - Most farmOS third party integrations will disable this. Otherwise the
+      same `client_secret` must be configured on all farmOS servers, or the
+      third party must keep track of a different secret for each server. This
+      challenge is due to the nature of farmOS being a self-hosted application.
+- `consumer.user_id` - When no specific user is authenticated Drupal will use
+  this user as the author of all the actions made by this consumer.
+    - This is only the case during the `Client Credentials` authorization flow.
+- `consumer.grant_types` - A list of the grant types that the client allows.
+- `consumer.scopes` - A list of default scopes that will be granted for this
+  client if no scopes are requested during the authorization flow. No scopes
+  will be granted that the user does not have access to.
+- `consumer.access_token_expiration` - The lifetime of access tokens in seconds.
+- `consumer.refresh_token_expiration` - The lifetime of refresh tokens in
+  seconds.
+- `consumer.redirect_uri` - The URI this client will redirect to when needed.
+    - This is used with the Authorization Code authorization flow.
+- `consumer.allowed_origins` - Define any allowed origins the farmOS server
+  should allow CORS requests from. This is required for any API integrations
+  that will run in the browser.
+- `consumer.third_party` - Enable if the Consumer represents a third party.
+    - Users will skip the "grant" step of the authorization flow for first
+      party consumers only.