1AUTHSELECT-MIGRATIO(7)                                  AUTHSELECT-MIGRATIO(7)
2
3
4

NAME

6       authselect-migration - A guide how to migrate from authconfig to
7       authselect.
8

DESCRIPTION

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

MAIN DIFFERENCES

16       Authselect takes a completely different approach to system
17       configuration than the previous tool authconfig.
18
19       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
25       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
35       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
48       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

JOINING REMOTE DOMAINS

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

CONVERTING YOUR SCRIPTS

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
68       Table 1. Relation of authconfig options to authselect profiles
69       ┌────────────────────┬────────────────────┐
70       │                    │                    │
71Authconfig 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
92       Table 2. Relation of authconfig options to authselect profile features
93       ┌────────────────────┬────────────────────────────┐
94       │                    │                            │
95Authconfig 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
125           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
132       Examples.
133
134           authconfig --enableldap --enableldapauth --enablefaillock --updateall
135           authselect select sssd with-faillock
136
137           authconfig --enablesssd --enablesssdauth --enablesmartcard --smartcardmodule=sssd --updateall
138           authselect select sssd with-smartcard
139
140           authconfig --enableecryptfs --enablepamaccess --updateall
141           authselect select sssd with-ecryptfs with-pamaccess
142
143           authconfig --enablewinbind --enablewinbindauth --winbindjoin=Administrator --updateall
144           realm join -U Administrator --client-software=winbind WINBINDDOMAIN
145
146

CONFIGURATION FILES

148       This section contains snippets for minimal configuration of various
149       services.
150
151   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
156       "/etc"/openldap/ldap.conf.
157
158           # Set the default base dn
159           BASE   dc=example,dc=com
160
161           # Set the default LDAP server
162           URI    ldap://ldap.example.com ldap://ldap-master.example.com:666
163
164
165   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
170       "/etc"/krb5.conf.
171
172           [libdefaults]
173            default_realm = MYREALM
174
175           [realms]
176            MYREALM = {
177             kdc = kdc.myrealm.org
178            }
179
180           [domain_realm]
181            myrealm.org = MYREALM
182            .myrealm.org = MYREALM
183
184
185   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
191       "/etc"/sssd/sssd.conf.
192
193           [sssd]
194           config_file_version = 2
195           domains = default
196
197           [domain/default]
198           id_provider = ldap
199           ldap_uri = _srv_
200           dns_discovery_domain = myrealm
201
202       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
206       "/etc"/sssd/sssd.conf.
207
208           [sssd]
209           config_file_version = 2
210           domains = default
211
212           [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
220       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
225   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
231   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
236       "/etc"/yp.conf.
237
238           domain mydomain broadcast
239           # or
240           # domain mydomain server myserver
241
242       NIS domain must be also set in system network configuration.
243
244       "/etc"/sysconfig/network.
245
246           NISDOMAIN=mydomain
247
248       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
252           $ domainname mydomain
253           $ setsebool -P allow_ypbind 1
254
255   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
261       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

STARTING SERVICES

266       Depending on your configuration, you need to start required services
267       manually with systemd.
268
269       •   SSSD
270
271               systemctl enable sssd.service ; systemctl start sssd.service
272
273       •   Winbind
274
275               systemctl enable winbind.service ; systemctl start winbind.service
276
277       •   NIS
278
279               systemctl enable rpcbind.service ; systemctl start rpcbind.service
280               systemctl enable ypbind.service ; systemctl start ypbind.service
281
282       •   If mkhomedir feature is enabled
283
284               systemctl enable oddjobd.service ; systemctl start oddjobd.service
285

AUTHCONFIG TOOLS

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

SEE ALSO

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
295
296
297                                  2021-06-05            AUTHSELECT-MIGRATIO(7)
Impressum