``profile::aaa``
=====================

This module manages configuration related to authentication, authorization, and
auditing. In particular, it

- performs the Active Directory join (optional)
- configures login restrictions (e.g. :manpage:`pam_access(8)`)
- adds sudo rules for administrators


Parameters
----------

===============================  ========  ================================================
**Name**                         **Type**  **Default**
-------------------------------  --------  ------------------------------------------------
admins                           list      hiera_array('aaa::admins')
allow_sudoers_d                  bool      hiera('aaa::allow_sudoers_d')
bastions                         list      hiera('aaa::bastions')
cache_creds                      bool      hiera('aaa::cache_creds')
create_homes                     bool      hiera('aaa::create_homes')
enable_ad                        bool      hiera('aaa::enable_ad')
enable_eaccounts                 bool      hiera('aaa::enable_eaccounts')
enable_slurm                     bool      false
enable_ssh_allow                 bool      hiera('aaa::enable_ssh_allow')
enable_tier3_ldap                bool      hiera('aaa::enable_tier3_ldap', false)
ldap_enabled                     bool      hiera('aaa::ldap_enabled')
offline_creds_expiration         string    hiera('aaa::offline_creds_expiration')
override_homedir                 string    hiera('aaa::override_homedir', undef)
ssh_authorized_keys              hash      hiera_hash('aaa::sshkeys', {})
sssd_debuglevel                  int       hiera('aaa::sssd_debuglevel')
sudo_rules (Hiera only)          list      hiera_array('aaa::sudo_rules', [])
support_afs                      bool      hiera('aaa::support_afs'),
use_bastions                     bool      hiera('aaa::use_bastions', undef)
users                            list      hiera_array('aaa::users', [])
===============================  ========  ================================================


``admins``
~~~~~~~~~~

A list of user and/or group names. The users as well as the members of the groups
can log in on the system and have full root privileges via sudo.

Group names must be prefixed with ``%``.

Example::

  aaa::admins:
    - 'markushin'
    - 'gsell'
    - 'barabas'
    - '%unx-linux_support'

Also see `users`_.


``allow_sudoers_d``
~~~~~~~~~~~~~~~~~~~

This boolean controls whether the files in ``/etc/sudoers.d`` are taken
into account by sudo.


``bastions``
~~~~~~~~~~~~

A list of FQDNs. If `use_bastions`_ is true, then root logins are only allowed
from the hosts on this list. *Note*: If the list is empty, login is unrestricted
again!

Example::

  aaa::bastions:
    - 'gpfs-node1.psi.ch'
    - 'gpfs-node2.psi.ch'
    - 'gpfs-node3.psi.ch'
    - 'wmgt01.psi.ch'
    - 'wmgt02.psi.ch'

``create_homes``
~~~~~~~~~~~~~~~~

This boolean controls whether home directories are created on login when
necessary. This only works if the underlying filesystem allows it. In
particular, it does not work on AFS.

Also see `override_homedir`_.


``cache_creds``
~~~~~~~~~~~~~~~~~~~~~

This boolean controls whether sssd caches credentials.

Also see `offline_creds_expiration`_.


``enable_ad``
~~~~~~~~~~~~~

Determines whether the system will be configured for Active Directory
authentication.


``enable_eaccounts``
~~~~~~~~~~~~~~~~~~~~

Setting this to ``true`` enables the Active Directory OU containing the
e-accounts.


``enable_slurm``
~~~~~~~~~~~~~~~~
When set to ``true``, we allow slurm users to login on computing nodes in where
their jobs are running. Otherwise, users are not allowed to login in the computing
nodes.

To enable this behaviour, someone needs to call directly the ``profile::aaa`` class
and enable this feature, but also needs to change the call of the ``role::base`` 
class by setting ``include_aaa`` to ``false``. For example::

  class {
    'role::base':
        include_aaa => false;
    'profile::aaa':
      support_afs  => hiera('base::enable_afs'),
      enable_slurm => true;
    'slurm::compute':
        cluster => $cluster;
  }



``enable_ssh_allow``
~~~~~~~~~~~~~~~~~~~~

Allow users to manage access to the system bypassing Puppet by adding usernames
to ``/etc/security/ssh.allow.user``. This file is never touched by Puppet.
Documentation can be found in :manpage:`pam_listfile(8)` or
``/etc/security/ssh.allow.README`` on the target system.


``enable_tier3_ldap``
~~~~~~~~~~~~~~~~~~~~~
When set to ``true``, sssd.conf is configured to support only OpenLDAP for
the Tier3. Other domains (Active Directory D.PSI.CH and LDAP SLS.PSI.CH) are
not included in the configuration file.


``ldap_enabled``
~~~~~~~~~~~~~~~~

This boolean controls whether LDAP (AD) is used for user information and
authentication.

In this case the following port have to be accessible from the host to the
domain controllers:

 - 389/TCP
 - 389/UDP
 - 88/TCP
 - 88/UDP
 - 464/UDP



