Sparks Installation

1. Overview

This document is out of date but will remain here for the time being.

We suggest tha you refer to the current OpenSolaris Admin guides for
the most current versions of this documentation.

4. Self-Credentials Setup

4.1. Requirements.

In order to enable the self credential feature in the sparks project,
DNS must be setup to perform host name lookups, there
must be a KDC server and an LDAP server that supports the sasl GSSAPI
mechanism.

DNS name resolution is required by GSSAPI/Kerberos environment and
used during kerberos authentication.

The JES DS 5.2 and later directory server releases support the necessary
sasl GSSAPI mechanism. However, 5.2 patch 3 has a sasl bug that makes
sasl GSSAPI binds fail. So if you are using this version update to the
latest patch levels to avoid this bug.

To check to see if an installed LDAP server supports this feature, run
following command to see if the GSSAPI mechanisms are supported.

    /usr/bin/ldapsearch -h DIRECTORY-SERVER -p 389 -b "" -s base \\
            "objectclass=*" supportedSASLMechanisms | grep GSSAPI

The following should be returned:

    supportedSASLMechanisms: GSSAPI

If GSSAPI is not supported if there will probably be no output.

Any Kerberos KDC delivered with S10 or a later release should work fine.
Earlier Solaris KDCs and KDCs from other vendors that are compatible with
the versions listed above will also probably work. However, to date no
compatibility testing has been performed any other KDCs so we are unable
to make any further claims.

The directory server testing to date has only been performed
using JES 5.2 and JES 6.0 directory server builds.  Solaris 10 and
Solaris Nevada are known to work with other directories, and sparks
should also work in a like manner.  Again however, no directory
compatibility testing has been performed to date.

4.2. Set up KDC servers.

If you have already have a running KDC server, you can skip this part.

For additional KDC reference materials 2) see
System Administration Guide: Security Services - Kerberos Service.

In the following examples, the host name of KDC server is
kdc.example.com and the Kerberos realm is SPARKS.COM

4.2.1) Make sure DNS is running.

See the System Administration Guide: Naming and Directory Services (DNS, NIS, and LDAP) for questions about DNS setup.

4.2.2) Become superuser(root)

4.2.3) Edit /etc/krb5/krb5.conf

e.g.

    [libdefaults]
            default_realm = SPARKS.COM
    
    [realms]
            SPARKS.COM = {
                    kdc = kdc.example.com
                    admin_server = kdc.example.com
            }
    
    [domain_realm]
            .example.com = SPARKS.COM
    
    [logging]
            default = FILE:/var/krb5/kdc.log
            kdc = FILE:/var/krb5/kdc.log
            kdc_rotate = {

4.2.4) Edit /etc/krb5/kdc.conf

  e.g.

    [kdcdefaults]
            kdc_ports = 88,750
    
    [realms]
            SPARKS.COM = {
                    profile = /etc/krb5/krb5.conf
                    database_name = /var/krb5/principal
                    admin_keytab = /etc/krb5/kadm5.keytab
                    acl_file = /etc/krb5/kadm5.acl
                    kadmind_port = 749
                    max_life = 8h 0m 0s
                    max_renewable_life = 7d 0h 0m 0s
                    default_principal_flags = +preauth
            }

4.2.5) Create the KDC database by using the kdb5_util command.

  e.g.

    /usr/sbin/kdb5_util create -r SPARKS.COM -s

4.2.6) Edit the Kerberos access control list file  /etc/krb5/kadm5.acl

    super/admin@SPARKS.COM *

4.2.7). Start the kadmin.local command and add principals.
 
# /usr/sbin/kadmin.local kadmin.local: addprinc super/admin Enter password for principal super/admin@SPARKS.COM:<Type the password> Re-enter password for principal super/admin@SPARKS.COM: <Type it again> Principal "super/admin@SPARKS.COM" created. kadmin.local:

4.2.8). Create the kiprop principals.

    kadmin.local: addprinc -randkey kiprop/kdc.example.com
    Principal "kiprop/kdc.example.com@SPARKS.COM" created.
    kadmin.local:

