docs/doc/source/security/kubernetes/sssd-support-5fb6c4b0320b.rst

595 lines
22 KiB
ReStructuredText
Raw Blame History

This file contains invisible Unicode characters

This file contains invisible Unicode characters that are indistinguishable to humans but may be processed differently by a computer. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

.. _sssd-support-5fb6c4b0320b:
============================================================
SSH User Authentication using Windows Active Directory (WAD)
============================================================
By default, |SSH| to |prod| hosts supports authentication using the 'sysadmin'
Local Linux Account and |prod| Local |LDAP| Linux User Accounts. |SSH| can
also be optionally configured to support authentication with 1 or more remote
|LDAP| identity providers (such as |WAD|). Internally,
|SSH| uses |SSSD| service to provide NSS and PAM interfaces and a backend
system able to remotely connect to multiple different |LDAP| domains.
|SSSD| provides a secure solution by using data encryption for |LDAP| user
authentication. |SSSD| supports authentication only over an encrypted channel.
In summary the |SSH|/|SSSD| solution for remote |LDAP| authentication includes:
- Multi domain remote |LDAP| authentication
- Extra security by using data encryption for |LDAP| user authentication
- Offline authentication if a |LDAP| identity store is unavailable, by
caching users and managing caching timeout and refresh
- High authentication and authorization performance
In |prod| a maximum of 3 |LDAP| |WAD| domains are supported besides the local
Openldap domain.
.. note::
SSH/SSSD authentication configuration described in this section also
applies to local console logins.
You can find more information about |SSSD| configuration at
`https://linux.die.net/man/5/sssd.conf
<https://linux.die.net/man/5/sssd.conf>`__ and
`https://linux.die.net/man/5/sssd-ldap
<https://linux.die.net/man/5/sssd-ldap>`__.
--------------------------
Install WAD CA Certificate
--------------------------
To be able to successfully connect to a |WAD| domain through a secure |SSL|
connection, |SSSD| requires the |SSL| Certificate of the |CA| that signed the
remote |WAD| server's SSL Certificate to be installed on the |prod| system. The
|WAD| |CA| |SSL| certificate needs to be installed before the corresponding AD
domain is added.
The command to add |WAD| |CA| certificate:
.. code-block:: none
system ca-certificate-install <AD CA certificate file>
---------------------
Add Remote WAD Domain
---------------------
A maximum of three remote |LDAP| AD domains are supported in |prod|:
``ldap-domain1``, ``ldap-domain2``, ``ldap-domain3``. Each domain needs to be
configured using mandatory and optional service parameters. Each parameter will
be validated according to industry standard validation rules for correct syntax
that apply to domain names, ldap url, and directory names. An error message
will be displayed if the parameter does not have the standard syntax.
Mandatory parameters
--------------------
To add a new remote ldap |WAD| domain the following mandatory |SSSD| parameters
need to be added using system service parameter commands:
- ``domain_name``
A valid domain name (example: ``wad.mydomain.com``) that will be the name of the
|SSSD| domain configuration section (example: [domain/<domain name>]).
- ``ldap_uri``
The server URI that the |SSSD| client needs to connect to. For example:
``ldaps://wad.mydomain.com`` where ``ldaps`` indicates that the secure |LDAP|
protocol should be used for the connection. This |SSSD| attribute can accept
the IP address of the server but it is not recommended.
- ``ldap_access_filter``
An |LDAP| search filter criteria that must be met for the user to get
access on this host. All the |WAD| server supported filters are allowed.
For the |WAD| supported filters, see
`https://learn.microsoft.com/en-us/archive/technet-wiki/5392.active-directory-ldap-syntax-filters
<https://learn.microsoft.com/en-us/archive/technet-wiki/5392.active-directory-ldap-syntax-filters>`__.
Verify that the |LDAP| filter is valid using the :command:`ldapsearch`
command prior to setting it in the ``ldap_access_filter`` parameter.
.. note::
Offline caching for this feature is limited to determining whether the
user's last online login was granted access permission. If they were
granted access during their last login, they will continue to get
access while offline and vice-versa.
- ``ldap_search_base``
The default base |DN| used to perform |LDAP| searches. The filter must be a
valid |LDAP| search filter as specified by `http://www.ietf.org/rfc/rfc2254.txt <http://www.ietf.org/rfc/rfc2254.txt>`__.
Example: ``ldap_search_base=CN=Users,DC=wad,DC=mydomain,DC=com``.
- ``ldap_default_bind_dn``
The default bind |DN| used to perform |LDAP| operations. Example:
``ldap_default_bind_dn=CN=Administrator,CN=Users,DC=wad,DC=mydomain,DC=com``.
- ``ldap_default_authtok``
The authentication token of the default bind |DN|. Currently, only clear
text passwords are supported.
If a mandatory parameter is missing, an error will be displayed, naming the
missing parameter for the domain and the domain will not be created.
Commands to add mandatory parameters for a remote ldap domain:
.. code-block:: none
system service-parameter-add <service_name> <section_name> parameter_name=<parameter_value>
# <service_name> is “identity” for all domains.
# <section_name> identifies a domain as either “ldap-domain1”, “ldap-domain2” or “ldap-domain3”.
Example:
system service-parameter-add identity ldap-domain1 domain_name=ad.wad-server.com
system service-parameter-add identity ldap-domain1 ldap_uri=ldaps://ad.wad-server.com
system service-parameter-add identity ldap-domain1 ldap_access_filter=memberOf=CN=allowedusers,CN=Users,DC=wad-server,DC=com
system service-parameter-add identity ldap-domain1 ldap_search_base=CN=Users,DC=wad-server,DC=com
system service-parameter-add identity ldap-domain1 ldap_default_bind_dn=CN=Administrator,CN=Users,DC=wad-server,DC=com
system service-parameter-add identity ldap-domain1 ldap_default_authtok =Passw0rd*
.. note::
The ``ldap_access_filter`` service parameter can be configured to allow
access to the Linux host. In the following example, the access is
restricted to members of the group ``allowedusers``. Users that are not
part of ``allowedusers`` will get the message ``Authentication failed``.
Here, ``allowedusers`` is an example of a |WAD| group.
.. code-block:: none
system service-parameter-add identity ldap-domain1 ldap_access_filter=memberOf=CN=allowedusers,CN=Users,DC=wad-server,DC=com
The ``allowedusers`` group is a |WAD| group where the ``gidNumber``
|LDAP| attribute must be set to a unique group number among Linux groups so
that it is mapped on the Linux platform as a Linux |LDAP| group with a
unique ``gid`` value.
For more details on |SSSD| parameters, refer to `https://linux.die.net/man/5/sssd-ldap <https://linux.die.net/man/5/sssd-ldap>`__.
Optional Parameters
-------------------
There are two optional domain parameters that can be added using system service
parameter commands:
- ``ldap_user_search_base``
An optional base |DN|, search scope, and |LDAP| filter to restrict |LDAP| searches
for user objects. If not specified, the default value is ``ldap_search_base``.
- ``ldap_group_search_base``
An optional base |DN|, search scope, and |LDAP| filter to restrict |LDAP| searches
for group objects. If not specified, the default value is ``ldap_search_base``.
For example:
.. code-block:: none
system service-parameter-add identity ldap-domain1 ldap_user_search_base=CN=Users,DC=wad-server,DC=com
system service-parameter-add identity ldap-domain1 ldap_group_search_base=CN=Groups,DC=wad-server,DC=com
For more details on |SSSD| parameters, refer to `https://linux.die.net/man/5/sssd-ldap <https://linux.die.net/man/5/sssd-ldap>`__.
Apply parameters
----------------
After all the domain mandatory parameters are added and if needed, the optional
ones, the parameters will be applied using :command:`service-parameter-apply`
command. Only after “apply” command the sssd domain configuration will be added to
``/etc/sssd/sssd.conf`` and becomes active, and the SSSD daemon will connect to
the remote |WAD| server.
The :command:`system service-parameter-apply` command has been enhanced for
this feature to include a ``section`` parameter that did not exist in the
previous release. The new ``section`` parameter is an optional parameter of the
:command:`service-parameter-apply` command. In the context of the ``identity``
service ldap domains it is needed to specify the domain section name, as
follows:
.. code-block:: none
system service-parameter-apply <service-name> --section <section-name>
E.g.:
system service-parameter-apply identity --section ldap-domain1
Default WAD Domain Configuration
---------------------------------
The default |WAD| domain configuration parameters are pre-configured. Main |SSSD|
default configuration settings include:
- Offline Authentication is enabled, allowing users to still authenticate
even if the ldap identity provider is unavailable. using their cached
credentials. User credentials caching is enabled by parameter setting
``cache_credentials = true``. After a successful login user credentials are
stored as part of the user account in the |SSSD| cache.
- |WAD| Domain enumeration is disabled by using the default setting
``enumerate = false`` for performance reasons.
- User home directory on the |prod| platform gets created after the first
user login with the following path ``/home/<domain_name>/<user_name>``.
- |CA| server certificate verification is always required by using the default
setting for ``ldap_tls_reqcert`` parameter as ``demand``.
-----------------------------
SSH using the WAD domain user
-----------------------------
Verify SSSD is Connected to the Domain
--------------------------------------
If the |SSSD| is connected to a |WAD| domain, then the domain users have been
discovered and cached on the host. The same applies to the domain groups.
Run ``getent passwd <user_login_name>@<domain_name>``, to see if the user has
been cached on the host.
.. code-block:: none
getent passwd pvtest1@ad.wad-server.com
Run ``getent group <group_name>@<domain_name>`` to see the group and its members.
.. code-block:: none
getent passwd eng@ad.wad-server.com
Remote SSH
----------
Once the |SSSD| is connected to the domain, a domain user can be used to |SSH|
to the |prod| host. If a user has the same user login name in multiple domains,
the domain name can be used to distinguish between the common name users.
.. code-block:: none
ssh -l <domain_user_name>@<domain_name> <host_IP_address>
The automatically created home directory for the user is
``/home/<domain_name>/<user_name>``.
-----------------------------------
Modify/Delete WAD Domain parameters
-----------------------------------
Modify an |SSSD| parameter for an ldap domain using system service parameter
command.
The ``service-parameter-apply`` needs to follow the
``service-parameter-modify`` so the parameter value change can take effect.
For example:
.. code-block:: none
system service-parameter-modify identity ldap-domain1 ldap_group_search_base=CN=Users,DC=wad-server,DC=com
system service-parameter-apply identity --section ldap-domain1
Regarding deleting |WAD| domain parameters, only optional |SSSD| service
parameters can be individually deleted:
.. code-block:: none
system service-parameter-delete <parameter-uuid>
system service-parameter-apply identity --section <domain_section_name>
---------------------------------
Delete a WAD Domain configuration
---------------------------------
Optional domain parameters can be deleted individually.
Mandatory parameters cannot be deleted individually, is all or none.
To fully delete a domain, delete all the mandatory parameters and the
configured optional parameters. After that, execute the :command:`service-parameter-apply``
command.
.. code-block:: none
system service-parameter-delete <parameter-uuid>
------------ delete all parameters of the domain-----------
system service-parameter-apply identity --section <domain_section_name>
Deleting a domain will cause the users to not show up with ``getent passwd``
command anymore even if they may have not been removed from cache just yet. The
users will be removed from cache according to cache expiration configuration.
The cache expiry configuration for this release, uses default values.
The |WAD| users home directories created on the platform will not be removed
after the |WAD| domain configuration is removed. It is administrator's
responsibility to clean up users' home directories that are no longer used.
------------------------------------------
SUDO Capability and Local Group Membership
------------------------------------------
This section describes how to enable the ``sudo`` and ``sys_protected`` privileges
for configured users in |WAD| servers.
The Linux specification stipulates that the GUID values in the range 0 to 99
should be statically allocated by the system and shall not be created by
applications. Therefore, a ``sudo`` group with GUID 27 and the ``root`` group
GUID 0 are special groups that cannot be created by the |SSSD| client interfacing
with the |WAD| server.
The ``sudo`` privileges can be assigned to |WAD| users using the ``sudo rules`` mechanism.
``Sudo rules`` are access control rules that define the users who are granted access,
the commands a user has access to, and the target hosts to which the rules
apply.
Enable Sudo Privileges for WAD Users
-------------------------------------
You can enable ``sudo All`` privileges for LDAP users from a remote |WAD| server.
Enabling ``sudo`` privileges allows the LDAP users to execute the following
operations:
- ``sw_patch`` to unauthenticated endpoint
- ``docker`` and/or ``crictl`` commands to communicate with the respective daemons
- Utilities ``show-certs.sh`` and ``license-install`` (recovery only)
- IP configuration for local network setup
- Password change of local openldap users
- Access to restricted files, example: restricted logs
- Manual reboots
Load Sudo Schema in WAD LDAP Server
-----------------------------------
The ``sudo rules`` schema is not a part of standard |WAD| installation. For |WAD|
servers, the schema needs to be loaded and installed using the ``ldifde``
utility.
LDAP ``sudo rules`` schema is contained in the package ``libsss-sudo``. The
schema will be loaded in ``/usr/share/doc/sudo-ldap/schema.ActiveDirectory.gz``
during system installation.
Install Schema
--------------
.. rubric:: |proc|
#. Extract the schema from ``schema.ActiveDirectory.gz`` and copy it in a file
on the |WAD| server.
#. Install the schema by running the following command on the |WAD| server:
.. code-block:: none
ldifde -v -i -f ``schema.ActiveDirectory.txt`` -j
.. rubric:: |result|
The following shows the successful loading of a schema:
.. code-block:: none
Importing directory from file ``schema.ActiveDirectory.txt``
Loading entries
…….
12 entries modified successfully.
The command has completed successfully
Create Directory Entry for Sudo Rules in WAD Server
---------------------------------------------------
The ``sudoers`` OU needs to be created on the domain root. This OU will hold all
the ``sudo rules`` defined using ``sudoRole`` object.
.. note::
The ``sudoers`` OU directory path will be automatically set as the
``ldap_sudo_search_base`` parameter value in the sssd configuration file
``/etc/sssd/sssd.conf``. The ``ldap_search_base`` parameter
must be set at the same level in the domain root as shown in the following example:
.. code-block:: none
ldap_search_base = CN=Users,DC=domain,DC=com (set using ``system service-parameter`` command)
ldap_sudo_search_base = OU=sudoers,DC=domain,DC=com (pre-configured in sssd configuration)
.. rubric:: |proc|
#. Create an ``ldif`` file with the following content:
.. code-block:: none
dn: OU=sudoers,DC= dc=domain,DC=com
changetype: add
objectClass: top
objectClass: organizationalUnit
ou: sudoers
#. Import the file by running the following command on the |WAD| server:
.. code-block:: none
ldifde -v -i -f "sudoers_ou.txt" -j
where, ``sudoers_ou.txt`` is the ``ldif`` file created in the previous step.
.. rubric:: |result|
The following shows the successful loading of the ``ldif`` file:
.. code-block:: none
Connecting to ``ad.domain.com``
Logging in as current user using SSPI
Importing directory from file "sudoers_ou.txt"
Loading entries
1: OU=sudoers,DC=domain,DC=com
Entry modified successfully
Create a Sudo Rule for a WAD User
---------------------------------
.. rubric:: |proc|
#. To assign ``sudo All`` privileges to a |WAD| user with name ``techadmin``, create
and load the following ``ldif`` file content:
.. code-block:: none
dn: CN=techadmin,OU=sudoers,DC=domain,DC=com
changetype: add
objectClass: top
objectClass: sudoRole
cn: techadmin
distinguishedName: CN=techadmin,OU=sudoers,DC=domain,DC=com
name: techadmin
sudoUser: techadmin
sudoHost: ALL
sudoRunAsUser: ALL
sudoCommand: ALL
#. Load the ``ldif`` file by running the following command on the |WAD| server:
.. code-block:: none
ldifde -v -i -f "sudo-rule.txt" -j
where, ``sudo-rule.txt`` is the ``ldif`` file created in the previous step.
.. rubric:: |result|
The following shows the successful loading of the ``ldif`` file:
.. code-block:: none
Connecting to "ad.domain.com"
Logging in as current user using SSPI
Importing directory from file "sudo-rule.txt"
Loading entries
1: CN=techadmin,OU=sudoers,DC=domain,DC=com
Entry modified successfully.
1 entry modified successfully.
The command has completed successfully
The ``sudo rules`` will be discovered by sssd service and cached in the |prod|
platform. The sssd logs in ``/var/log/sssd/sssd_ad.domain.log`` will show the
number of rules downloaded from |WAD| server that indicates that the ``sudo rules``
were received.
.. code-block:: none
(2023-02-28 22:35:16): [be[ad.domain.com]] [sdap_search_bases_ex_donee] (0x0400): Receiving data from base [OU=sudoers,DC=domain,DC=com]
(2023-02-28 22:35:16): [be[ad.domain.com]] [sdap_sudo_load_sudoers_done] (0x0200): Received 1 sudo rules
(2023-02-28 22:35:16): [be[ad.domain.com]] [sdap_sudo_refresh_done] (0x0400): Received 1 rules
Verify Sudo All Privileges for the WAD Sudo User
------------------------------------------------
SSH to the |prod| platform using the ``sudo`` user and verify that the user has
``sudo All`` privileges.
.. code-block:: none
techadmin@controller-0:~$ sudo -l
Password:
Matching Defaults entries for techadmin on controller-0:
env_reset, mail_badpass,
secure_path=/usr/local/sbin\:/usr/local/bin\:/usr/sbin\:/usr/bin\:/sbin\:/bin,
lecture=never,
secure_path=/usr/local/bin\:/usr/bin\:/bin\:/usr/local/sbin\:/usr/sbin\:/sbin,
lecture=never,
secure_path=/usr/local/bin\:/usr/bin\:/bin\:/usr/local/sbin\:/usr/sbin\:/sbin,
passprompt="Password: "
User techadmin may run the following commands on controller-0:
(ALL) ALL
techadmin@controller-0:~$
Creating a User in the Linux Sys_protected Group on a WAD Server
----------------------------------------------------------------
Create a ``sys_protected`` group in the |WAD| server and set the ``gidNumber`` to
345 to be the same as Linux ``sys_protected`` group. Add a |WAD| user (example:
techadmin) as a member in the ``sys_protected`` group. The ``sys_protected``
LDAP group and its member will be discovered and cached in the |prod| platform
by SSSD service.
To check if the |WAD| user has been added to the ``sys_protected`` group, SSH to
|prod| as the |WAD| user and check the groups the user is a member of.
.. code-block:: none
Linux controller-0 5.10.0-6-amd64 #1 SMP PREEMPT StarlingX Debian 5.10.162-1.stx.64 (2023-02-16) x86_64
Last login: Fri Mar 10 22:20:16 2023 from 10.10.10.254
techadmin@controller-0:~$ groups
domain users sys_protected
techadmin@controller-0:~$
.. note::
When creating a |WAD| user that will be discovered and created on the
|prod| Linux host as part of the ``users`` group, set the |WAD| user GUID value
to 100 that is the same as that of the Linux ``users`` group. The |WAD| user
UID should be set to a unique value within the Linux ``users`` group.
When a new |WAD| user is created using the Active Directory Users and Group
Administration tool, the **User must change password at next login**
checkbox must be unchecked, otherwise the user login to the |prod| host will fail.
-------------------------------------------
Default Local OpenLDAP Domain Configuration
-------------------------------------------
The configuration for the local OpenLDAP domain is part of the default |SSSD|
configuration.
All the local OpenLDAP domain parameters are pre-configured. Main |SSSD|
default configuration settings include:
- Domain enumeration is enabled as the local domain number of users is not as
large to pose performance issues. The use of command :command:`getent passwd`
will list all the remote domain discovered users.
- The user home directory on the |prod| platform gets created after the
first user login and has the following path ``/home/<user_name>``.
- |CA| server certificate verification is always required by using the default
setting for ``ldap_tls_reqcert`` parameter as ``demand``.
The OpenLDAP |SSL| certificate is created and managed internally by
|prod| platform.
---------
SSSD logs
---------
|SSSD| logs can be viewed on the host, in directory ``/var/log/sssd/sssd.log``.
Each domain also has its own log file: ``/var/log/sssd/sssd_<domain_name>.log``.