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 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:

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.

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:

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.