``offline_creds_expiration``
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

This integer controls for how many days cached credentials are valid after the
last successful online login. A value of 0 means that there is no limit.

Also see `cache_creds`_.


``override_homedir``
~~~~~~~~~~~~~~~~~~~~

This string defines the home directory path to use as expected by sssd's
``override_homedir`` option. See :manpage:`sssd.conf(5)` for details.

Example::

  aaa::override_homedir: '/home/%u'


``sshkeys``
~~~~~~~~~~~

A hash of hashes, each of which contains the parameters as accepted by the
`ssh_authorized_key
<https://docs.puppet.com/puppet/latest/types/ssh_authorized_key.html>`_ resource
type.

Example::

  aaa::sshkeys:
    'root@ra':
       user: 'root'
       type: 'ssh-dss'
       key: 'AAAAB3Nz...'

Keep in mind that this only works if the user's home directory is accessible to
root. In particular, it doesn't work if the home is on AFS.


``sssd_debuglevel``
~~~~~~~~~~~~~~~~~~~

This integer configures sssd's ``debug_level`` option (see
:manpage:`sssd.conf(5)`). It is rarely necessary to use this setting, as the
debug level can be changed at runtime using :manpage:`sss_debuglevel(8)`.


``sudo_rules``
~~~~~~~~~~~~~~

A list of strings taken from Hiera containing additional sudo rules.


``support_afs``
~~~~~~~~~~~~~~~

Configure PAM and related tools which are necessary for running AFS.


``use_bastions``
~~~~~~~~~~~~~~~~

This parameter determines whether root logins are only possible from the hosts
listed in `bastions`_. Normally the value is taken from the network property of
the same name, but this parameter allows overriding the network setting through
Hiera or in Puppet manifests.


``users``
~~~~~~~~~

A list of user and/or group names. The users as well as the members of the
groups can log in on the system.

Group names must be prefixed with ``%``.

Also see `admins`_.


``ssh_authorized_key``
~~~~~~~~~~~~~~~~~~~~~~

A hash containing SSH public keys as expected by the ``ssh_authorized_key``
Puppet resource.


Examples
--------

The base role includes this profile by default. If you need to customize the
profile, do it like this::

  class role::some_role () {
    class {'role::base':
      include_aaa => false,
      ...
    }

    class {'profile::aaa':
      override_homedir => '/localhomes/%u',
      create_homes     => true,
      ...
    }
    ...


Implementation Notes
--------------------


User/Group Enumeration
~~~~~~~~~~~~~~~~~~~~~~

User/group enumeration happens when using the ``{set,get,end}pwent`` and
``{set,get,ent}grent`` APIs to enumerate all users or groups. These are used by
``getent passwd`` and ``gentent group`` for example, when not providing a
specific user or group to query.

Enumeration would potentially be very slow and put a high load on the AD domain
controllers if it were to return all users/groups from AD. To prevent this, we
disable enumeration for AD accounts using the ``enumerate`` setting in
:manpage:`sssd.conf(5)`. This means that enumeration using the APIs/programs
above only returns local users and groups.


The ``min_id`` issue
~~~~~~~~~~~~~~~~~~~~

There are Unix groups in AD at PSI with very low GIDs, the lowest being 101
(``unx-fkt``). This leads to problems, because :manpage:`sssd(8)` ignores users
and groups with GIDs lower than ``min_id`` (from :manpage:`sssd.conf(5)`), which
has a value of 500 by default.

Therefore we set ``min_id`` to 100. One consequence is that there is overlap
between the IDs considered by sssd when querying AD, and the ID range for system
users and groups (``[SYS_]ID_{MIN,MAX}``) as defined in
:manpage:`login.defs(5)`.

When creating system groups, :manpage:`groupadd` scans **all** GIDs from
``SYS_GID_MAX`` to ``SYS_GID_MIN``. This causes a number of requests to AD,
which is usually not a problem but can be, if those take a long time to
complete. This used to happen without the ``ad_enabled_domains`` setting for
example. ``sssd`` would query ``d.ethz.ch`` in addition to ``d.psi.ch``, which
would time out after a few seconds.


PAM details
~~~~~~~~~~~

There have been discussions to move :manpage:`pam_access` to the ``auth``
section (from the ``account`` section) to prevent information leakage for
accounts that can't even log in: an attacker would get a different error message
depending on whether the password was wrong or whether :manpage:`pam_access`
didn't allow access.

The problem is that when using Kerberos authentication, sshd does not use PAM
for authentication, circumventing :manpage:`pam_access`. Hence, just moving the
latter from ``account`` to ``auth`` does not work.


Kerberos ticket/AFS token renewal
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Kerberos tickets and AFS tokens are automatically renewed for as long as
possible. This is done by running a :manpage:`krenew` for every session in the
background.

