Integrating Authentication into dCache access methods

Currently we provide three different ways to push a dCache client to use authentication and authorization when talking to a dCache service. Subsequently we are using the term tunnel when referring to any method which securely accesses dCache services. In all cases the path to the tunnel provider library has to be specified in the LD_LIBRARY_PATH environment variable otherwise the tunnel provider has to be the full path to the provider library.
It's obvious that a tunnel provider can only talk to a dCache door supporting exactly the same protocol. If not, the behaviour is undefined and the login will certainly fail.

The order in which the the different provider specifications are honoured is :

The Tunnel functionality has bean tested with the MIT and the Heimdal kerberos5 implementations.

To get the dCache service, namely a door, to use a tunnel, the following steps have to be done:

  1. Compile and create a JAR file from the javatunnel package, which is located in the security_plugins directory in the client source tree. Copy the JAR file into the d-cache/classes directory.

  2. Modify the dCacheSetup file as follows

     
    java_options="$java_options -Djava.security.krb5.realm=YOUR.REALM \ 
        -Djava.security.krb5.kdc=your.kdc \ 
        -Djavax.security.auth.useSubjectCredsOnly=false \ 
        -Djava.security.auth.login.config=${config}/sec.conf" 
     
    classpath=${ourHomeDir}/classes/tunnel.jar 
    dCapKerberosPort=${portBase}126 
    dCapSslPort=${portBase}128 
    
  3. Create a ${config}/sec.conf file:
     
    com.sun.security.jgss.accept 	{ 
        com.sun.security.auth.module.Krb5LoginModule required 
        doNotPrompt=true 
        principal="host/your.door@YOUR.REALM" 
        useKeyTab=true 
        debug=false 
        keyTab="${/}etc${/}krb5.keytab" 
        storeKey=true; 
    }; 
    
  4. Create a kerberos5 entry for the door. Due to the tunnel client code implementation, the entry has to be created for the FQDN of the interface. Due to a JAVA limitation (?) the entry may only use the des-cbc-crc key type. You need a keytab file with host principal installed on the door node. The following commands have to be invoked under K5 admin account to produce correct host principal( example for Heimdal K5 ):
         $ kadmin
         kadmin> add -r  host/<FQDN of K5 door host>
         kadmin> del_enctype host/<FQDN of K5 door host> des-cbc-md4
         kadmin> del_enctype host/<FQDN of K5 door host> des-cbc-md5
         kadmin> del_enctype host/<FQDN of K5 door host> des3-cbc-sha1
         kadmin> exit
         $ ktutil --keytab=/tmp/<FQDN of K5 door host>  get <FQDN of K5 door host>
         $ ktutil --keytab=/tmp/<FQDN of K5 door host> remove -e des-cbc-md4
         $ ktutil --keytab=/tmp/<FQDN of K5 door host> remove -e des-cbc-md5
         $ ktutil --keytab=/tmp/<FQDN of K5 door host> remove -e des3-cbc-sha1
         $ scp /tmp/<FQDN of K5 door host> root@<FQDN of K5 door host>:/etc/krb5.keytab
         $ rm /tmp/<FQDN of K5 door host>
         
  5. Add entries for GSS and/or SSL doors into the door.batch file.
      	      
    create dmg.cells.services.login.LoginManager DCap-k5 \ 
        "${dCapKerberosPort} \ 
        diskCacheV111.doors.DCapDoor \ 
        -prot=telnet -localOk \ 
        -maxLogin=1500 \ 
        -authorization=required \ 
        -usermap=pam  \ 
        -socketfactory=javatunnel.TunnelServerSocketCreator,javatunnel.GssTunnel,host/your.door@YOUR.REALM" 
    # 
    #  	      
    create 	dmg.cells.services.login.LoginManager DCap-ssl \ 
        "${dCapSslPort} \ 
        diskCacheV111.doors.DCapDoor \ 
        -prot=raw -localOk \ 
        -maxLogin=1500 \ 
        -authorization=required \ 
        -usermap=pam  \ 
        -socketfactory=javatunnel.SSLServerSocketCreator,<java keystore file>,<passphrase>" 
    
  6. To enable GSI authentification, first of all you need to put a host key and host certificate files into /etc/grid-security/ directory and trusted certificates into /etc/grid-security/certificates/directory. Add a new entry into door.batch file:
    #
    #
    #
    create dmg.cells.services.login.LoginManager DCap-gsi \
                "${dCapGsiPort} \
                 diskCacheV111.doors.DCapDoor \
                 -prot=telnet -localOk \
                 -maxLogin=1500 \
                 -brokerUpdateTime=120 \
                 -protocolFamily=dcap \
                 -authorization=strong \
                 -usermap=gsi-pam \
                 -socketfactory=javatunnel.TunnelServerSocketCreator,javatunnel.GsiTunnel,dummy"
    
    In addition to it You need a grid-mapping file - correspondence between Grid user certificate and local account. It's done through dcache.kpwd file. Add into door.batch file ( or any other batch file with used by your local setup ) following lines:
    #
    create diskCacheV111.admin.PAMAuthentificator gsi-pam \
            " -users=class:diskCacheV111.admin.UserMetaDataProviderFnal  \
             -kpwd-file=${ourHomeDir}/config/dcache.kpwd"
    
    Be sure, that dCapGsiPort defined in dCacheSetup file.
  7. To enable host based authentification modify your door.batch file as following:
    #
    #
    #
    create dmg.cells.services.login.LoginManager DCap-netrole \
                 "${dCapNetRolePort} \
                  diskCacheV111.doors.DCapDoor \
                  -prot=telnet -localOk \
                  -maxLogin=1500 \
                  -loginBroker=LoginBroker \
                  -brokerUpdateTime=120 \
                  -protocolFamily=dcap \
                  -authorization=strong \
                  -usermap=netrole-map \
                  -socketfactory=javatunnel.NetRolesServerSocketCreator,dummy,dummy" 
    
    Be sure, that dCapNetRolePort defined in dCacheSetup file.

    In addition you need to start a new net-role authentificator:

    #
    create diskCacheV111.admin.PAMAuthentificator netrole-map \
            " -users=class:diskCacheV111.admin.UserMetaDataProviderFnal  \
             -kpwd-file=${ourHomeDir}/config/dcache-netrole.kpwd"
    
    Add entry for your trusted host:
    mapping "127.0.0.1" tigran
                                                                                                                     
    login tigran 3750 1000 / /pnfs/desy.de/data/tigran /pnfs/desy.de/data/tigran
     127.0.0.1
    
    Note, that it's a host to user mapping. This mechanism can be userd on secure networks only, for example for writing data from dedicated hosts with url-like syntax.
If the authentication fails, the nobody account is used.

The examples above assume that the pam cell is able to deliver sufficient user information (uid,gid,homedir) so that the door can check the pnfs acls against these values. See The PAMAuthentificator manual pages for details. We are using the PAMAuthentificator cell just for convenience to do the user meta data lookup. I agree that the name of the cell (in this context) is slightly misleading. In the context of kerberos, the entity which is authenticated is not exactly the username but the principle. At desy, we have a one to one relation between principles and users, so that the LoginManager simply strips off the domain part and sends the remainding value to the user meta data cell. This might not be the case everywhere. Therefore the DCap door leaves the authenticated principle unchanged if the option -keepPrinciple is given on the startup command line of the DCapDoor. One should keep in mind that a full principle can not be resolved by the standard PAMAuthentificator. The reason is that neither the /etc/password file nor the NIS service will resolve full principle names into uid,gids. To achive this, the PAMAuthentificator may load customized classes to resolve arbitrary entities into the uid,gid pairs.


$Id: tunnel-HOWTO.html,v 1.7 2004/10/06 08:33:01 tigran Exp $