----
h1. GTS Installation Guide
----
{include:Documentation Navigation}
{cagridroundpanel}
{pre:class=cagridheaderfont}Contents{pre}
{toc:outline=true|exclude=GTS Installation Guide|style=none}
{cagridroundpanel}This guide explains how to install and configure the Grid Trust Service (GTS) version 1.3.
\\

h2. Step 1: Install caGrid/GTS

In this step you download and install the GTS using the caGrid Installer. If you have already installed caGrid 1.3, proceed to the next step.

{include:caGrid13:Install caGrid Using the caGrid 1.3 Installer}\* The installer installs caGrid to the directory you specified during installation. From this point on we refer to this directory as *{_}CAGRID_HOME{_}*.
\\
* You can find the GTS in the directory _CAGRID_HOME/projects/gts_; from this point on we refer to this directory as *{_}GTS{_}{*}{*}_\_HOME{_}*.

* The GAARDS UI (user interface) for administrating the GTS is located in _CAGRID_HOME/projects/gaardsui_; from this point on we refer to this directory as *{_}GAARDS_UI_HOME{_}*.

h2. Step 2: Bootstrap the Trust Fabric

Deployments that leverage the GTS to maintain the trust fabric are effectively delegating their authentication responsibility to the GTS. Therefore it is imperative the GTS instance(s) can be trusted. In order for the GTS to be trusted it must run securely with a host credential (X.509 certificate and private key). It is critical that this host credential be issued by an authority that all parties in the deployment trust.  This certificate authority will be the trust anchor of the entire trust fabric and will be the certificate authority that all parties trust in order to bootstrap the entire trust fabric.  It is *{_}EXTREMELY IMPORTANT{_}* that this certificate authority be highly secured, if it were to be compromised parties trusting it could be convinced to trust certificate authorities that would not otherwise be trusted.

Although it is not required we recommend that you use a separate certificate authority for issuing host credentials to GTS instance(s).  For the purposes of this guide we will create a certificate authority that we will use for issuing credentials to GTS instances.  To create a certificate authority please complete the following steps from a command line:

# Type {{{*}cd GTS_HOME{*}}}.
# Type {{{*}ant generateCA{*}}}.
# Enter the distinguished name (DN) for the CA (i.e O=caGrid,OU=GTS Example,OU=Trust Fabric,CN=Trust Fabric CA).
# Enter the number of days that the CA will be valid for (i.e 3650).
# Enter a password which will be used to encrypt the CA's private key. {note}The password should be 13 characters long. {note}
# Enter a file to write the CA private key to.
# Enter a file to write the CA certificate to.

Sample output from executing the above steps is shown below:

{noformat}ant generateCA
Buildfile: build.xml

setGlobus:

checkGlobus:
[echo] Globus: /Users/langella/ext/ws-core-4.0.3

defineClasspaths:

defineExtendedClasspaths:

init:

checkValidate:

preInit:

configure:
[copy] Copying 1 file to /Users/langella/releases/caGrid-1.3/projects/gts

postInit: generateCA:
[input] Please enter the DN for the new CA (ex. O=osu,OU=bmi,CN=Some CA):
O=caGrid,OU=GTS Example,OU=Trust Fabric,CN=GTS Example Trust Fabric CA
[input] Please enter the number of days the new CA will be valid for:
3650
[input] Please enter a password for the new CA:
test
[input] Please enter a location to write the new CA's private key:
/Users/langella/certificates/gts-example/trustca-key.pem
[input] Please enter a location to write the new CA's certificate:
/Users/langella/certificates/gts-example/trustca-cert.pem
[java] Successfully created the CA certificate:
[java] O=caGrid,OU=GTS Example,OU=Trust Fabric,CN=GTS Example Trust Fabric CA
[java] CA certificate valid till:
[java] Thu Feb 14 15:06:56 EST 2019 \[java\] CA private key written to:
[java] /Users/langella/certificates/gts-example/trustca-key.pem
[java] CA certificate written to:
[java] /Users/langella/certificates/gts-example/trustca-cert.pem

