.. asset:: debian:apt-authentication

Category: ``debian:apt-authentication``
=======================================

This asset stores authentication data that can be used by tasks that need to
authenticate to an external APT repository, such as :task:`APTMirror`.

* Data:

  * ``auth_scheme`` (string): the authentication scheme; at present this may
    only be ``basic``, but this field exists in case APT adds other
    authentication schemes in future
  * ``name`` (string): the name of these credentials, used to identify the
    asset in tasks
  * ``credentials`` (dictionary): secret scheme-dependent credentials

For ``auth_scheme: basic``, the ``credentials`` field is as follows:

  * ``username`` (string)
  * ``password`` (string)

This asset must be in a workspace, and only a single asset with a given name
can exist in a given workspace.  In task data, the asset may be identified
either as ``name`` (in which case it is looked up in the same workspace as
the task) or as ``workspace:name`` (in which case it is looked up in the
named workspace in the same scope as the task).

This asset may be used by the owner of that workspace, or by members of
groups to which the ``APT_AUTHENTICATOR`` role has been granted via an
``AssetUsage`` row.

To ensure that credentials are not exposed in logs, tasks must take care to
provide them to APT using the `apt_auth.conf(5)
<https://manpages.debian.org/trixie/apt/apt_auth.conf.5.en.html>`__
mechanism.

Since Basic authentication is sent in cleartext (see `RFC 7617
<https://www.rfc-editor.org/rfc/rfc7617.html>`__), APT will only use it with
repositories accessed over HTTPS (unless an explicit protocol is specified
in ``/etc/apt/auth.conf.d/``, which tasks should not do).  Tasks may add
their own checks for this in order to provide better error handling.