4.2.9) Create a keytab file for the kadmind service.

    kadmin.local: ktadd -k /etc/krb5/kadm5.keytab kadmin/kdc.example.com
    kadmin.local: ktadd -k /etc/krb5/kadm5.keytab changepw/kdc.example.com
    kadmin.local: ktadd -k /etc/krb5/kadm5.keytab kadmin/changepw
    kadmin.local:

4.2.10) Add the kiprop principal for the master KDC server to the kadmind keytab file.

    kadmin.local: ktadd -k /etc/krb5/kadm5.keytab kiprop/kdc.example.com

4.2.11) Quit kadmin.local.

    kadmin.local: quit

4.2.12) Start the Kerberos daemons.

    # svcadm enable -r network/security/krb5kdc
    # svcadm enable -r network/security/kadmin

4.2.13) Start kadmin

    # /usr/sbin/kadmin -p super/admin
    Enter password: <Type super/admin password>
    kadmin:

4.2.14) Create the master KDC host principal.

kadmin: addprinc -randkey host/kdc.example.com kadmin:

4.2.15) Add the master KDC's host principal to the master KDC's keytab file.

    kadmin: ktadd host/kdc.example.com

4.2.16) Quit kadmin.

    kadmin: quit

Now the KDC is configured.

4.3. Create a Kerberos client installation profile.

in a safe location.  Such as /usr/tmp or other.  For these
instructions we 'll use /usr/tmp/krb5.profile.

e.g.

    # cat /usr/tmp/krb5.profile
    
    REALM SPARKS.COM
    KDC kdc.example.com
    ADMIN super/admin
    FILEPATH /usr/tmp/krb5.conf
    NFS 1
    DNSLOOKUP none

4.4. Set up LDAP servers.

If you have already have an LDAP server running, you can skip 1) .
 

4.4.1) Install a (JES) DS server.

See the Directory Server Download Page
or the Directory Server Enterprise Edition page for more details.

See the following Identity mapping and LDAP server configuration. for
specific direcotry server configuration/setup details.

After the directory server is installed for use:

4.4.2) Run /usr/lib/ldap/idsconfig to configure the LDAP server.

    # /usr/lib/ldap/idsconfig
    Do you wish to continue with server setup (y/n/h)? [n] y
    
    Enter the iPlanet Directory Server's (iDS) hostname to setup: kdc.example.com
    
    Enter the port number for iDS (h=help): [389] <Enter your port>
    
    Enter the directory manager DN: [cn=Directory Manager] <Enter your DN>
    Enter passwd for cn=Directory Manager : <Enter your password>
    
    Enter the domainname to be served (h=help): [example.com] <Enter
    your domain>
    
    Enter LDAP Base DN (h=help): [dc=central,dc=sun,dc=com] <Enter your DN>
    
    GSSAPI is supported. Do you want to set up gssapi:(y/n) [n] y
    
    Enter Kerberos Realm: [EXAMPLE.COM] SPARKS.COM
    
    You can create a sasl/GSSAPI enabled profile with default values now.
    Do you want to create a sasl/GSSAPI default profile ? [n] y
    
    Enter the profile name (h=help): [gssapi~_SPARKS.COM] <Enter>
    
    GSSAPI setup is done.
    
    You can continue to create a profile and
    configure the LDAP server.
    Or you can stop now.
    
    Do you want to stop:(y/n) [n] 
         Say no so it continue to configure the server or yes to stop here

If you say yes, idsconfig stop here, and it will not continue to do the
actual configuration that was perfomed when the first time idsconfig was run.

If you haven't run idsconfig before, say no and let it continue.
idsconfig prompts you to create a customized profile.
idsconfig recommended that you create a profile with proxy credential level
and simple authentication method so you can initialize a non
self credentialed NL client to compare with self credentialed
clients initialized by gssapi_REALM.

4.4.3) Add Host Principals for the KDC and Directory Server Machines.

