Wiki code for Sparks Installation

Hide Line numbers
1: == 1. Overview
2: 
3: This document describes how to install the sparks beta deliverable and
4: how to setup per-user authentication for evaluation.
5: 
6: This version of the sparks beta release is distributed as a bfu archive.
7: To learn more about the use of bfu refer to the [[Developers Reference Guide>>Community Group on.devref_toc]]
8: [[installing and testing ON>>Community Group on.#5_3_using_bfu_to_install_on]]
9: section for bfu instructions.
10: 
11: If you do not have an OpenSolaris release installed, you should first start by installing the current Solaris Express release. More information about available OpenSolaris distributions can be found [[here>>Main.downloads]].
12: 
13: == 2. System Requirements
14: 
15: This alpha includes bfu binaries for either sparc or x86.  All systems known to work with the [[current ON bfu>>http://dlc.sun.com/osol/on/downloads/current]] should work with these bfu’s.
16: 
17: == 3. Normal Setup/Usage
18: 
19: If you wish to test the sparks infrastructure changes using your existing naming service configuration, the only actions that should be necessary are performing a bfu using the alpha bfu, resolving any conflicts and rebooting.
20: 
21: The [[issues page>>Project sparks.issues]] will discuss any currently known issues/problems/limitations with the sparks alpha release.
22: 
23: == 4. Self-Credentials Setup
24: 
25: === 4.1. Requirements.
26: 
27: In order to enable the self credential feature in the sparks project,
28: DNS must be setup to perform host name lookups, there
29: must be a KDC server and an LDAP server that supports the sasl GSSAPI
30: mechanism.
31: 
32: DNS name resolution is required by GSSAPI/Kerberos environment and
33: used during kerberos authentication.
34: 
35: The JES DS 5.2 and later directory server releases support the necessary
36: sasl GSSAPI mechanism. However, 5.2 patch 3 has a sasl bug that makes
37: sasl GSSAPI binds fail. So if you are using this version update to the
38: latest patch levels to avoid this bug.
39: 
40: To check to see if an installed LDAP server supports this feature, run
41: following command to see if the GSSAPI mechanisms are supported.
42: 
43: {{{
44:     /usr/bin/ldapsearch -h DIRECTORY-SERVER -p 389 -b "" -s base \\
45:             "objectclass=*" supportedSASLMechanisms | grep GSSAPI
46: }}}
47: 
48: The following should be returned:
49: 
50: 
51: {{{
52:     supportedSASLMechanisms: GSSAPI
53: }}}
54: 
55: If GSSAPI is not supported if there will probably be no output.
56:  
57: Any Kerberos KDC delivered with S10 or a later release should work fine.
58: Earlier Solaris KDCs and KDCs from other vendors that are compatible with
59: the versions listed above will also probably work. However, to date no 
60: compatibility testing has been performed any other KDCs so we are unable
61: to make any further claims.
62: 
63: The directory server testing to date has only been performed
64: using JES 5.2 and JES 6.0 directory server builds.  Solaris 10 and
65: Solaris Nevada are known to work with other directories, and sparks
66: should also work in a like manner.  Again however, no directory
67: compatibility testing has been performed to date.
68: 
69: 
70: === 4.2. Set up KDC servers.
71: 
72: If you have already have a running KDC server, you can skip this part.
73: 
74: For additional KDC reference materials 2) see
75: [[System Administration Guide: Security Services - Kerberos Service>>http://docs.sun.com/app/docs/doc/816-4557/6maosrjk5?a=view]].
76: 
77: In the following examples, the host name of KDC server is
78: kdc.example.com and the Kerberos realm is SPARKS.COM
79: 
80: ==== 4.2.1) Make sure DNS is running.
81: 
82: See the [[System Administration Guide: Naming and Directory Services (DNS, NIS, and LDAP)>>http://docs.sun.com/app/docs/doc/816-4556]] for questions about DNS setup.
83: 
84: 
85: ==== 4.2.2) Become superuser(root)
86: 
87: ==== 4.2.3) Edit /etc/krb5/krb5.conf
88: 
89: e.g.
90: 
91: {{{
92:     [libdefaults]
93:             default_realm = SPARKS.COM
94:     
95:     [realms]
96:             SPARKS.COM = {
97:                     kdc = kdc.example.com
98:                     admin_server = kdc.example.com
99:             }
100:     
101:     [domain_realm]
102:             .example.com = SPARKS.COM
103:     
104:     [logging]
105:             default = FILE:/var/krb5/kdc.log
106:             kdc = FILE:/var/krb5/kdc.log
107:             kdc_rotate = {
108: }}}
109: 
110: ==== 4.2.4) Edit /etc/krb5/kdc.conf
111: 
112:   e.g.
113: 
114: {{{
115:     [kdcdefaults]
116:             kdc_ports = 88,750
117:     
118:     [realms]
119:             SPARKS.COM = {
120:                     profile = /etc/krb5/krb5.conf
121:                     database_name = /var/krb5/principal
122:                     admin_keytab = /etc/krb5/kadm5.keytab
123:                     acl_file = /etc/krb5/kadm5.acl
124:                     kadmind_port = 749
125:                     max_life = 8h 0m 0s
126:                     max_renewable_life = 7d 0h 0m 0s
127:                     default_principal_flags = +preauth
128:             }
129: }}}
130: 
131: ==== 4.2.5) Create the KDC database by using the kdb5_util command.
132: 
133:   e.g.
134: 
135: {{{
136:     /usr/sbin/kdb5_util create -r SPARKS.COM -s
137: }}}
138: 
139: ==== 4.2.6) Edit the Kerberos access control list file  /etc/krb5/kadm5.acl
140: 
141: {{{
142:     super/admin@SPARKS.COM *
143: }}}
144: 
145: ==== 4.2.7). Start the kadmin.local command and add principals.
146:   
147: {{{
148:     # /usr/sbin/kadmin.local
149:     kadmin.local: addprinc super/admin
150:     Enter password for principal super/admin@SPARKS.COM:<Type the password>
151:     Re-enter password for principal super/admin@SPARKS.COM: <Type it again>
152:     Principal "super/admin@SPARKS.COM" created.
153:     kadmin.local:
154: }}}
155: 
156: ==== 4.2.8). Create the kiprop principals.
157: 
158: {{{
159:     kadmin.local: addprinc -randkey kiprop/kdc.example.com
160:     Principal "kiprop/kdc.example.com@SPARKS.COM" created.
161:     kadmin.local:
162: }}}
163: 
164: ==== 4.2.9) Create a keytab file for the kadmind service.
165: 
166: {{{
167:     kadmin.local: ktadd -k /etc/krb5/kadm5.keytab kadmin/kdc.example.com
168:     kadmin.local: ktadd -k /etc/krb5/kadm5.keytab changepw/kdc.example.com
169:     kadmin.local: ktadd -k /etc/krb5/kadm5.keytab kadmin/changepw
170:     kadmin.local:
171: }}}
172: 
173: ==== 4.2.10) Add the kiprop principal for the master KDC server to the kadmind keytab file.
174: 
175: {{{
176:     kadmin.local: ktadd -k /etc/krb5/kadm5.keytab kiprop/kdc.example.com
177: }}}
178: 
179: ==== 4.2.11) Quit kadmin.local.
180: 
181: {{{
182:     kadmin.local: quit
183: }}}
184: 
185: ==== 4.2.12) Start the Kerberos daemons.
186: 
187: {{{
188:     # svcadm enable -r network/security/krb5kdc
189:     # svcadm enable -r network/security/kadmin
190: }}}
191: 
192: ==== 4.2.13) Start kadmin
193: 
194: {{{
195:     # /usr/sbin/kadmin -p super/admin
196:     Enter password: <Type super/admin password>
197:     kadmin:
198: }}}
199: 
200: ==== 4.2.14) Create the master KDC host principal.
201:  
202: {{{
203:     kadmin: addprinc -randkey host/kdc.example.com
204:     kadmin:
205: }}}
206: 
207: ==== 4.2.15) Add the master KDC’s host principal to the master KDC’s keytab file.
208: 
209: {{{
210:     kadmin: ktadd host/kdc.example.com
211: }}}
212: 
213: ==== 4.2.16) Quit kadmin.
214: 
215: {{{
216:     kadmin: quit
217: }}}
218: 
219: Now the KDC is configured.
220: 
221: 
222: === 4.3. Create a Kerberos client installation profile.
223: 
224: in a safe location.  Such as /usr/tmp or other.  For these
225: instructions we ’ll use /usr/tmp/krb5.profile.
226: 
227: e.g.
228: 
229: {{{
230:     # cat /usr/tmp/krb5.profile
231:     
232:     REALM SPARKS.COM
233:     KDC kdc.example.com
234:     ADMIN super/admin
235:     FILEPATH /usr/tmp/krb5.conf
236:     NFS 1
237:     DNSLOOKUP none
238: }}}
239: 
240: === 4.4. Set up LDAP servers.
241: 
242: If you have already have an LDAP server running, you can skip 1) .
243:  
244: ==== 4.4.1) Install a (JES) DS server.
245: 
246: See the [[Directory Server Download Page>>http://www.sun.com/download/index.jsp?cat=Identity%20Management&tab=3&subcat=Directory%20Server]]
247: or the [[Directory Server Enterprise Edition>>http://www.sun.com/software/products/directory_srvr_ee/index.xml]] page for more details.
248: 
249: See the following [[Identity mapping and LDAP server configuration.>>http://docs.sun.com/source/817-7613/ssl.html#wp19858]] for
250: specific direcotry server configuration/setup details.
251: 
252: 
253: After the directory server is installed for use:
254: 
255: 
256: ==== 4.4.2) Run /usr/lib/ldap/idsconfig to configure the LDAP server.
257: 
258: 
259: 
260: 
261: {{{
262:     # /usr/lib/ldap/idsconfig
263:     Do you wish to continue with server setup (y/n/h)? [n] y
264:     
265:     Enter the iPlanet Directory Server’s (iDS) hostname to setup: kdc.example.com
266:     
267:     Enter the port number for iDS (h=help): [389] <Enter your port>
268:     
269:     Enter the directory manager DN: [cn=Directory Manager] <Enter your DN>
270:     Enter passwd for cn=Directory Manager : <Enter your password>
271:     
272:     Enter the domainname to be served (h=help): [example.com] <Enter
273:     your domain>
274:     
275:     Enter LDAP Base DN (h=help): [dc=central,dc=sun,dc=com] <Enter your DN>
276:     
277:     GSSAPI is supported. Do you want to set up gssapi:(y/n) [n] y
278:     
279:     Enter Kerberos Realm: [EXAMPLE.COM] SPARKS.COM
280:     
281:     You can create a sasl/GSSAPI enabled profile with default values now.
282:     Do you want to create a sasl/GSSAPI default profile ? [n] y
283:     
284:     Enter the profile name (h=help): [gssapi~_SPARKS.COM] <Enter>
285:     
286:     GSSAPI setup is done.
287:     
288:     You can continue to create a profile and
289:     configure the LDAP server.
290:     Or you can stop now.
291:     
292:     Do you want to stop:(y/n) [n] 
293:          Say no so it continue to configure the server or yes to stop here
294: }}}
295: 
296: If you say yes, idsconfig stop here, and it will not continue to do the
297: actual configuration that was perfomed when the first time idsconfig was run.
298: 
299: If you haven’t run idsconfig before, say no and let it continue.
300: idsconfig prompts you to create a customized profile.
301: idsconfig recommended that you create a profile with proxy credential level
302: and simple authentication method so you can initialize a non
303: self credentialed NL client to compare with self credentialed
304: clients initialized by gssapi_REALM.
305: 
306: 
307: 
308: ==== 4.4.3) Add Host Principals for the KDC and Directory Server Machines.
309: 
310: 
311: You can do this on the KDC machine or any kerberized machines.
312: KDC and the LDAP server can be on the same machine.
313: 
314: {{{
315:     # /usr/sbin/kadmin -p super/admin
316:     Enter Password:
317:     kadmin: add_principal -randkey host/kdc.example.com
318:     kadmin: ktadd host/kdc.example.com
319:     kadmin: add_principal -randkey host/kdc.example.com
320:     kadmin: ktadd host/kdc.example.com
321:     kadmin: quit
322: }}}
323: 
324: ==== 4.4.4) Add an LDAP Principal for the Directory Server.
325: 
326: {{{
327:     # /usr/sbin/kadmin -p super/admin
328:     Enter Password:
329:     kadmin: add_principal -randkey ldap/kdc.example.com
330:     Principal "ldap/kdc.example.com@SPARKS.COM" created.
331:     kadmin: quit
332: }}}
333: 
334: ==== 4.4.5) Create a Directory Server Keytab. run this on the directory server machine.
335: 
336: {{{
337:     # /usr/sbin/kadmin -p super/admin
338:     Enter Password:
339:     kadmin: ktadd -k /export/home/ldap.keytab ldap/kdc.example.com
340:     kadmin: quit
341: }}}
342: 
343: ==== 4.4.6) Change the permissions and ownership on this custom keytab to make it owned by the user account used to run Directory Server and readable only by that user
344: 
345: {{{
346:     # chown root:root /export/home/ldap.keytab
347:     # chmod 600 /export/home/ldap.keytab
348: }}}
349: 
350: ==== 4.4.7) Edit start-slapd script.
351: 
352: e.g.
353: 
354: 
355: {{{
356:     #!/bin/sh
357:     
358:     # Configure the server to use a custom Kerberos keytab.
359:     KRB5~_KTNAME=/export/home/ldap.keytab
360:     export KRB5~_KTNAME
361:     
362: }}}
363: 
364: ==== 4.4.8) Stop the server and start the server so the directory can use the new keytab.
365: 
366: === 4.5. Configure the clients.
367: 
368: In the following example, the hostname is client.example.com.
369: 
370: ==== 4.5.1) Become superuser(root)
371: 
372: ==== 4.5.2) Run kclient to initialize Kerberos.
373: 
374: e.g.
375: 
376: {{{
377:     # /usr/sbin/kclient -p /usr/tmp/krb5.profile
378:     
379: This prompts you to enter the password for the principal to update KDC.
380: In the example above, it’s super/admin.
381: After "kclient -p <profile>",
382: host/client.example.com@SPARKS.COM was added to KDC.
383: }}}
384: 
385: ==== 4.5.3) Add user principal to KDC. 
386: 
387: e.g.  assuming login name is foo.
388: 
389: {{{
390:     # kadmin -p super/admin
391:     Enter Password:
392:     kadmin: add_principal foo
393:     Enter password for principal "foo@SPARKS.COM":
394:     Re-enter password for principal "foo@SPARKS.COM":
395:     Principal "foo@SPARKS.COM" created.
396:     kadmin: quit
397: }}}
398: 
399: ==== 4.5.4) Edit /etc/nsswitch.ldap. Add dns to "hosts:" and "ipnodes:".
400: 
401: e.g.
402: 
403: {{{
404:     host: files dns
405:     ipnodes: files dns
406: }}}
407: 
408: ==== 4.5.5) Create /etc/resolv.conf with an appropriate DNS configuration.
409: 
410: ==== 4.5.6) Start DNS client
411: 
412: {{{
413:     # svcadm enable dns/client
414: }}}
415: 
416: ==== 4.5.7) Make sure users, hosts and auto_home entries are added to the LDAP
417: 
418: directory. Without doing so, the principal can’t be mapped to the
419: corrosponding user or host DN.
420: 
421: e.g.
422: 
423: {{{
424:     hostname: client.example.com
425:     user: foo
426:     
427:     The following entries have to be added
428:     
429:     dn: uid=foo,ou=People,dc=example,dc=com
430:       .....
431:     dn: cn=client+ipHostNumber=9.9.9.9,ou=Hosts,dc=example,dc=com
432:       .....
433:     dn:
434:     automountKey=chinlong,automountMapName=auto_home,dc=example,dc=comdn:
435:     automountKey=foo,automountMapName=auto_home,dc=example,dc=com
436:     automountKey: foo
437:     objectClass: automount
438:     objectClass: top
439:     automountInformation: server:/export/home/chinlong
440: }}}
441: 
442: ==== 4.5.8) Run ldapclient init to initialize the NL client
443: 
444: {{{
445:     # /usr/sbin/ldapclient init -a profilename=gssapi_SPARKS.COM -a \\
446:             domainname=example.com 9.9.9.50
447: }}}
448: 
449: ==== 4.5.9) Try to login as foo.
450: 
451: Run "kinit -p foo". Run "ldaplist -l passwd foo" in foo’s login session and you should see "userpassword". But "ldaplist -l passwd bar"
452: can get the entry but without "userpassword". root can still see
453: "userpassword" of everybody.
454: 
455: 
456: === 4.6. What does idsconfig do?
457: 
458: idsconfig adds 2 identity mapping entries and one ACL to ou=people
459: container.
460: 
461: host/hname.domain@REALM is mapped to "cn=hname+ipHost=<ip>,ou=hosts,BASEDN"
462: 
463: user@REALM is mapped to "uid=user,ou=people,BASEDN"
464: 
465: e.g.
466: 
467: {{{
468:     dn: cn=host~_auth~_SPARKS.COM, cn=GSSAPI,cn=identity mapping,cn=config
469:     objectClass: top
470:     objectClass: nsContainer
471:     objectClass: dsIdentityMapping
472:     objectClass: dsPatternMatching
473:     cn: host~_auth~_SPARKS.COM
474:     dsMatching-pattern: ${Principal}
475:     dsMatching-regexp: host\\/~(.\*).example.com@SPARKS.COM
476:     dsSearchBaseDN: ou=hosts,dc=example,dc=com
477:     dsSearchFilter: (&(objectClass=ipHost)(cn=\$1))
478:     dsSearchScope: one
479:     
480:     dn: cn=user~_auth~_SPARKS.COM, cn=GSSAPI,cn=identity mapping,cn=config
481:     objectClass: top
482:     objectClass: nsContainer
483:     objectClass: dsIdentityMapping
484:     objectClass: dsPatternMatching
485:     cn: user~_auth~_SPARKS.COM
486:     dsMatching-pattern: \${Principal}
487:     dsMatching-regexp: (.\*)@SPARKS.COM
488:     dsMappedDN: uid=\$1,ou=People,dc=example,dc=com
489:     
490:     
491:     ACL:
492:     
493:     dn: ou=people,dc=example,dc=com
494:     changetype: modify
495:     add: aci
496:     aci: (targetattr="userPassword")(version 3.0; acl self-read-pwd; allow
497:           (read,search) userdn="ldap:///self" and authmethod="sasl GSSAPI";)
498:     \-
499:     add: aci
500:     aci: (targetattr="userPassword")(version 3.0; acl host-read-pwd; allow
501:           (read,search)
502:            userdn="ldap:///cn=\*+ipHostNumber=\*,ou=Hosts,dc=example,dc=com"
503:            and authmethod="sasl GSSAPI";)
504: }}}
505: 
506: **note: the ACLS above are multiple lines due HTML formatting restrictions on this web server**
507: 
508: The JES DS does identity matching based on the cn attribute and uses
509: a regular expression to compare values in ascending order because this
510: attribute is normall indexed.
511: The more unique the regular expression is, the fewer comparisons are needed.
512: However, the attribure/value pair cn=default has special meaning. If
513: none of rules are matched, the DS falls back to cn=default as the last
514: ditched effort to match an entry.
515: 
516: e.g.
517: 
518: 
519: In the example above, if cn=host~_auth~_SPARKS.COM is changed to
520: b~_host~_auth and user~_auth_SPARKS.COM is changed to a~_user~_auth then it
521: would fail on host authentication because host\FQDN@REALM is mapped to
522: uid=host\FQDN@REALM,ou=people,BASEDN.
523: 
524: The users can create their own mapping rules and ACLs to whatever is suitable
525: for their applications and environments.
526: 
527: idsconfig is designed to provide only basic rules and ACL for a simple standard setup.
528: 
529: == Debugging Tips
530: 
531: 1) Due to a bug in pkc11softoken, metaslot must currently be disabled when
532: self credential is enabled. So you will see syslog warning "libsldap:
533: Metaslot is disabled". If metaslot is enabled, self credential mode won’t
534: work.
535: 
536: 2) If the syslog has messages: "libsldap: Status: 7  Mesg:
537: openConnection: GSSAPI bind failed - 82 Local error", it’s likely that
538: Kerberos is not initialized or ticket is expired. Run "klist" to
539: browse it. Run "kinit -p foo" or "kinit -R -p foo" and try again.
540: 
541: Or you can add pam~_krb5.so.1 to /etc/pam.conf so it does kinit when
542: you login.
543: 
544: 
545: e.g.
546: 
547: 
548: {{{
549:     login   auth optional           pam~_krb5.so.1
550:     rlogin  auth optional           pam~_krb5.so.1
551:     other   auth optional           pam~_krb5.so.1
552: }}}
553: 
554: 3) If a user is kinited and the syslog message indicates "Invalid
555: credential", then the problem could be the host entry(root) or user entry(self)
556: is not in LDAP directory or mapping rules are not correct.
557: 
558: 4) When "ldapclient init" is executed, it makes some checks if the
559: LDAP profile contains self/ sasl/GSSAPI configuration.
560: If it fails at /etc/nsswitch.ldap, it’s dns not adding to "host: " and
561: "ipnodes: ". If it fails due to DNS client not enabled, run "svcs -l
562: dns/client" to see if /etc/resolv.conf is missing or it’s just
563: disabled. Run "svcadm enable dns/client" to enable it.
564: 
565: If the check fails due to sasl/GSSAPI bind, check syslog to find out
566: what weng wrong.
567: 
568: You can also run the following command in non-NL environment(e.g. NIS)
569: to verify if sasl/GSSAPI bind is working.
570: 
571: {{{
572:     /usr/bin/ldapsearch -h host -p port -b baseDN -o mech=GSSAPI -o authzid="" uid=foo
573: }}}
OpenSolaris

Top Menu

Wiki code for Sparks Installation

Search

Collectives

Community Group

Project

User Group

Subsites

Project sparks Pages
