.. include:: /includes.rst.txt

.. comments - headings

   # with overline, for parts
   * with overline, for chapters
   = for sections
   - for subsections
   ^ for subsubsections
   " for paragraphs
   * for H5
   + for H6

.. _users_yaml:

The ``users.yaml`` file
-----------------------

``users.yaml`` is a configuration file where user accounts (or service accounts)
and their roles are defined for the following authentication methods:

* :ref:`form_authentication`
* :ref:`basic_authentication`
* :ref:`cookie_authentication`

.. note::
   The file plays the same role as ``tomcat-users.xml`` in older versions
   of EDG (see :ref:`tomcat_authentication`).


File location
^^^^^^^^^^^^^

By default, the system will look for a file ``users.yaml`` in the same
directory as the :ref:`setup file <setup_file>` (``edg-setup.properties``).

Name and location can be overridden in the setup file::

   usersFile = ./my-user-file.yaml


Example
^^^^^^^

The following example can be used as a template:

.. code-block:: yaml

   # users.yaml template
   "Admin_user":
     password: "password32"
     roles: [ "admin", "manager" ]
   "Editor_user":
     password: "password54"
     roles: [ "editor" ]
   "Guest":
     encPassword: "{bcrypt}$2y$15$krgnAQqdWl8wqJ1nwE86ZejFDTVHJI2KDUd5RFsYrNTuGxR6Nrx7q"
     roles: [ "viewer" ]


Syntax
^^^^^^

The file uses YAML syntax.

Each user account is a text block of this form:

.. code-block:: yaml

   "loginName1":
      password: "password1"
      encPassword: "{bcrypt}$2y$15$7UPVu0GcvphJ5f.2mt/Sb.pBv8ucAHObnoMoBVBfH2gqQaAMmMqua"
      roles: [ "role1", "role2" ]


``loginName1``
   The account's login name goes here. The are no special restrictions on the
   characters used. For example, email addresses could be used as login names.

``password``
   The account's password, in clear text. This is not recommended for production systems. Use ``encPassword`` instead.

``encPassword``
   The account's password, hashed with bcrypt for improved security.
   Only one of ``password`` and ``encPassword`` may be present.
   The value must start with the string ``{bcrypt}``, followed by the hashed password.
   Use a bcrypt-capable utility to encode the password, for example on a Linux command
   line::

      % htpasswd -nbBC 15 USER topsecret
      USER:$2y$15$HHI02CXNcMF2gDG3GosJku4jmUhE9eM8GHkIB.mKSuYJMKIZ8RUf6
   
   and replace the initial ``USER:`` with ``{bcrypt}``.

``roles``
   A YAML list of the account's security roles. Any roles used here must match those defined
   in the setup file file under :ref:`securityRoles <setup_securityRoles>`, case-sensitive.