BUILD SUCCESSFUL
Total time: 1 minute 44 seconds
{noformat}
{tip}Be sure to note down the location that your CA certificate and private key were written to, from this point forward we will refer to thesse locations as *{_}TRUST_CA_CERTIFICATE{_}* and *{_}TRUST_CA_KEY{_}* respectively.  Also be sure to note down that password you entered for your private key.  Finally be sure to take note of the distiguished name or subject you entered for your CA, from this point forward we will refer to this as the *CA_SUBJECT*.
{tip}Now that we have created a trust fabric certificate authority we can use it to issue host credentials for GTS instances. To create host credentials please complete the following steps from a command prompt(illustrated below):
\\
\\
# Type {{{*}cd GTS_HOME{*}}}.
# Type {{{*}ant createAndSignHostCertificate{*}}}.
# Enter the location of the CA's private key (TRUST_CA_KEY).
# Enter the password used to encrypt the CA's private key.
# Enter the location of the CA's certificate (TRUST_CA_CERTIFICATE).
# Enter the name of the host.
{note}Use of the fully qualified hostname is highly recommended. {note}
# Enter the number of days that the host credentials should be valid for.
{note}The number of days entered must allow the host certificate to expire before the CA's certificate. {note}
# Enter a location to which to write the host private key.
# Enter a location to which to write the host certificate.

Sample output from executing the above steps is shown below:


{noformat}$ ant createAndSignHostCertificate
Buildfile: build.xml
setGlobus:
checkGlobus:
[echo] Globus: /Users/langella/ext/ws-core-4.0.3
defineClasspaths:
defineExtendedClasspaths:
init: checkValidate:
preInit:
configure:
[copy] Copying 1 file to /Users/langella/releases/caGrid-1.3/projects/gts
postInit:
createAndSignHostCertificate:
[input] Please enter the location of the CA's private key:
/Users/langella/certificates/gts-example/trustca-key.pem
[input] Please enter the CA's password: test
[input] Please enter the location of the CA's certificate: /Users/langella/certificates/gts-example/trustca-cert.pem
[input] Please enter the Hostname [llanowar]: [llanowar]
llanowar
[input] Please enter the number of days the host certificate will be valid for:
1000
[input]Please enter a location to write the host key:
/Users/langella/certificates/gts-example/llanowar-key.pem
[input] Please enter a location to write the host certificate:
/Users/langella/certificates/gts-example/llanowar-cert.prm
[java]
Successfully created the host certificate:
[java] O=caGrid,OU=GTS Example,OU=Trust Fabric,CN=host/llanowar
[java] Host certificate issued by:
[java] O=caGrid,OU=GTS Example,OU=Trust Fabric,CN=GTS Example Trust Fabric CA
[java] Host certificate valid till: [java] Sun Nov 13 15:42:32 EST 2011
[java] Host private key written to:
[java] /Users/langella/certificates/gts-example/llanowar-key.pem
[java] Host certificate written to:
[java] /Users/langella/certificates/gts-example/llanowar-cert.prm BUILD SUCCESSFUL Total time: 1 minute 44 seconds
{noformat}
{tip}Note down the location to which the host certificate and private key were written. You will need these later to configure your container.
{tip}
h2. Step 3: Configure the Container

In this step we will configure a web service container that will host the GTS.  The GTS can be deployed to the Tomcat, JBoss, and Globus containers. This guide includes instructions on how to use the caGrid Installer to install and configure a secure Tomcat container. You will need to supply the installer with the host credentials you created in the last step.

{include:caGrid13:Configuring Secure Tomcat}
h2. Step 4: Configure Globus to Trust the GTS

In order for the GTS to be used to distribute trust certificate authorities we MUST configure Globus to trust the CA that issued the GTS's host certificate. To do this we place a copy of the certificate authority certificate (_TRUST_CA_CERTIFICATE_) in the Globus trusted certificates directory.

In most installations the Globus trusted certificate directory is usually _USER_HOME/.globus/certificates_. Globus requires all CA certificates in its trusted certificates directory to be in PEM format and to have a digit extension (0-9). For example, if the CA certificate is stored in the file cacert.pem we would configure Globus to trust this certificate authority by copying to the directory _USER_HOME/.globus/certificates_ (create directory if needed) with the file name cacert.0

