1AUTHSELECT-MIGRATIO(7) AUTHSELECT-MIGRATIO(7)
2
6 authselect-migration - A guide how to migrate from authconfig to
7 authselect.
8
10 This manual page explains the main differences between authconfig, the
11 previous tool to configure system authentication and identity sources,
12 and authselect which replaces it. It also explains what actions need to
13 be done in order to migrate from authconfig to authselect.
14
16 Authselect takes a completely different approach to system
17 configuration than the previous tool authconfig.
18 Authconfig tries its best to keep users’s manual changes to the files
20 it generates. It generates not only PAM configuration files and
21 nsswitch.conf (to setup authentication modules and identity sources)
22 but it also generates simple configuration files for several services
23 such as LDAP and Kerberos.
24 Authselect does no such things. It does not generate any configuration
26 files beside PAM and nsswitch.conf and it strictly prohibits any manual
27 changes to generated configuration. It provides a set of files called
28 profiles. Each profile describes how the resulting configuration should
29 look like and it can be slightly modified by enabling or disabling
30 certain optional features. If a need arises for a different profile
31 than what authselect ships, the administrator has an option to create a
32 whole new profile and use it with authselect. See
33 authselect-profiles(5) to learn more about profiles.
34 This may seem like a big disadvantage but the truth is the opposite.
36 Authconfig is a very old tool and the applications providing required
37 services have changed rapidly over the years. Typically, there is no
38 longer a need to have multiple authentication modules in PAM and
39 nsswitch.conf, because the vast majority of use-cases is covered by
40 SSSD. Therefore there is no need to add or remove them specifically.
41 There are also better tools to generate configuration for system
42 daemons that can help you automate the process of joining to a remote
43 domain such as realm. In addition, the shipped profiles give us
44 comprehensive and deterministic system configuration that can be fully
45 tested and is much less error prone. It is also much easier to
46 distribute such configuration across many systems.
47 Probably the most controversial change is that authselect only ships
49 profiles for sssd and winbind providers. Those two providers cover all
50 modern use cases from providing local users and legacy LDAP domain to
51 complex configurations with IPA or Active Directory servers. The
52 profiles no longer contain support for nss-pam-ldapd and users are
53 encouraged to switch to sssd.
54
56 You can use either ipa-client-install or realm to join an IPA domain
57 and realm to join an Active Directory domain. These tools will make
58 sure that the correct authselect profile is selected and all daemons
59 and services are properly configured.
60
62 If you use ipa-client-install or realm to join a domain, you can just
63 remove any authconfig call in your scripts. If this is not an option,
64 you need to replace each authconfig call with its equivalent authselect
65 call to select a correct profile with desired features. Then you also
66 need to write configuration file for required services.
67 Table 1. Relation of authconfig options to authselect profiles
69 ┌────────────────────┬────────────────────┐
70 │ │ │
71 │Authconfig options │ Authselect profile │
72 ├────────────────────┼────────────────────┤
73 │ │ │
74 │--enableldap │ sssd │
75 │--enableldapauth │ │
76 ├────────────────────┼────────────────────┤
77 │ │ │
78 │--enablesssd │ sssd │
79 │--enablesssdauth │ │
80 ├────────────────────┼────────────────────┤
81 │ │ │
82 │--enablekrb5 │ sssd │
83 ├────────────────────┼────────────────────┤
84 │ │ │
85 │--enablewinbind │ winbind │
86 │--enablewinbindauth │ │
87 ├────────────────────┼────────────────────┤
88 │ │ │
89 │--enablenis │ nis │
90 └────────────────────┴────────────────────┘
91 Table 2. Relation of authconfig options to authselect profile features
93 ┌────────────────────┬────────────────────────────┐
94 │ │ │
95 │Authconfig options │ Authselect profile feature │
96 ├────────────────────┼────────────────────────────┤
97 │ │ │
98 │--enablesmartcard │ with-smartcard │
99 ├────────────────────┼────────────────────────────┤
100 │ │ │
101 │--enablefingerprint │ with-fingerprint │
102 ├────────────────────┼────────────────────────────┤
103 │ │ │
104 │--enableecryptfs │ with-ecryptfs │
105 ├────────────────────┼────────────────────────────┤
106 │ │ │
107 │--enablemkhomedir │ with-mkhomedir │
108 ├────────────────────┼────────────────────────────┤
109 │ │ │
110 │--enablefaillock │ with-faillock │
111 ├────────────────────┼────────────────────────────┤
112 │ │ │
113 │--enablepamaccess │ with-pamaccess │
114 ├────────────────────┼────────────────────────────┤
115 │ │ │
116 │--enablewinbindkrb5 │ with-krb5 │
117 ├────────────────────┼────────────────────────────┤
118 │ │ │
119 │--enableshadow │ none │
120 ├────────────────────┼────────────────────────────┤
121 │ │ │
122 │--passalgo │ none │
123 └────────────────────┴────────────────────────────┘
124 Note
126 Authconfig options --enableshadow and --passalgo=sha512 were often
127 used to make sure that passwords are stored in /etc/shadow using
128 sha512 algorithm. The authselect profiles now use the yescrypt
129 hashing method and it cannot be changed through an option (only by
130 creating a custom profile). You can just omit these options.
131 Examples.
133 authconfig --enableldap --enableldapauth --enablefaillock --updateall
135 authselect select sssd with-faillock
136 authconfig --enablesssd --enablesssdauth --enablesmartcard --smartcardmodule=sssd --updateall
138 authselect select sssd with-smartcard
139 authconfig --enableecryptfs --enablepamaccess --updateall
141 authselect select sssd with-ecryptfs with-pamaccess
142 authconfig --enablewinbind --enablewinbindauth --winbindjoin=Administrator --updateall
144 realm join -U Administrator --client-software=winbind WINBINDDOMAIN
145
148 This section contains snippets for minimal configuration of various
149 services.
150 LDAP
152 Even if LDAP is not directly used through pam_ldap and nss_ldap, it is
153 still useful to configure ldap.conf to configure openldap-libs and
154 indirectly, e.g. LDAP tools such as ldapsearch.
155 "/etc"/openldap/ldap.conf.
157 # Set the default base dn
159 BASE dc=example,dc=com
160 # Set the default LDAP server
162 URI ldap://ldap.example.com ldap://ldap-master.example.com:666
163 KERBEROS
166 If you use Kerberos, the default Kerberos realm should be configured in
167 order for krb5-libs and therefore tools such as kinit to work out of
168 the box.
169 "/etc"/krb5.conf.
171 [libdefaults]
173 default_realm = MYREALM
174 [realms]
176 MYREALM = {
177 kdc = kdc.myrealm.org
178 }
179 [domain_realm]
181 myrealm.org = MYREALM
182 .myrealm.org = MYREALM
183 SSSD
186 Authselect encourages users to use SSSD wherever possible. There are
187 many configuration options, see sssd.conf(5). This is a minimal
188 configuration that creates one LDAP domain called default. The LDAP
189 server is auto-discovered through DNS lookups.
190 "/etc"/sssd/sssd.conf.
192 [sssd]
194 config_file_version = 2
195 domains = default
196 [domain/default]
198 id_provider = ldap
199 ldap_uri = _srv_
200 dns_discovery_domain = myrealm
201 And here is a configuration snippet for the same domain but now the
203 authentication is done over Kerberos. The KDC server is auto-discovered
204 through DNS lookups.
205 "/etc"/sssd/sssd.conf.
207 [sssd]
209 config_file_version = 2
210 domains = default
211 [domain/default]
213 id_provider = ldap
214 auth_provider = krb5
215 ldap_uri = _srv_
216 krb5_server = _srv_
217 krb5_realm = MYREALM
218 dns_discovery_domain = myrealm
219 If you want to configure SSSD for an IPA or Active Directory domain,
221 use the realm tool. This will perform an initial setup which involves
222 creating a Kerberos keytab and generating basic SSSD configuration. You
223 can then tune it up by modifying "/etc"/sssd/sssd.conf.
224 WINBIND
226 If you want to configure the machine to use Winbind, use realm. This
227 will perform an initial setup which involves creating a Kerberos keytab
228 and running adcli to join the domain. It also makes changes to
229 smb.conf. You can then tune it up by modifying "/etc"/samba/smb.conf.
230 NIS
232 There are several places that needs to be configured in order to make
233 NIS authentication work. First, you need to set NIS domain and
234 optionally also NIS server in "/etc"/yp.conf.
235 "/etc"/yp.conf.
237 domain mydomain broadcast
239 # or
240 # domain mydomain server myserver
241 NIS domain must be also set in system network configuration.
243 "/etc"/sysconfig/network.
245 NISDOMAIN=mydomain
247 Now, you can set the domain name with command line so there is no need
249 to reboot your system. Additionaly, it may be necessary to enable NIS
250 in selinux.
251 $ domainname mydomain
253 $ setsebool -P allow_ypbind 1
254 PASSWORD QUALITY
256 Authselect enables pam_pwquality module to enforce password quality
257 restrictions. This module is enabled only for local users. Remote users
258 should use the password policy that is enforced by the respective
259 remote server.
260 The pam_pwquality module can be configured in
262 "/etc"/security/pwquality.conf. See pam_pwquality(8) to see its
263 configuration options and defaults.
264
266 Depending on your configuration, you need to start required services
267 manually with systemd.
268 • SSSD
270 systemctl enable sssd.service ; systemctl start sssd.service
272 • Winbind
274 systemctl enable winbind.service ; systemctl start winbind.service
276 • NIS
278 systemctl enable rpcbind.service ; systemctl start rpcbind.service
280 systemctl enable ypbind.service ; systemctl start ypbind.service
281 • If mkhomedir feature is enabled
283 systemctl enable oddjobd.service ; systemctl start oddjobd.service
285
287 Authconfig shipped a tool called cacertdir_rehash. If you depend on
288 this tool, please switch to native openssl command: openssl rehash
289 <directory> that serves the same purpose.
290
292 authselect(8), authselect-profiles(5), realm(8), ipa-client-install(1),
293 sssd.conf(5), smb.conf(5), ldap.conf(5), krb5.conf(5)
294 2021-06-05 AUTHSELECT-MIGRATIO(7)