You can do this on the KDC machine or any kerberized machines.
KDC and the LDAP server can be on the same machine.

    # /usr/sbin/kadmin -p super/admin
    Enter Password:
    kadmin: add_principal -randkey host/kdc.example.com
    kadmin: ktadd host/kdc.example.com
    kadmin: add_principal -randkey host/kdc.example.com
    kadmin: ktadd host/kdc.example.com
    kadmin: quit

4.4.4) Add an LDAP Principal for the Directory Server.

    # /usr/sbin/kadmin -p super/admin
    Enter Password:
    kadmin: add_principal -randkey ldap/kdc.example.com
    Principal "ldap/kdc.example.com@SPARKS.COM" created.
    kadmin: quit

4.4.5) Create a Directory Server Keytab. run this on the directory server machine.

    # /usr/sbin/kadmin -p super/admin
    Enter Password:
    kadmin: ktadd -k /export/home/ldap.keytab ldap/kdc.example.com
    kadmin: quit

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

    # chown root:root /export/home/ldap.keytab
    # chmod 600 /export/home/ldap.keytab

4.4.7) Edit start-slapd script.

e.g.

    #!/bin/sh
    
    # Configure the server to use a custom Kerberos keytab.
    KRB5~_KTNAME=/export/home/ldap.keytab
    export KRB5~_KTNAME
    

4.4.8) Stop the server and start the server so the directory can use the new keytab.

4.5. Configure the clients.

In the following example, the hostname is client.example.com.

4.5.1) Become superuser(root)

4.5.2) Run kclient to initialize Kerberos.

e.g.

    # /usr/sbin/kclient -p /usr/tmp/krb5.profile
    
This prompts you to enter the password for the principal to update KDC.
In the example above, it's super/admin.
After "kclient -p <profile>",
host/client.example.com@SPARKS.COM was added to KDC.

4.5.3) Add user principal to KDC. 

e.g.  assuming login name is foo.

    # kadmin -p super/admin
    Enter Password:
    kadmin: add_principal foo
    Enter password for principal "foo@SPARKS.COM":
    Re-enter password for principal "foo@SPARKS.COM":
    Principal "foo@SPARKS.COM" created.
    kadmin: quit

4.5.4) Edit /etc/nsswitch.ldap. Add dns to "hosts:" and "ipnodes:".

e.g.

    host: files dns
    ipnodes: files dns

4.5.5) Create /etc/resolv.conf with an appropriate DNS configuration.

4.5.6) Start DNS client

    # svcadm enable dns/client

4.5.7) Make sure users, hosts and auto_home entries are added to the LDAP

directory. Without doing so, the principal can't be mapped to the
corrosponding user or host DN.

e.g.

    hostname: client.example.com
    user: foo
    
    The following entries have to be added
    
    dn: uid=foo,ou=People,dc=example,dc=com
      .....
    dn: cn=client+ipHostNumber=9.9.9.9,ou=Hosts,dc=example,dc=com
      .....
    dn:
    automountKey=chinlong,automountMapName=auto_home,dc=example,dc=comdn:
    automountKey=foo,automountMapName=auto_home,dc=example,dc=com
    automountKey: foo
    objectClass: automount
    objectClass: top
    automountInformation: server:/export/home/chinlong

4.5.8) Run ldapclient init to initialize the NL client

    # /usr/sbin/ldapclient init -a profilename=gssapi_SPARKS.COM -a \\
            domainname=example.com 9.9.9.50

4.5.9) Try to login as foo.

Run "kinit -p foo". Run "ldaplist -l passwd foo" in foo's login session and you should see "userpassword". But "ldaplist -l passwd bar"
can get the entry but without "userpassword". root can still see
"userpassword" of everybody.

4.6. What does idsconfig do?

idsconfig adds 2 identity mapping entries and one ACL to ou=people
container.

host/hname.domain@REALM is mapped to "cn=hname+ipHost=<ip>,ou=hosts,BASEDN"

user@REALM is mapped to "uid=user,ou=people,BASEDN"