# Locate the CA certificate file that you created in Step 2
# Copy the file into the *{_}USER_HOME/.globus/certificates{_}* directory as *cacert.0*
## Unix Location: usually /home/<username>/.globus/certificates
## Windows: usually C:\Documents and Settings\<username>\.globus\certificates
## Mac: usually /Users/<username>/.globus/certificates


h2. Step 5: Configure SyncGTS to Ignore the GTS CA

If you *{_}DID NOT{_}* select a Target Grid when installing the GTS, proceed to the next step. If you selected a *{_}Target Grid{_}* when you installed the GTS, the installer installs a plugin called [SyncGTS|SyncGTS] that will configure Dorian/Globus to ONLY accept credentials from credential providers that the target grid you selected trusts. This means that when the container is started it will not trust the GTS CA that we told it to trust in the last step. To fix this we will edit SyncGTS's configuration so that it will trust the host credentials of the GTS we are instantiating. This is a temporary solution to get things up and running for testing purposes. In a production environment, your SyncGTS should be configured to sync with your GTS instance(s).

To edit SyncGTS's configuration so that Dorian/Globus will trust the Dorian being installed and the credential providers trusted in the target grid, edit the file as follows.

# Open the sync-description.xml file for editing
\\
*_$CATALINA_HOME/webapps/wsrf/WEB-INF/etc/cagrid_SyncGTS/sync-description.xml{_}*
\\
\\
# Locate the *gtsServiceURI* element (Shown Below):
{code}<ns1:gtsServiceURI>https://slavegts.training.cagrid.org:8443/wsrf/services/cagrid/GTS</ns1:gtsServiceURI>{code}Set to the URI for the master GTS. The master GTS URI is the correct value for both master and slave GTS instances.
\\
\\
# Locate the *GTSIdentity* element (Shown Below):
{code}<ns1:GTSIdentity>/O=caBIG/OU=caGrid/OU=Training Trust Fabric/CN=host/slavegts.training.cagrid.org</ns1:GTSIdentity>{code}Set this to the grid identity of the host that runs the master GTS service in this element.
{tip}If you don't know the grid identity of the master GTS service's host, you can get it by logging onto the host and using a program provided by globus the the identity from the host's host certificate. If {{HOST_CERT}} is the name of the host certificate file, issue the command
\\
$GLOBUS_LOCATION/bin/grid-cert-info \-file HOST_CERT
\\
The output from this command will look like this
{code}subject : O=akuGrid,OU=GTS,OU=Trust Fabric,CN=host/mastergts.aku.edu issuer : O=akuGrid,OU=GTS,OU=Trust Fabric,CN=Trust Fabric CA start date : Tue Sep 21 23:56:50 GMT+05:00 2010 end date : Thu Aug 20 00:01:50 GMT+05:00 2020
{code}The subject field contains the information you need in a slightly different form than it is needed in the *gtsServiceURI* element. The subject field separates sub-fields with a comma ",". The identity in the *gtsServiceURI* element introduces each sub-field with a forward slash "/". {tip}\\
\\
# Locate the *ExcludedCAs* element (Shown Below):
{code:XML}<ns1:ExcludedCAs> <ns1:CASubject>O=caBIG,OU=caGrid,OU=Training Trust Fabric,CN=caGrid Training Trust Fabric CA</ns1:CASubject></ns1:ExcludedCAs>{code}Add an additional child element *{_}CASubject{_}* containing the distinguished name or subject that you entered when you create the certificate authority _(earlier noted as CA_SUBJECT)_.
{code:XML}<ns1:ExcludedCAs> <ns1:CASubject>O=caBIG,OU=caGrid,OU=Training Trust Fabric,CN=caGrid Training Trust Fabric CA</ns1:CASubject> <ns1:CASubject>O=caGrid,OU=GTS Example,OU=Trust Fabric,CN=Trust Fabric CA</ns1:CASubject></ns1:ExcludedCAs>
{code}

h2. Step 6: Edit Service Properties of SyncGTS

Edit syncGTS service.properties of the *deployed* SyncGTS as follows to bypass the first run of SyncGTS after starting your container.
# Open the *SyncGTS jndi-config.xml* in your editor.
## *_$CATALINA_HOME/webapps/wsrf/WEB-INF/etc/cagrid_SyncGTS/jndi-config.xml{_}*
# Find the *performFirstSync* setting.
# Replace the "true" value with "*false*".
# The final configuration should look like this:
{code}parameter> <name>performFirstSync</name> <value>false</value> </parameter>
{code}

