API & Docs - init OAuth 2.0 documentation

docsrc/source/api/index.rst

@@ -7,6 +7,7 @@ API documentation
 
    auth
    configuration
+   oauth2
    records
    sports
    stats

docsrc/source/api/oauth2.rst

@@ -0,0 +1,14 @@
+OAuth2
+######
+
+.. autoflask:: fittrackee:create_app()
+   :endpoints:
+    oauth2.get_clients,
+    oauth2.create_client,
+    oauth2.get_client_by_client_id,
+    oauth2.get_client_by_id,
+    oauth2.delete_client,
+    oauth2.revoke_client_tokens,
+    oauth2.authorize,
+    oauth2.issue_token,
+    oauth2.revoke_token

docsrc/source/apps.rst

@@ -0,0 +1,42 @@
+Third-party applications
+########################
+(*new in 0.7.0*)
+
+FitTrackee provides a REST API (see `documentation <api/index.html>`__) whose
+most endpoints require authorization/authentication.
+
+To allow a third-party application to interact with API endpoints, an
+`OAuth2 <https://datatracker.ietf.org/doc/html/rfc6749>`_ client can be created
+in user settings ('apps' tab).
+
+.. note::
+  OAuth2 support is implemented with `Authlib <https://docs.authlib.org/en/latest/>`_ library.
+
+.. warning::
+  OAuth2 endpoints requiring authentication are not accessible by third-party
+  applications (`documentation <api/oauth2.html>`__), only by FitTrackee
+  client (first-party application).
+
+FitTrackee supports only `Authorization Code <https://datatracker.ietf.org/doc/html/rfc6749#section-1.3.1>`_
+flow (with PKCE support).
+It allows to exchange an authorization code for an access token.
+It is recommended to use `PKCE <https://datatracker.ietf.org/doc/html/rfc7636>`_
+to provide a better security.
+
+The following scopes are available:
+
+- ``application:write``: grants write access to application configuration (only for users with administration rights),
+- ``profile:read``: grants read access to auth endpoints,
+- ``profile:write``: grants write access to auth endpoints,
+- ``users:read``: grants read access to users endpoints,
+- ``users:write``: grants write access to users endpoints,
+- ``workouts:read``: grants read access to workouts-related endpoints,
+- ``workouts:write``: grants write access to workouts-related endpoints.
+
+.. figure:: _images/fittrackee_screenshot-07.png
+   :alt: OAuth2 client creation on FitTrackee
+
+Some resources about OAuth 2.0:
+
+- `OAuth 2.0 Simplified <https://www.oauth.com>`_ by `Aaron Parecki <https://aaronparecki.com>`_
+- `Web App Example of OAuth 2 web application flow <https://requests-oauthlib.readthedocs.io/en/latest/examples/real_world_example.html>`_ with Requests-OAuthlib

docsrc/source/cli.rst

@@ -14,8 +14,9 @@ A command line interface (CLI) is available to manage database and users.
       --help  Show this message and exit.
 
     Commands:
-      db     Manage database.
-      users  Manage users.
+      db      Manage database.
+      oauth2  Manage OAuth2 tokens.
+      users   Manage users.
 
 .. warning::
     | The following commands are now deprecated and will be removed in a next version:
@@ -40,6 +41,26 @@ Apply migrations.
 Empty database and delete uploaded files, only on development environments.
 
 
+OAuth2
+~~~~~~
+
+``ftcli oauth2 clean``
+""""""""""""""""""""""
+.. versionadded:: 0.7.0
+
+Remove tokens expired for more than provided number of days
+
+.. cssclass:: table-bordered
+.. list-table::
+   :widths: 25 50
+   :header-rows: 1
+
+   * - Options
+     - Description
+   * - ``--days``
+     - Number of days.
+
+
 
 Users
 ~~~~~

docsrc/source/features.rst

@@ -81,6 +81,8 @@ Account & preferences
   | A disabled sport (by admin or user) will not appear in dropdown when **adding a workout**.
   | A workout with a disabled sport will still be displayed in the application.
 
+- A user can create `clients <apps.html>`__ for third-party applications (*new in 0.7.0*).
+
 
 Administration
 ^^^^^^^^^^^^^^

docsrc/source/index.rst

@@ -33,6 +33,7 @@ Table of contents
    :maxdepth: 1
 
    features
+   apps
    installation
    cli
    api/index

docsrc/source/installation.rst

@@ -9,6 +9,7 @@ This application is written in Python (API) and Typescript (client):
     - `staticmap <https://github.com/komoot/staticmap>`_ to generate a static map image from gpx coordinates
     - `python-forecast.io <https://github.com/ZeevG/python-forecast.io>`_ to fetch weather data from `Dark Sky <https://darksky.net>`__ (former forecast.io)
     - `dramatiq <https://flask-dramatiq.readthedocs.io/en/latest/>`_ for task queue
+    - `Authlib <https://docs.authlib.org/en/latest/>`_ for OAuth 2.0 Authorization support
 - Client:
     - Vue3/Vuex
     - `Leaflet <https://leafletjs.com/>`__ to display map