SSH Authentication & Authorization

SSH Authentication

SSH Authentication

SSH User Authentication using sysadmin

By default, SSH to Cloud Platform hosts supports authentication using the sysadmin Local Linux Account.

SSH User Authentication using Local LDAP

By default, SSH to Cloud Platform hosts supports authentication using Cloud Platform Local LDAP Linux User Accounts.

SSH User Authentication using Windows Active Directory (WAD)

SSH can 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 StarlingX 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 and 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 StarlingX system. The WAD CA SSL certificate needs to be installed before the corresponding AD domain is added.

The command to add WAD CA certificate:

system ca-certificate-install <AD CA certificate file>
Add Remote WAD Domain

A maximum of three remote LDAP AD domains are supported in StarlingX: 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. Verify that the LDAP filter is valid using the 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. 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:

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.

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.

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:

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.

Apply parameters

After all the domain mandatory parameters are added and if needed, the optional ones, the parameters will be applied using 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 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 service-parameter-apply command. In the context of the identity service ldap domains it is needed to specify the domain section name, as follows:

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 StarlingX 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.

getent passwd pvtest1@ad.wad-server.com

Run getent group <group_name>@<domain_name> to see the group and its members.

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 StarlingX 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.

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:

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:

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 service-parameter-apply` command.

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.

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 getent passwd will list all the remote domain discovered users.

  • The user home directory on the StarlingX 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 StarlingX 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.

Selectively Disable SSH for Local LDAP and WAD Users

Local LDAP and WAD servers are used for K8s API and SSH authentication. In some cases, it may be necessary to disallow SSH authentication for selective users or a group of users.

The Linux group denyssh is a system created group which is preconfigured in the SSHD configuration such that any member of this group is denied SSH access.

Deny SSH Access Local LDAP Users

Procedure

  1. Create a local LDAP user with the ldapusersetup command and add the user to Linux group denyssh during the creation of the LDAP user account.

    Example:

    [sysadmin@controller-0 ~(keystone_admin)]$ sudo ldapusersetup
Enter username to add to LDAP: test1
Successfully added user test1 to LDAP
Successfully set password for user test1
Warning : password is reset, user will be asked to change password at login
Add test1 to sudoer list? (yes/NO): yes
Successfully added sudo access for user test1 to LDAP
Add test1 to secondary user group? (yes/NO): yes
Secondary group to add user to? [sys_protected]: denyssh
Successfully added user test1 to group cn=denyssh,ou=Group,dc=cgcs,dc=local
Enter days after which user password must be changed [90]:
Successfully modified user entry uid=test1,ou=People,dc=cgcs,dc=local in LDAP
Updating password expiry to 90 days
Enter days before password is to expire that user is warned [2]:
Successfully modified user entry uid=test1,ou=People,dc=cgcs,dc=local in LDAP
Updating password expiry to 2 days

  2. Verify that the new user is a member of the denyssh group.

    Example:

    [sysadmin@controller-0 ~(keystone_admin)]$ id test1
uid=10005(test1) gid=100(users) groups=100(users),10000(denyssh)
[sysadmin@controller-0 ~(keystone_admin)]$ groups test1
test1 : users denyssh
sysadmin@controller-0:~$ getent group|grep denyssh
denyssh:x:10000:test1

  3. Ssh as user test1.

    The ssh should be denied.

  4. Remove the user from denyssh group.

    Example:

    [sysadmin@controller-0 ~(keystone_admin)]$ sudo ldapdeleteuserfromgroup test1 denyssh
Password:
Successfully deleted user test1 from group cn=denyssh,ou=Group,dc=cgcs,dc=local
[sysadmin@controller-0 ~(keystone_admin)]$ id test1
uid=10005(test1) gid=100(users) groups=100(users)

  5. Ssh as user test1.

    The ssh should be allowed.

Deny SSH Access for WAD Users

Procedure

  1. Create a WAD group or use an existing WAD group for the users that should not have access to the platform.

    Note

    The WAD group used should have a name other than denyssh.

  2. Add the WAD user to the WAD group.

    Note

    The WAD user you want to deny access to should not be a member of a WAD group that has allowed access. The allowed user groups are configured with the SSSD parameter ldap_access_filter. Giving and denying access to the user at the same time leads to inconsistent authentication results.

  3. Map the WAD group to the existing Linux group denyssh following the PAM group configuration described in Add LDAP Users to Linux Groups Using PAM Configuration.

    Example: Add the following line in /etc/security/group.conf to map the WAD group to the denysssh Linux group.

    *;*;%disallowed_users@wad.mydomain.com;Al0000-2400;denyssh

  4. Attempt to ssh as the WAD user.

    The ssh should be denied.

  5. Remove the user from the WAD group.

    The user should be able to ssh.

SSH Authorization

Add LDAP Users to Linux Groups Using PAM Configuration

The Linux pam_group module enables binding/mapping of LDAP users/groups to a specified list of one or more Linux groups. The mapping allows Linux capabilities (via the Linux groups) to be assigned to the LDAP users/groups. The mapping will occur after the SSSD service has discovered the LDAP users and groups and cached them on the host.

The mapping between the discovered LDAP users and their group membership to the local Linux groups works for all Linux groups, including system groups, such as sudo and root.

Note

The procedure described in this section applies to all the LDAP users, both Local LDAP and LDAP users in the remote Windows Active Directory servers.

Procedure

Perform the following PAM configuration on all the hosts after the system is installed:

  1. To configure pam_group module, add the following line to the top of the /etc/pam.d/common-auth file after the comments.

    auth    required     pam_group.so use_first_pass

  2. Update /etc/security/group.conf with LDAP groups mapping to Linux groups.

    For each LDAP group mapping to a local Linux group(s), the following line needs to be added to the bottom of the /etc/security/group.conf file using the format services;ttys;users;times;groups:

    *;*;%<fully qualified wad group name>;Al0000-2400;<list of local Linux groups>

    Where, Al0000-2400 stands for times. It is used to indicate when these groups are available to the user. The times format is a logical list of day/time-range entries. Al stands for all seven days of the week.

    Each day/time-range can be prefixed with a ! to indicate anything but.

    The time-range part is two 24-hour times HHMM separated by a hyphen that indicates the start and finish time. More information on the line format can be found in the file /etc/security/group.conf.

    For example:

    *;*;%pvtest@wad.mydomain.com;Al0000-2400;sys_protected,root,sudo

    The example above can be read as: For all services and all ttys, members(%) of pvtest@wad.mydomain.com group, for all days and times (Al0000-2400), add these users to the following local Linux groups:  sys_protected, root, and sudo.

    Note

    The pam_group configuration will enforce the LDAP group membership in Linux groups, after a LDAP mapped group member is successfully authenticated in the platform, either with SSH or direct login.

After the login of a LDAP user that is part of a mapped LDAP group, you can view the new membership to Linux groups. The LDAP user memberships and privileges set with the above example mapping gives a user the following sudo privileges:

WAD user example:

Last login: Mon Jul  8 12:53:12 2024 from 10.10.10.1
pvtest1@wad.mydomain.com@controller-0:~$ source /etc/platform/openrc
[pvtest1@wad.mydomain.com@controller-0 ~(keystone_admin)]$ sudo su
Password:
root@controller-0:/var/home/wad.mydomain.com/pvtest1# groups
root
root@controller-0:/var/home/wad.mydomain.com/pvtest1# exit
exit
[pvtest1@wad.mydomain.com@controller-0 ~(keystone_admin)]$ groups
eng@wad.mydomain.com root sudo sys_protected pvtest@wad.mydomain.com

Local LDAP user example:

Add the following line in /etc/security/group.conf to map users of the Local LDAP group managers to linux groups: sys_protected, root and sudo.

*;*;%managers;Al0000-2400;sys_protected,root,sudo

Log in with user johndole from managers group and check the user’s group memberships and privileges.

johndole@controller-0:~$ id
uid=10007(johndole) gid=100(users) groups=100(users),0(root),27(sudo),345(sys_protected),10001(managers)
johndole@controller-0:~$ source /etc/platform/openrc
[johndole@controller-0 ~(keystone_admin)]$ kubectl config get-contexts
CURRENT   NAME                          CLUSTER      AUTHINFO           NAMESPACE
*         kubernetes-admin@kubernetes   kubernetes   kubernetes-admin

[johndole@controller-0 ~(keystone_admin)]$ groups
users root sudo sys_protected managers
[johndole@controller-0 ~(keystone_admin)]$

[johndole@controller-0 ~(keystone_admin)]$ sudo -l
Password:
Matching Defaults entries for johndole 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 johndole may run the following commands on controller-0:
(ALL : ALL) ALL
(ALL) ALL
[johndole@controller-0 ~(keystone_admin)]$