h2. Step 7: Configure the GTS

The GTS is configured through a configuration file which is located at GTS_HOME/etc/gts-conf.xml(shown below). The GTS uses a Mysql Database as its backend data store; you must provide the GTS with the connection details for your Mysql database.

{include:GTS Configuration File}\|\| Configuration File Element \|\| Purpose \|\|
\\
\| *gts-internal-id* \| Specifies the name of the GTS database that will be created \|
| *sync-authorities* | Specifies how often the GTS should sync with its authorities |
| *driver* | The Standard MySQL driver |
| *urlPrefix* | Standard MySQL URL Prefix |
| *host* | Database hostname |
| *port* | Database port |
| *username* | Username of user with *database creation privileges* |
| *paassword* | Database user password |
| *pool* | Database connection pool size |

# Open the GTS configuration file to edit the commonly changed values.
#* *{_}GTS_HOME/etc/gts-conf.xml{_}*
# MySQL Database connection information:
## Replace *localhost* with the appropriate hostname if you are using a database on another server.
## Replace *port* if not using the standard MySQL port.
## Replace *username* with another user with *database creation privileges* if you choose not to use the root account.
## Provide the *password* for the username that you have provided.
# Save the file.

h2. Step 8: Edit the GTS Service Metadata

The GTS provides service metadata to clients and other services that describes information about the service, operations supported by the service, and information on the organization hosting the service.

Edit the service metadata to reflect your organization as follows:
# Open the GTS service metatada file, *{_}GTS_HOME/etc/serviceMetadata.xml{_}*.
# In the *{_}hostingResearchCenter{_}* element near the bottom of the file, do the following.
## Supply your *ResearchCenter* infomation.
## Supply your *Address*. This is the address that is used when mapping your service on the caGrid Portal.

# Edit the *GTS deploy.properties* file to bypass Index Service registration as follows:
## Open the *GTS_HOME/deploy.properties* file.
## Locate the *index.service.url* entry and replace the current URL with the URL of your Index Service.
## Locate the *perform.index.service.registration* entry and temporarily set it to "false" to avoid communication errors caused by missing Index Service.

h2. Step 9: Add Initial Administrators

The GTS provides many operations for administrating the trust fabric; these operations are restricted to GTS administrators. GTS Administrators are _"super users"_ and can perform any operation on a GTS (i.e., manage certificate authorities, manage trust levels, manage permissions, etc). To bootstrap the GTS such that it may be administered through its service interface, we must provide the GTS with at least one initial administrator. The GTS provides a command line program for adding initial administrators. To use this program, type the following from a command prompt:

{terminal}$ cd GTS_HOME $ ant addAdmin
{terminal}You are prompted for the grid identity of the initial administrator to add. Enter that information as follows.

h2. Step 10: Deploy the GTS

At this point we have completed configuring the GTS and the container the GTS will run in.

From a command prompt, do the following if you want to deploy the GTS to the Secure Tomcat Container:
{terminal}>cd GTS_HOME\\ > ant deployTomcat {terminal}If you chose to use a JBoss container, deploy the GTS by typing the following at a command prompt:
{terminal}> cd GTS_HOME\\ > ant deployJBoss {terminal}Although the installer does not support configuring a secure Globus container, deploy the GTS to a secure Globus container by typing the following at the command prompt:
{terminal}> cd GTS_HOME\\ > ant deployGlobus {terminal}No matter which container you choose, you should see a significant amount of output to the screen. If the deployment is successful, the words *{_}BUILD SUCCESSFUL{_}* appear on the screen.
\\

h2. Step 11: Start GTS

# If you chose a Tomcat container, start Tomcat as follows:
\\
{terminal}$CATALINA_HOME/bin/startup.sh {terminal}
{info}Check the $CATALINA_HOME/logs/catalina.out file for any errors.
{info}
# If you chose a JBoss container, start JBoss as follows:
\\
## Windows:
\\
{terminal}$JBOSS_HOME\run.bat {terminal}
## Unix/Mac:
\\
{terminal}$JBOSS_HOME/run.sh {terminal}

