dump-things-service/docs/authentication.rst

Authentication & Authorization
================================

The service uses *authentication sources* to authenticate and authorize clients.
Each collection can have its own list of authentication sources.

Authentication Sources
-----------------------

Authentication sources are tried in the order they are listed for a collection.
If an authentication source authenticates the token successfully, no further
sources are queried. If no source is defined for a collection, the
``config``-source is used, i.e., tokens are read directly from the configuration.

If the same authentication source is listed more than once, the duplicate entries
are ignored and a warning ``Ignoring duplicate authentication provider...`` is
logged.

Available Sources
^^^^^^^^^^^^^^^^^

The following authentication source types are available:

``config``
   Reads token information directly from the persisted configuration.
   This is the default source.

``forgejo``
   Uses a `Forgejo <https://forgejo.org/>`_ instance to authenticate tokens
   and to determine the user ID and the incoming label.


Configuring Authentication Sources
------------------------------------

Authentication sources are configured per collection via the ``auth_sources``
key:

.. code-block:: yaml

   collections:
     my_collection:
       default_token: anon_read
       curated: my_collection/curated
       auth_sources:
         - type: forgejo
           url: https://forgejo.example.com/api/v1
           organization: data_handling
           team: data_entry_personal
           label_type: team
           repository: reference-repository   # optional
         - type: config


Config-based Authentication
^^^^^^^^^^^^^^^^^^^^^^^^^^^^

No extra keys are required beyond ``type: config``.

.. code-block:: yaml

   auth_sources:
     - type: config


Forgejo-based Authentication
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

The Forgejo source uses the Forgejo REST API to validate tokens and determine
permissions. This allows clients to use Forgejo personal access tokens to
authenticate with the service.

This is an example configuration for a Forgejo source:

.. code-block:: yaml

   collections:
     my_collection:
       auth_sources:
         - type: forgejo
           url: https://forgejo.example.com/api/v1
           organization: data_handling
           team: data_entry_personal
           label_type: team
           repository: reference-repository   # optional
           instance_id: example_com

The keys are:

``type``
   Must be ``forgejo``.

``url``
   The API URL of the Forgejo instance, e.g. ``https://forge.example.com/api/v1``.

``organization``
   The name of the Forgejo organization that is used to determine the permissions of the token.

``team``
   The name of the team inside the organization that is used to determine the permissions of the token.

``label_type``
   Either ``team`` or ``user``. Determines the incoming label format.

   If `label_type` is set to `team`, the incoming label is `forgejo-team-<organization-name>-<team-name>`.

   If `label_type` is set to `user`, the incoming label is `forgejo-user-<user-login>`


``repository`` (optional)
   If set, the token is only authorized if the team has access to this
   repository.

``instance_id`` (optional)
   Optional identifier to disambiguate users on different Forgejo instances.
   Defaults to a hash of ``url``.


When a Forgejo source authenticates a token, the user ID is set to the email of the Forgejo user.

The permissions will be fetched from the units `repo.code` and `repo.actions` of the team definition.
The following mapping is used:

============ ============ ============= ============== ============= ============
`repo.code`: curated_read incoming_read incoming_write curated_write zones_access
============ ============ ============= ============== ============= ============
`none`       `False`      `False`       `False`        `False`       `False`
`read`       `True`       `True`        `False`        `False`       `False`
`write`      `True`       `True`        `True`         `False`       `False`
============ ============ ============= ============== ============= ============


=============== ============ ============= ============== ============= ============
`repo.actions`: curated_read incoming_read incoming_write curated_write zones_access
=============== ============ ============= ============== ============= ============
`none`          `False`      `False`       `False`        `False`       `False`
`read`          `False`      `False`       `False`        `False`       `False`
`write`         `True`       `True`        `True`         `True`        `True`
=============== ============ ============= ============== ============= ============



A Forgejo authentication source can authenticate Forgejo-tokens that have at
least the following `Read`-permissions:

- **User**: this is required to determine user-related information, i.e. user-email and user login name.
- **Organization**: this is required to determine the membership of a user to a team in an organization.
- **Repository** (Only if `repository` is set in the configuration): required to determine a team's access to the repository.


Incoming Label Generation
''''''''''''''''''''''''''

The ``label_type`` key controls how the incoming label is derived:

- ``team`` → ``forgejo-<instance_id or URL-hash>-team-<organization>-<team>``
- ``user`` → ``forgejo-<instance_id or URL-hash>-user-<user-login>``




Administrator Tokens
---------------------

Administrator tokens are always authenticated using the persisted configuration.