Table of Contents
The system on which you install the GridShib CA needs the following software installed:
Apache HTTP Server (Tested with 2.0.54). You need to have HTTPS/SSL configured on the server (the best documentation for this seems to be the file README.QUICKSTART.SSL which should be included with your server.)
Shibboleth SP software (Tested with 1.3)
Perl (Version 5.8.5 or later should work, early versions might.)
OpenSSL Both the binary and the development libraries and header files. Version 0.9.7 or later.
You need to configure Shibboleth so that you have a Shibboleth protected cgi-bin directory into which you will subsequently install the GridShib-CA cgi-bin scripts. You can find the directions for installing and configuring Shibboleth on the Shibboleth wiki.
For the purposes of these installation directions it is assumed that the URL for the Shibboleth-protected cgi-bin directory is /cgi-bin/shib-protected/, if not adjust accordingly.
The source code for the GridShib-CA is available from: http://gridshib.globus.org/downloads/gridshib-ca-0-4-0.tar.gz
These directions assume you are installing GridShib-CA with version 0.4.0. If not replace all instances of 0.4.0 with the version you are actually installing.
Unpack the gridshib-ca tarball and cd into the resulting directory.
% tar xfz gridshib-ca-0-4-0.tar.gz % cd gridshib-ca-0.4.0
Run "configure". configure takes a number of arguments, which can be viewed by running "configure --help". Assuming you are using the default paths configure should handle most of the work for you, the only help you may need to give it would be to specify the following:
--with-gridshib-ca-conf-dir=<path>
The GridShib-CA configuration files, PERL modules, basically everything that is not served by directly by Apache is stored in this directory (which should not be accessible by HTTP). The default location is /tmp/gridshib-ca/, but this can be overridden using this configure option.
--with-www-user=<username>
If the username that your Apache HTTPD runs under is something other than "apache" you need to tell configure this with '-with-www-user'
--with-www-dir=<path>
If your Apache root directory is not "/var/www/" then you need to tell configure this with '--with-www-dir'.
Run "make"
% make
It's a good idea to run the tests at this point to verify things look good at this point. This should exit without errors:
% make test
As root, run "make install"
# make install
These directions assume you are using the OpenSSL-based CA that comes with the GridShib-CA, which is the easiest route. You can also use MyProxy as a backend CA for the GridShib-CA.
To install the OpenSSL-based CA, you need to install the CA certificate and private key for the GridShib CA. Running the script utils/create-openssl-ca.pl will generate these automatically for you, creating a CA based on some defaults or the options you provided to configure.
Now got to Testing
The GridShib-CA has several configuration files that control its behavior. These files are all found in the gridshib-ca-conf-dir as provided to configure.
gridshib-ca.conf: General configuration
authorizedIdps.conf: List of Shibboleth IdPs trusted by the GridShib-CA
authorizedPortals.conf: List of Portals authorized to receive delegations from the GridShib-CA
The GridShib-CA uses the file /tmp/gridshib-ca//gridshib-ca.conf to control a number of configuration options, including:
What PERL modules are used to accomplish tasks, allowing deployment modification of behavior;
Syslog options to control how the GridShib-CA logs;
Locations of files including the CA certificate, private key;
Where issued certificates are stored.
By default the values in the file should work without modification. The file is commented and self-documenting, so all the options are not described here. The general form of the file looks like the following:
###################################################################### # # Configuration files # # GridShib CA configuration directory GridShibCAConfDir = /usr/local/gridshib-ca-0.2.1-test # JNLP file template JNLPTemplate = $(GridShibCAConfDir)/CredentialRetriever.jnlp # Symetric key file for tokens TokenKeyFile = $(GridShibCAConfDir)/token-key
A pound character (#) indicates a comment. Everything from the # to the end of the line is ignored.
A string such a $(var) is replaced with the variable as defined elsewhere in the file. Recursion is allowed to a depth of 24.
This file controls which Shibboleth identity providers are trusted by the GridShib-CA and how DNs are formed for their users. A user must have an identity asserted by an Idp specified as trusted by this file in order to use the GridShib-CA.
The configuration installed by default will trust any IdP in InQueue.
The file has the general form as the following example:
# Any idp in InQueue. Use the IdP id as the OU component and ePPN as the CN
urn:mace:inqueue:* "cn=${REMOTE_USER}, ou=${HTTP_SHIB_IDENTITY_PROVIDER}"
Each line of the file lists an Idp or set of Idps using a wildcard. An asterix (*) matches any characters, allowing for sets of Idps to be specified on a single line. Following the Idp name is whitespace, and following that is the double-quote delimited name policy. The name policy corresponds to the user-specific portion of the user's DN (i.e. everything but the relative DN used by the CA for all certificates) in RFC 2253 format. This policy may contain references to Shibboleth-specified environment variables formatted as ${variable-name}. The exact variables you can use depend on your Shibboleth configuration (AAP.xml to be precise). Some common, default variables are:
The user's eduPersonPrincipal name
The user's Shibboleth identity provider's identity
A pound (#) indicates a comment - all text from a pound to the end of a line is ignored.
The script check-config.pl should be run after changing gridshib-ca.conf to check for errors in the file.
Starting with version 0.3.0, if so configured, the GridShib-CA allows for the delegation of credentials directly to other portals. This file controls which portals are trusted to receive delegations.
The configuration installed by default will only trust portals on the same system as the GridShib-CA.
The file has the general form as the following example:
# Any url on the local hsot https://myhost.somedomain.edu/*
Each line of the file lists a URL or set of URLs using a wildcard. An asterix (*) matches any characters, allowing for sets of URLs to be specified on a single line. A pound (#) indicates a comment - all text from a pound to the end of a line is ignored.
Here are some steps to test your GridShib-CA installation. Note that it's normal to get some browser warnings/questions about trusting certificates, both for web sites and Java Web Start applications, as you go through the process.
From your build directory, run the post-install tests. You'll need to do this as root or the user under which Apache runs, so that the tests can read all the appropriate. This should go through the process of issuing a certificate and test everything but your Shibboleth configuration. Note that this will actually issue a certificate from your CA, outputting the certificate and generated private key to standard out.
# make test-post-install
Fire up your favorite browser and point it at https://hostname/gridshib-ca-0.4.0 replacing hostname with the name of the host on which you installed the GridShib-CA. Be sure to use 'https'. If this didn't work then something is fundamentally broken. Each Apache isn't installed right or a 404 error indicates your installation didn't put the files in the right place and you need to go review the configure options, the most likely culprit being --with-www-dir.
Click on the link entitled "make sure you have the system properly configured".
This should bring up a page that checks to see if you have Java Web Start installed.
If that looks ok, then click on the "Check Prerequisites" button. This should launch a Java Web Start application on your local machine. If that looks good, then you should be ready to move on. Otherwise you have some issue with either Java Web Start not functioning or a basic installation problem.
Click "OK" to close the test application.
Now click on "Return to GridShib CA" at the bottom of the page.
Now go for it and click on "Shibboleth logon to generate Grid credentials".
At this point, assuming your Shibboleth SP is correctly configured, you should be set either to a WAYF site to select your home institution or directly to a Shibboleth IdP. If this doesn't work, your Shibboleth configuration is incorrect and you need to work on that. If you don't have Shibboleth Idp you can use, register at OpenIdp.
You should now see a welcome message and the DN that you will receive. Click "Press here to generate and download Grid credential."
A Java Web Start application should now launch and download your grid credential. Once is successfully completes, click "OK" to close it.
On the command line, you should now be able to see your grid credential by running grid-proxy-info. For example:
% grid-proxy-info subject : /C=US/O=NCSA-TEST/OU=User/CN=vwelch@openidp.org issuer : /C=US/O=NCSA-TEST/OU=GridShib/CN=SP-CA identity : /C=US/O=NCSA-TEST/OU=User/CN=vwelch@openidp.org type : end entity credential strength : 1024 bits path : /tmp/x509up_u501 timeleft : 11:58:12
If you got this far you are good to go.
Problems with the GridShib-CA can be tricky to diagnosis because they could be Apache, Shibboleth or GridShib-CA problems. The first step is to figure out with which of these components the problem lies. Checking the following logs is a good way to do that:
Check your system logs (e.g. /var/log/messages) for messages. The GridShib-CA scripts will log errors here.
Check your apache ssl_error_logs (e.g. /var/log/http/ssl_error_logs) for messages. Errors encountered by Apache will be logged here.
Check your Shibboleth logs. Check log4j.appender.shibd_log.fileName in /etc/shibboleth/shid.logger for the location of this log.