e.g.

    dn: cn=host~_auth~_SPARKS.COM, cn=GSSAPI,cn=identity mapping,cn=config
    objectClass: top
    objectClass: nsContainer
    objectClass: dsIdentityMapping
    objectClass: dsPatternMatching
    cn: host~_auth~_SPARKS.COM
    dsMatching-pattern: ${Principal}
    dsMatching-regexp: host\\/~(.\*).example.com@SPARKS.COM
    dsSearchBaseDN: ou=hosts,dc=example,dc=com
    dsSearchFilter: (&(objectClass=ipHost)(cn=\$1))
    dsSearchScope: one
    
    dn: cn=user~_auth~_SPARKS.COM, cn=GSSAPI,cn=identity mapping,cn=config
    objectClass: top
    objectClass: nsContainer
    objectClass: dsIdentityMapping
    objectClass: dsPatternMatching
    cn: user~_auth~_SPARKS.COM
    dsMatching-pattern: \${Principal}
    dsMatching-regexp: (.\*)@SPARKS.COM
    dsMappedDN: uid=\$1,ou=People,dc=example,dc=com
    
    
    ACL:
    
    dn: ou=people,dc=example,dc=com
    changetype: modify
    add: aci
    aci: (targetattr="userPassword")(version 3.0; acl self-read-pwd; allow
          (read,search) userdn="ldap:///self" and authmethod="sasl GSSAPI";)
    \-
    add: aci
    aci: (targetattr="userPassword")(version 3.0; acl host-read-pwd; allow
          (read,search)
           userdn="ldap:///cn=\*+ipHostNumber=\*,ou=Hosts,dc=example,dc=com"
           and authmethod="sasl GSSAPI";)

note: the ACLS above are multiple lines due HTML formatting restrictions on this web server

The JES DS does identity matching based on the cn attribute and uses
a regular expression to compare values in ascending order because this
attribute is normall indexed.
The more unique the regular expression is, the fewer comparisons are needed.
However, the attribure/value pair cn=default has special meaning. If
none of rules are matched, the DS falls back to cn=default as the last
ditched effort to match an entry.

e.g.

In the example above, if cn=host_auth_SPARKS.COM is changed to
b_host_auth and user_auth_SPARKS.COM is changed to a_user_auth then it
would fail on host authentication because host\FQDN@REALM is mapped to
uid=host\FQDN@REALM,ou=people,BASEDN.

The users can create their own mapping rules and ACLs to whatever is suitable
for their applications and environments.

idsconfig is designed to provide only basic rules and ACL for a simple standard setup.

Debugging Tips

1) Due to a bug in pkc11softoken, metaslot must currently be disabled when
self credential is enabled. So you will see syslog warning "libsldap:
Metaslot is disabled". If metaslot is enabled, self credential mode won't
work.

2) If the syslog has messages: "libsldap: Status: 7  Mesg:
openConnection: GSSAPI bind failed - 82 Local error", it's likely that
Kerberos is not initialized or ticket is expired. Run "klist" to
browse it. Run "kinit -p foo" or "kinit -R -p foo" and try again.

Or you can add pam_krb5.so.1 to /etc/pam.conf so it does kinit when
you login.

e.g.

    login   auth optional           pam~_krb5.so.1
    rlogin  auth optional           pam~_krb5.so.1
    other   auth optional           pam~_krb5.so.1

3) If a user is kinited and the syslog message indicates "Invalid
credential", then the problem could be the host entry(root) or user entry(self)
is not in LDAP directory or mapping rules are not correct.

4) When "ldapclient init" is executed, it makes some checks if the
LDAP profile contains self/ sasl/GSSAPI configuration.
If it fails at /etc/nsswitch.ldap, it's dns not adding to "host: " and
"ipnodes: ". If it fails due to DNS client not enabled, run "svcs -l
dns/client" to see if /etc/resolv.conf is missing or it's just
disabled. Run "svcadm enable dns/client" to enable it.

If the check fails due to sasl/GSSAPI bind, check syslog to find out
what weng wrong.

You can also run the following command in non-NL environment(e.g. NIS)
to verify if sasl/GSSAPI bind is working.

    /usr/bin/ldapsearch -h host -p port -b baseDN -o mech=GSSAPI -o authzid="" uid=foo