NCSA CyberSecurity

Author:	Terry Fleury (tfleury@ncsa.uiuc.edu)
Last Update:	October 3, 2006

Introduction

Steps for using MyProxy for single sign-on are shown in the following diagram.

1. Client A wants to authenticate a Username using a given Password. It sends U/P to the MyProxy Server.
2. MyProxy uses various mechanisms to see if U/P authenticates. For example, it can check any locally stored credentials for matching U/P, or it can authenticate to external sources via a Pluggable Authentication Module (PAM) or Simple Authentication and Security Layer (SASL).
3. If successfully authenticated, the MyProxy Server returns a new Credential.
4. Client A generates a new random (Session) Password (P') which will be used the next time a process wants to authenticate the Username. Note that while the client generates the password, the MyProxy server can enforce policies with respect to that password, e.g. minimum string length.
5. Client A stores the Credential on the MyProxy Server under U/P'. The client specifies the lifetime of this credential, which is then the lifetime of the Session Password. The MyProxy server may impose limits on this lifetime.

Much of the information on this page is taken from other sources. References are given where appropriate. The intent of this page is to put all of the information in a single location with specific instructions for configuring MyProxy to create session passwords. When MyProxy is configured in this manner, it should be used exclusively for this purpose.

Installation Overview

Installation and configuration of the MyProxy server for use with sessions passwords consists of the following high-level steps, most of which will need to be done as the root user:

1. Install the NTP time synchronization system and development packages.
2. Build and install the MyProxy-specific version of the Globus Toolkit, version 4.0.3.
3. Install the latest version of the MyProxy server.
4. Configure MyProxy to act as a certificate authority with SimpleCA.
5. Create a host certificate for your server.
6. Install a MyProxy PAM for external user authentication.
7. Install and configure the myprxoy-server.config file.
8. Install the files related to the configuration file.
9. Set up an init.d file to have MyProxy start automatically.
10. Test your setup.

Installation and Configuration Details

1. Install NTP (the network time protocol daemon), chkconfig (for setting the runlevels for ntpd), and initscripts (for the service command to turn on and off ntpd). (Additional instructions can be found on the Linux Home Networking website.) With Fedora Core, you can use the "yum" command to install the software and any dependencies.

   yum -y install ntp chkconfig initscripts
   

   Once NTP is installed you may need to change the time servers your machine talks to. To do this, edit the files /etc/ntp/ntpservers and /etc/ntp/step-tickers. Once you have added your particular time servers, you can set NTP to start automatically at boot, and also start up NTP now with the following commands.

   /sbin/chkconfig ntpd on  
   /sbin/service ntpd start
   

   Depending on your operating system, you may also need to download the development packages for several programs, in particular MySQL, OpenSSL, and PAM. The development packages are separate from the "standard" packages and can be installed manually as follows.

   yum -y install mysql-devel openssl-devel pam-devel
   

2. Download and install Globus Toolkit 4.0.3. (Additional instructions can be found on the Globus website.) For Fedora Core 4, you may need to first install a C++ compiler. You can use the "yum" command as follows.

   yum -y install gcc-c++
   

   Next, download Globus Toolkit 4.0.3. Let's download the file to the /tmp directory. Then untar the tarball. The commands to do this are as follows.

   cd /tmp
   wget http://www-unix.globus.org/ftppub/gt4/4.0/4.0.3/installers/src/gt4.0.3-all-source-installer.tar.bz2
   tar xvjf gt4.0.3-all-source-installer.tar.bz2
   

   Create the destination directory for the compiled Globus Toolkit. This can be anywhere you typically install third-party software. Let's use the /usr/local directory tree. Also, set up the GLOBUS_LOCATION environment variable required for installation and execution of the Globus Toolkit commands.

   mkdir -p /usr/local/globus-4.0.3 
   export GLOBUS_LOCATION=/usr/local/globus-4.0.3
   

   At this time, you may also want to put this environment variable in your /etc/profile so that it gets set whenever a user logs in. Near the bottom of the /etc/profile file, add the following two lines.

   export GLOBUS_LOCATION=/usr/local/globus-4.0.3 
   export PATH=$PATH:$GLOBUS_LOCATION/bin
   

   Now build and install the MyProxy-specific portions of the Globus Toolkit. (Additional instructions can be found on the Globus website.) In the directory where you untarred the source tarball (in the above case /tmp/gt4.0.3-all-source.installer), compile and install as follows.

   cd /tmp/gt4.0.3-all-source-installer
   ./configure --prefix=$GLOBUS_LOCATION  
   make gsi-myproxy  
   make install
   

3. Install MyProxy v3.7. Globus Toolkit 4.0.3 comes with MyProxy 3.6 which, for the most part, is suitable for the creation of session passwords. However, it lacks the server configuration option to prevent the storage of a user's credential under a username other than his own. This configuration option was added in version 3.7. Installing a newer version of MyProxy isn't too difficult, but you must first UNinstall the MyProxy 3.6 which was installed with Globus Toolkit 4.0.3. (Additional instructions can be found on the MyProxy website.) First, find out which "flavors" of the Globus Toolkit you have installed as follows.

   $GLOBUS_LOCATION/sbin/gpt-query globus_gssapi_gsi
           2 packages were found in /usr/local/globus-4.0.3 that matched your query:
   
           packages found that matched your query 
                   globus_gssapi_gsi-gcc32dbg-dev pkg version: 4.9.0
                   globus_gssapi_gsi-gcc32dbg-rtl pkg version: 4.9.0
   

   In this case, the installed "flavor" is "gcc32dbg". Note this for a later step. Next, uninstall the current version of MyProxy as follows.

   $GLOBUS_LOCATION/sbin/gpt-uninstall myproxy
   

   Now download the newer MyProxy tarball to the /tmp directory and install it as follows:

   cd /tmp
   wget ftp://ftp.ncsa.uiuc.edu/aces/myproxy/myproxy-3.7.tar.gz
   $GLOBUS_LOCATION/sbin/gpt-build -force -verbose myproxy-3.7.tar.gz gcc32dbg
   

   You may have to replace the "gcc32dbg" in that last command to match the "flavor" you found earlier.
4. Configure MyProxy to act as a certificate authority (CA). This allows MyProxy to issue credentials to users who are properly authenticated using an alternate method (such as PAM). A package called SimpleCA is included in the Globus Toolkit installed earlier. (Additional instructions can be found on the MyProxy website and on the Globus Toolkit website.) Run the "setup-simple-ca" script as follows. Entries that you need to make are indicated in red italic. (Note that the values presented here are specific to the MAEviz project. You should enter values that apply to your project.)

   $GLOBUS_LOCATION/setup/globus/setup-simple-ca
   
   WARNING: GPT_LOCATION not set, assuming:
            GPT_LOCATION=/usr/local/globus-4.0.3
   
       C e r t i f i c a t e    A u t h o r i t y    S e t u p
   
   This script will setup a Certificate Authority for signing Globus
   users certificates.  It will also generate a simple CA package
   that can be distributed to the users of the CA.
   
   The CA information about the certificates it distributes will
   be kept in:
   
   /root/.globus/simpleCA/
   
   The unique subject name for this CA is:
   
   cn=Globus Simple CA, ou=simpleCA-yourserver.com, ou=GlobusTest, o=Grid
   
   Do you want to keep this as the CA subject (y/n) [y]:n
   
   Enter a unique subject name for this CA:CN=MAEviz Simple CA, C=US, O=myproxyserver, OU=MAEviz
   
   Enter the email of the CA (this is the email where certificate
   requests will be sent to be signed by the CA):maeviz@ncsa.uiuc.edu
   
   The CA certificate has an expiration date. Keep in mind that 
   once the CA certificate has expired, all the certificates 
   signed by that CA become invalid.  A CA should regenerate 
   the CA certificate and start re-issuing ca-setup packages 
   before the actual CA certificate expires.  This can be done 
   by re-running this setup script.  Enter the number of DAYS 
   the CA certificate should last before it expires.
   [default: 5 years (1825 days)]:(hit <ENTER> to accept default)
   
   Enter PEM pass phrase:(enter password, not echoed)
   Verifying - Enter PEM pass phrase:(enter password, not echoed)
   
   creating CA config package...done.
   
   A self-signed certificate has been generated 
   for the Certificate Authority with the subject: 
   
   /C=US/O=myproxyserver/OU=MAEviz/CN=MAEviz Simple CA
   
   If this is invalid, rerun this script 
   
   /usr/local/globus-4.0.3/setup/globus/setup-simple-ca
   
   and enter the appropriate fields.
   
   -------------------------------------------------------------------
   
   The private key of the CA is stored in /root/.globus/simpleCA//private/cakey.pem
   The public CA certificate is stored in /root/.globus/simpleCA//cacert.pem
   
   The distribution package built for this CA is stored in
   
   /root/.globus/simpleCA//globus_simple_ca_84c59fba_setup-0.19.tar.gz
   
   This file must be distributed to any host wishing to request
   certificates from this CA.
   
   CA setup complete.
   
   The following commands will now be run to setup the security
   configuration files for this CA:
   
   $GLOBUS_LOCATION/sbin/gpt-build /root/.globus/simpleCA//globus_simple_ca_84c59fba_setup-0.19.tar.gz
   
   $GLOBUS_LOCATION/sbin/gpt-postinstall
   -------------------------------------------------------------------
   
   setup-ssl-utils: Configuring ssl-utils package
   Running setup-ssl-utils-sh-scripts...
   
   ***************************************************************************
   
   Note: To complete setup of the GSI software you need to run the
   following script as root to configure your security configuration
   directory:
   
   /usr/local/globus-4.0.3/setup/globus_simple_ca_84c59fba_setup/setup-gsi
   
   For further information on using the setup-gsi script, use the -help
   option.  The -default option sets this security configuration to be 
   the default, and -nonroot can be used on systems where root access is 
   not available.
   
   ***************************************************************************
   
   setup-ssl-utils: Complete
   

   The most important entry during this process is the "unique subject name for this CA". In this case the entry is "CN=MAEviz Simple CA, C=US, O=myproxyserver, OU=MAEviz". Notice that "CN=MAEviz Simple CA" appears first in the list even though the CN (Common Name) would typically appear last. SimpleCA will reorder the fields appropriately so that the CN field correctly appears last, but if you put it last on the entry line, SimpleCA will fail.

   Finally, complete the SimpleCA setup by running "setup-gsi" as indicated by the previous command.

   $GLOBUS_LOCATION/setup/globus_simple_ca_84c59fba_setup/setup-gsi -default
   

   In this command, replace the "84c59fba" part of the command with the 8-character hash string you saw in the previous step when setting up SimpleCA. It will be different for each server on which you configure SimpleCA.
5. Create a host certificate for your server based on the SimpleCA you set up in the previous step. (Additional instructions can be found on the Globus Toolkit website.) First, you generate a host certificate "request" as follows.

   grid-cert-request -host 'hostname'
   

   Here, give the FQDN (fully qualified domain name) of your host as the 'hostname' field in the above command. The files "hostkey.pem" and "hostcert_request.pem" will be created in the directory "/etc/grid-security". You now need to "sign" the request in this directory as follows.

   cd /etc/grid-security
   grid-ca-sign -in hostcert_request.pem -out hostcert.pem
   

   When you are prompted for a passphrase, use the one you used when creating the SimpleCA.
6. Install an external authentication method via PAM (Pluggable Authentication Modules). As a CA, MyProxy needs to have some way to authenticate a user with an external authority. MyProxy can use PAM for this purpose to connect to an external Kerberos, LDAP, or MySQL database. (Additional instructions can be found on the MyProxy website.)

   As an example, we will use pam_mysql to connect to a Sakai user database. Sakai stores user password in a non-standard way, so you will need to download and compile a special version of pam_mysql. We will rename this new version so that it can coexist with any currently installed version of pam_mysql. Use the following commands to download, compile, and install this special version of the pam_mysql software.

   cd /tmp
   wget http://security.ncsa.uiuc.edu/research/wssec/gsihttps/pam_mysql_sakai.tar.gz
   tar xvzf pam_mysql_sakai.tar.gz
   cd pam_mysql_sakai
   ./configure --with-openssl
   make
   cp .libs/pam_mysql.so /lib/security/pam_mysql_sakai.so
   

   Now we need to configure MyProxy to actually use this new pam_mysql_sakai module when authenticating users. This is done by creating the file "/etc/pam.d/myproxy". Edit this file and add the following lines. (Entries marked in red italic are those you will need to change to suit your particular server.)

   #%PAM-1.0
   auth    required pam_mysql_sakai.so \ 
           user=dbuser passwd=dbpasswd host=sakai.server.host.com db=sakaidb \
           table=SAKAI_USER usercolumn=USER_ID passwdcolumn=PW statcolumn=0 \
           crypt=b64md5
   account required pam_mysql_sakai.so \
           user=dbuser passwd=dbpasswd host=sakai.server.host.com db=sakaidb \
           table=SAKAI_USER usercolumn=USER_ID passwdcolumn=PW statcolumn=0 \
           crypt=b64md5
   

   This configures the MyProxy server to talk to the Sakai user database on sakai.server.host.com. Since this is a MySQL database, we need to configure MySQL on sakai.server.host.com to allow connections from our MyProxy server. You will need MySQL root access on the server hosting the Sakai user database to execute the following commands. (As before, entries marked in red italic must be changed to suit your particular setup.)

   mysql --user=root --password=mysqlrootpassword
   mysql> GRANT SELECT ON sakaidb.* TO 'dbuser'@'myproxy.server.host.com' IDENTIFIED BY 'dbpasswd';
       Query OK, 0 rows affected (0.16 sec)
   mysql> \q
   

7. Install and modify the myproxy-server.config file to allow for the creation of "session passwords". There is a basic configuration file provided in the MyProxy installation. You simply need to copy it to the appropriate location and edit it for a "session password" setup.

   cp $GLOBUS_LOCATION/share/myproxy/myproxy-server.config /etc/
   chmod 600 /etc/myproxy-server.config
   

   Now, edit the /etc/myproxy-server.config file and uncomment/modify the following line entries. You will have to scroll through the entire file to find them all. (Note that you need to set the "simpleCApasswd" passphrase appropriately.)

   accepted_credentials       "*"
   authorized_retrievers      "*"
   default_retrievers         "*"
   authorized_renewers        "*"
   default_renewers           "none"
   authorized_key_retrievers  "*"
   default_key_retrievers     "none"
   trusted_retrievers         "*"
   default_trusted_retrievers "none"
   pam "sufficient"
   certificate_issuer_cert /root/.globus/simpleCA/cacert.pem
   certificate_issuer_key /root/.globus/simpleCA/private/cakey.pem
   certificate_issuer_key_passphrase "simpleCApasswd"
   certificate_serialfile /root/.globus/simpleCA/serial
   certificate_mapapp /etc/grid-security/mapper.sh
   accepted_credentials_mapapp /etc/grid-security/accepter.sh
   check_multiple_credentials true
   

8. Install files referenced by the myproxy-server.config file. There were two shell scripts referenced in the myproxy-server.config file which you need to create and install. The first script is "/etc/grid-security/mapper.sh". It takes in a username and returns a subject DN (Distinguished Name) for that username. It exits with 0 (zero) status upon success and 1 (one) upon failure. Here is an example mapper.sh file which you can modify for your site's configuration.

   #!/bin/sh
   username=$1
   if [ X"$username" = X ]; then
       # no username given
       exit 1
   fi
   echo "/C=US/O=myproxyserver/OU=MAEviz/CN=${username}"
   exit 0
   

   The second script is "/etc/grid-security/accepter.sh". It takes in a subject DN and a username and exits with 0 (zero) status if a credential with the given subject DN should be allowed to be stored under the given username. It exits with 1 (one) status otherwise. Here is an example accepter.sh file which you can modify for your site's configuration.

   #!/bin/sh
   if [ $# -ne 2 ]; then
       # need 2 command line arguments
       exit 1
   fi
   subjectdn=$1
   username=$2
   if [ "${subjectdn}" != "/C=US/O=myproxyserver/OU=MAEviz/CN=${username}" ]; then
       # invalid mapping of subjectDN and username
       exit 1
   fi
   exit 0
   

   Now you need to give these two shell scripts the appropriate execution permissions as follows.

   chmod 755 /etc/grid-security/mapper.sh /etc/grid-security/accepter.sh
   

9. Set up an init.d file to start MyProxy automatically at boot time. Assuming your system uses the /etc/init.d/ style of program startup at boot time, you can simply copy the init.d style file to the appropriate directory and modify the value of $GLOBUS_LOCATION in the file to point to your actual installation directory. Here are the commands:

   cp $GLOBUS_LOCATION/share/myproxy/etc.init.d.myproxy /etc/init.d/myproxy
   chmod 755 /etc/init.d/myproxy
   chkconfig --add myproxy
   

   Now edit /etc/init.d/myproxy, look for the line with the GLOBUS_LOCATION environment variable, and set it appropriately:

   GLOBUS_LOCATION="/usr/local/globus-4.0.3"
   

   Finally, you can start up MyProxy!

   service myproxy start
   

10. Test your setup. You can test your configuration by running a client on the same machine as the MyProxy server, but to make sure everything is working remotely, you should test from a separate client machine. There are two ways to do this: (a) using MyProxy command line tools and (b) using a Java test application. Both methods require that the client is configured with the server's root certifcate.

    When you configured MyProxy to use SimpleCA, you created a root certificate for your server. This root certificate consists of two files.

    /etc/grid-security/certificates/84c59fba.0
    /etc/grid-security/certificates/84c59fba.signing_policy
    

    Note that the 84c59fba is an 8 character hex string and will be different for your server. Copy these two files to every client machine that will be contacting the MyProxy server for user authentication. Copy them to your home directory in the "~/.globus/certificates/" directory (or "%HOMEPATH%\.globus\certificates\" in MS-Windows). Commands for *nix would look like this.

    mkdir -p ~/.globus/certificates
    cp 84c59fba.* ~/.globus/certificates/
    

    In MS-Windows, you will need to start a "command prompt" window (e.g. Start->Run..., type cmd, and then <Enter>) and then type the following commands.

    mkdir %HOMEPATH%\.globus\certificates
    copy 84c59fba.* %HOMEPATH%\.globus\certificates\
    

    If you are going to use the Java application on *nix to test your setup, you will also need to copy these root certificate files to your "/etc/grid-security/certificates/" directory as root.

    mkdir -p /etc/grid-security/certificates
    cp 84c59fba.* /etc/grid-security/certificates/
    

    In order to test your setup using MyProxy command line tools, you will need to install the MyProxy-specific version of the Globus Toolkit v4.0.3. You can do this as you did before on the server. You will NOT need to upgrade MyProxy to v3.7, however. Once you have MyProxy installed on the client machine, execute the following commands. (As before, entries marked in red italic must be changed to suit your particular setup.)

    myproxy-logon -s myproxy.server.host.com -l sakaiusername -o cred1
          Enter MyProxy pass phrase: (enter sakaipassword, not echoed)
          A credential has been received for user sakaiusername in cred1.
    
    myproxy-init -s myproxy.server.host.com -l sakaiusername -C cred1 -y cred1 -c 0 -a -k cred1
          Your identity: /C=US/O=myproxyserver/OU=MAEviz/CN=sakaiusername
          Creating proxy ......................................................... Done
          Proxy Verify OK
          Your proxy is valid until: Sat Sep 30 01:54:23 2006
          Enter MyProxy pass phrase:(enter (NEW)SessionPassword, not echoed)
          Verifying - Enter MyProxy pass phrase:(re-enter SessionPassword, not echoed)
          A proxy valid for 11 hours (0.5 days) for user sakaiusername now exists on myproxy.server.host.com.
    
    myproxy-logon -s myproxy.server.host.com -l sakaiusername -o cred2
          Enter MyProxy pass phrase: (enter SessionPassword, not echoed)
          A credential has been received for user sakaiusername in cred2.
    
    

    So what is going on here? The first myproxy-logon command contacts the MyProxy server with the Sakai username and saves a new credential for that user in the file "cred1". You can view the contents of this credential with the following command.

    openssl x509 -noout -text -in cred1
    

    This new "cred1" was created by the MyProxy server using its SimpleCA functionality. MyProxy contacted the Sakai user database using the pam_mysql module, got successful authentication, and then returned a new credential on-the-fly.

    The next myproxy-init command puts this cred1 credential BACK to the MyProxy server under the same username but a NEW "session password" that you made up. You also had to specify a credential name ("cred1" in this case using the "-k" option, but it could be anything). We won't care about the credential name in the future because MyProxy has been configured to check all stored credentials for a matching password.

    Finally, the last myproxy-logon command uses the NEW "session password" that you just created to fetch another credential and store it in the file "cred2". You will notice that this new credential is different from the first credential. In fact, the new credential is a proxy credential based on the first credential. You could then put this second credential back to the MyProxy server under a different credential name using another "session password". Future authentication attempts with either password would return a new credential.

    An alternative way of checking your MyProxy server setup is using a Java client program. For this, you will need Sun's Java installed (version 1.4.2 or higher) as well as a few JARs. Download the following files.

    • SSOUtils.java Java utility code
    • Globus Toolkit 4 Java WS Core Binary Installer
    • Apache Jakarta Commons Lang Library
    Untar the two tarballs to any directory you want. You will be using several JAR libraries in your CLASSPATH so you only need read access. Let's assume you untarred them to the /tmp directory. The full commands would look something like this.

    cd /tmp
    wget http://security.ncsa.uiuc.edu/research/wssec/gsihttps/SSOUtils.java
    wget http://www-unix.globus.org/ftppub/gt4/4.0/4.0.3/ws-core/bin/ws-core-4.0.3-bin.tar.gz
    wget http://apache.oregonstate.edu/jakarta/commons/lang/binaries/commons-lang-2.1.tar.gz
    tar xvzf ws-core-4.0.3-bin.tar.gz
    tar xvzf commons-lang-2.1.tar.gz
    mkdir -p edu/uiuc/ncsa/myproxy
    mv SSOUtils.java edu/uiuc/ncsa/myproxy/
    export CLASSPATH=.:\
    /tmp/ws-core-4.0.3/lib/cog-jglobus.jar:\
    /tmp/ws-core-4.0.3/lib/log4j-1.2.8.jar:\
    /tmp/ws-core-4.0.3/lib/cryptix32.jar:\
    /tmp/ws-core-4.0.3/lib/cryptix-asn1.jar:\
    /tmp/ws-core-4.0.3/lib/puretls.jar:\
    /tmp/ws-core-4.0.3/lib/jce-jdk13-125.jar:\
    /tmp/commons-lang-2.1/commons-lang-2.1.jar
    javac edu/uiuc/ncsa/myproxy/SSOUtils.java
    

    After all that, you should have a newly compiled class file in "/tmp/edu/uiuc/ncsa/myproxy/SSOUtils.class". You can now run the test application as follows. (As before, entries marked in red italic must be changed to suit your particular setup.)

    java edu.uiuc.ncsa.myproxy.SSOUtils sakaiusername sakaipassword myproxy.server.host.com
    

    You should see plenty of "Succeeded!" messages if everything is configured correctly. The Java code is doing basically the same thing as the MyProxy command line tool commands shown before.

    The SSOUtils.java file also contains several utility methods that you can use in your own Java code. Look at the comments in the file for more information. Basically you should use "createSessionPassword" to take in a username/password and return a NEW "session password", and "authenticateUser" to take in a username/password and return an "authentication OK" value. Note that both methods can take either the user's original Sakai password or a newly created "session password". Once a session password has been created, it will remain valid until it expires (default value is 4 hours). So you can create multiple session passwords for any given username.

    Can't connect? Check your firewall settings:

    • Is the MySQL port (default 3306) open on the Sakai User Database server?
    • Is the MyProxy port (default 7512) open on the MyProxy server?