h2. Step 12: Verify the Installation

Once you have deployed the GTS, you have completed the installation and configuration of the GTS. Next we will verify that the installation was successful. Before doing so we must start the GTS service. This is done by starting the container to which the GTS was deployed. To start a secure Tomcat container, run the startup script (startup.sh or startup.bat) located in _CATALINA_HOME/bin_. Check the Tomcat log files (*{_}CATALINA_HOME/log/catalina.out{_}*) to ensure that there are no error or stacktraces and that the container successfully started and bound to the port you specified during the installation. Once the container has started we are ready to verify that the GTS installation was successful. To accomplish this we use the GAARDS UI, which is a graphical user interface for administering security services such as the GTS. We will use the GAARDS UI to add the certificate authority we created to the trust fabric. To do this we must first configure the GAARDS UI to be able to communicate with the GTS we just instantiated. Complete the following steps:











{section}




\\






\\







\\



\\

{column}











# Type the following from a command prompt:
{noformat}$ cd GAARDS_UI_HOME $ ant ui
{noformat}
# Select *Window* > *Preferences*. The Preference window appears.
# From the preferences tree on the left side of the window, expand the *Trust Fabric* node and then click the *Grid Trust Service(s)* node. On the right side of the screen you should see a list of GTS Services.
# In the Display Name text field enter *{_}Localhost{_}*.
# In the Service URL field, enter *_[https://localhost:8443/wsrf/services/cagrid/GTS]_*, replacing the port (8443) with the port you configured during installion.
# Click *Add*.
# Click *Save*.

Login in as one of the initial administrators we created earlier.&nbsp; To accomplish this complete the following steps:
# Click *Login*. The Login window appears.
# From the Credential Provider list, select the Dorian that issued your administrators credential.
# From the Organization list, select the identity provider of the administrator.
# In the User Id box, enter the user ID of the administrator.
# In the Password box, enter the password of the administrator.
# Click *Authenticate*.

Create a [Level of Assurance|Levels of Assurance] to which to assign the trust fabric CA we create. Complete the following steps:
# Select *Trust Fabric* > *Levels of Assurance*. The Levels of Assurance window appears.
# From the Service list, select *{_}Localhost{_}*.
# Click *Add*. This opens the Add Level of Assurance window.
# In the Name box, enter *{_}Trust Fabric._*
# In the Description box, enter *{_}Level of Assurance for Trust Fabric CAs{_}*.
# Click *Add*. The level of assurance is added to the GTS. Note that is appears in the Levels of Assurance window.

Add the certificate authority we created earlier to the GTS as a trusted certificate authority. Complete the following steps:
# Select *Trust Fabric > Certificate Authorities*. The Certificate Authorities Window appears.
# From the Service drop down select *{_}Localhost{_}*.
# Click *Add*. The Add Certificate Authority Window appears.
# Select the *Certifcate* tab.
# Click *Import Certificate*. A file browser appears.
# Browse to the CA certificate you created earlier (*{_}TRUST_CA_CERTIFICATE{_}*) and click *Open*.&nbsp; This loads the certificate into the UI.
# Select the *Level of Assurance* tab.
# Select the *Trust Fabric* check box.
# Click *Add*. The certificate authority is added to the GTS as a trusted certificate authority.
# In the Certificate Authorities Window, click *Search*. Once the search completes, the certificate authority you just added appears in the table below the Search button.

{tip}Congratulations. You have succesfully installed the Grid Trust Service (GTS).
{tip}

{column}\\
\\






\\



\\

{column}











{gallery:page=GTS Preferences Screenshot|title=GTS Preferences}{gallery}
{gallery:page=gaardsui13:Login Screenshot|title=Login Window}{gallery}
{gallery:page=Add Level of Assurance Screenshot|title=Add Level of Assurance}{gallery}
{gallery:page=Levels of Assurance Screenshot|title=Levels of Assurance}{gallery}
{gallery:page=Add Certificate Authority Screenshot|title=Add Certificate Authority}{gallery}
{gallery:page=Trusted Certificate Authorities Screenshot|title=Certificate Authorities}{gallery}
{column}\\
\\
\\
\\
{section}