Integrating an Identity Provider

Default Authentication Provider with Custom Subject Provider

[ Authentication Service:  Developers Guide  | caGrid: Documentation Guides ]

Overview

This guide provides step by step details on how to integrate a Identity Provider using the Authentication Service 1.3.  This approach should be used in the case where your Identity Provider is not capable of issuing SAML Assertions and is not supported by the Common Security Module (CSM).

Authentication Service Installation and Base Configuration

	Contents 1.1 Prerequisites 1.2 Step 1: Install caGrid/Authentication Service 1.3 Installer Prerequisites 1.4 Installing caGrid 1.3 Using the Installer 1.5 Step 2: Obtain Host Credentials 1.6 Step 3: Configure a Secure Container 1.7 Step 4: Edit Service Metadata

Prerequisites

In order to install and run the Credential Delegation Service (CDS), the following prerequisite software must be installed:

• Java 1.5 JDK or Greater

Step 1: Install caGrid/Authentication Service

In this step you will download and install the Authentication Service using the caGrid Installer. If you already have caGrid 1.3 installed on your machine you may proceed to the next step. To install caGrid/Authentication Service, complete the following steps:

Installer Prerequisites

The caGrid Installer installs all prerequisites except for Java and MySQL.

• Java 1.5 JDK
• (Optional) If you are deploying caGrid core services locally, you may also need a MySQL database.

  Note MySQL is only required for the security services and GME. You can use 4.x (with transaction enabled; i.e., use InnoDB engine) or 5.x.

• Make sure the JAVA_HOME environment variable is set and points to the correct location.

Installing caGrid 1.3 Using the Installer

Internet Resources Required by the Installer Unless you are using a customized installer, the installer will need to be able to access these internet resources: ftp://ftp1.nci.nih.gov to get its uncustomized configuration. http://gforge.nci.nih.gov to download caGrid and Globus http://archive.apache.org to download ant and tomcat (if you create a tomcat container) http://downloads.sourceforge.net to download JBoss if you create a JBoss container.

1. Download the caGrid 1.3 Installer, unless you have a customized installer that you have been instructed to use for your grid. The downloaded installer should be contained in the file caGrid-installer-1.3.zip. If you are using a customized installer the name may vary.
   
   
2. Unzip the file caGrid-installer-1.3.zip. This creates the directory caGrid-installer-1.3. This documentation refers to this directory as CAGRID_INSTALLER_LOCATION.
   
   
3. From a command prompt, launch the installer using the following command:
   

    > cd <CAGRID_INSTALLER_LOCATION>
   
   > java -jar caGrid-installer-1.3.jar 

4. Select the I agree to this license checkbox and then click  Next.
5. Select the Install/Configure caGrid Software checkbox and then click  Next.
6. The installer detects whether or not you have already installed Ant. It installs or reinstalls it, depending on your installation status. In either case, you must specify the location where you want to install Ant.
   
   
7. The installer detects whether or not you have already installed Globus. It installs or reinstalls it, depending on your installation status. In either case, you must specify the location where you want to install Globus.
   
   
8. The installer asks you for a location on your local file system to install caGrid. Specify a location to install caGrid and click  Next.

   To select a file location that is not in the User's Home directory, Click the Look In: drop down list and select a new starting location.
9. The installer displays a list of tasks that the installer will perform. Click  Next to begin the installation process. At this time the installer downloads, builds, and installs several components. This process takes several minutes.
10. Once the installer has completed installing all the components, click  Next.
11. The installer prompts you to specify which Grid you want to configure your installation to use. The installer supports configuring caGrid to work out of the box with many community Grid environments. For testing and development purposes, we recommend selecting the Training Grid. If you do not want to configure caGrid to work with an existing Grid you may select that as well. The installer can also be modified to support additional Grids.
12. The installer shows a summary of the tasks to be completed. Click  Next to configure caGrid to use the selected target Grids. This process takes several minutes.
13. Once the installer has finished configuring caGrid to use the target Grid, click  Next. The final screen reminds you to set your ANT_HOME and GLOBUS_LOCATION environment variables. Set these variables immediately and click Finish.

Congratulations! You have successfully installed caGrid.

Add ANT_HOME/bin to PATH You will be running the ant program from the command line so add ANT_HOME/bin to PATH.

The installer will install caGrid to the directory you specified during installation. From this point forward we will refer to this directory as CAGRID_HOME. The Authentication Service can be found in the directory CAGRID_HOME/projects/authentication-service, from this point forward we will refer to this directory as AUTHENTICATION_SERVICE_HOME. The GAARDS UI or graphical user interface for authenticating with the Authentication Service, is located in CAGRID_HOME/projects/gaardsui, from this point forward we will refer to this directory as GAARDS_UI_HOME.

Step 2: Obtain Host Credentials

The Authentication Service runs as a secure service. In order to run a secure service, the container hosting the service must run with a host credential. A host credential consist of a X.509 certificate and private key. In production environment it is very important that this credential be issued by a certificate authority that your environment trusts.  For the purposes of this guide we will provide instructions on how to obtain a host credential from Dorian. Dorian is an open source service framework for issuing PKI credentials and is a trusted certificate authority in many Grid environments. Most target Grids (selected in the last step) are configured with one or more Dorian instances. For the purposes of this guide we will provide documentation on requesting a host credential from the Training Dorian, similar steps can be used for requesting a host credential from other Dorian instances.

To request a host credential from the Training Dorian, you must have must have an account.  Any user may request an account from the Training Dorian.  If you have an account with the Training Dorian, please complete the steps below to get a host credential, other wise click here for directions on requesting an account and then proceed with the steps below: Launch the GAARDS UI Log onto the Grid. From the MyAccount menu, select Request a Host Certificate, this will launch the Request a Host Certificate window. From the Service drop down select the Dorian you wish to request a host certificate from. In the Host text box, enter the fully qualified name of the host you are requesting a host certificate for. Next you must specify the directory on the file system where the host credentials should be written to, this can be done by clicking the Browse button. Click the Request Certificate button.

Request Host Certificate

Immediately after clicking the Request Certificate button, the UI will submit the host certificate request to Dorian. Upon receiving the request Dorian will either immediately approve the request or submit the request to administrator for approval. In the case where the request is immediately approved, the host credentials (certificate and private key) will be written to the directory specified. The file containing the certificate will be named THE_HOSTNAME_YOU_ENTERED-cert.pem, the file containing the private key will be named THE_HOSTNAME_YOU_ENTERED-key.pem.

In the case where host certificate request requires approval of an administrator, the file containing the private key will be named THE_HOSTNAME_YOU_ENTERED-key.pem. The host certificate WILL NOT be written since it is not issued until the request is approved.  You will need to wait for an administrator to approve your request before proceeding forward.  The GAARDS UI provide a means of checking the status of your request, for directions on how to do this click here.

Note the location where that the host certificate and private key were written. You will need these later to configure your container.

Step 3: Configure a Secure Container

In this step we will configure a web service container that will host the Authentication Service.   The Authentication Service can be deployed to the Tomcat, JBoss, and Globus containers.  For the purposes of this guide we will provide detailed 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.

Have a Copy of the .cagrid/certificates Directory Make sure that you have a copy of the $HOME/.cagrid/certificates directory. There is a bug in the installer that can sometimes corrupt the files in this directory. After you are finished performing the following steps, check the contents of the $HOME/.cagrid/certificates directory. If the files in this directory have a zero length, they are corrupted. In this case, copy the files from the copy of the $HOME/.cagrid/certificates directory into the directory.

1. From a command prompt, launch the caGrid Installer:
   

    > cd <CAGRID_INSTALLER_LOCATION> 
    > java -jar caGrid-installer-1.3.jar 

2. Select the I agree to this license checkbox and then click Next.
3. Select the Install/Configure Grid Service Container checkbox and then click Next.
4. Select the Container you to which you want to deploy your service. This guide will use Tomcat. Select the Should this container be secure? checkbox and then click Next.
5. In the hostname checkbox, enter the hostname of your server. This should match the hostname you used when you created your host credentials. Click Next.

   If you plan on using this container to deploy a service that registers to an existing grid, it is important that you use a publicly resolvable DNS name (or static IP). Otherwise, you will need to edit configuration files manually later to correct this.

6. From the Obtain host credentials method list, select the option that applies to your situation and click Next.

   Options: If you do not yet have credentials for your service, then select Use GAARDS to obtain host credentials. If you have host credentials that are not in the default location, then select Browse to host credential on the file system If you have host credentials that are in the default location, then select Host credentials are already installed Note: Use of the Copy in host credentials manually option is not recommended. Use the Browse to host credential on the file system option instead. Default credential location: On Windows, this will be a path like "C:\Documents and Settings\<USERNAME>\.cagrid\certificates". On Linux/MAC this will be a path like "/Users/YOUR_USERNAME/.cagrid/certificates".
7. Enter the location of your host certificate into the Certificate text checkbox. Enter the location of your private key into Key text checkbox. Click Next. Note: after this step, verify that your host certificate and private key files exist. Verify that the size of these files is greater than zero. If the filesize is zero for either file, restore it from a backup copy.
8. The next screen asks where you want to install Tomcat. Enter that location in the Directory text checkbox and click Next.

   Avoid Blanks in the Container Path Do not choose a name or path for the container that contains any blanks. In particular, in a Windows environment, do not put the container under directories such as "Documents and Settings" or "My Documents".

9. A list of tasks appears that the installer will perform to install and configure Tomcat. Click Next.
10. Once the installer has completed installing all the components, click Next.
11. Click Next. The final screen reminds you to set your ANT_HOME, GLOBUS_LOCATION and CATALINA_HOME environment variables. Set these variables immediately and click Finish.
    Congratulations! You have successfully installed and configured your Tomcat container.

Step 4: Edit Service Metadata

The Authentication Service 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:

1. Open the Authentication Service metadata file, AUTHENTICATION_SERVICE_HOME/etc/serviceMetadata.xml.
2. In the hostingResearchCenter element near the bottom of the file, do the following.
   1. Supply your ResearchCenter infomation.
   2. Supply your Address. This is the address that is used when mapping your service on the caGrid Portal.
   3. Supply the PointOfContact. This is the person responsible for maintaining the service.
      A completed example:

      <ns1:hostingResearchCenter>
        <ns53:ResearchCenter displayName="Ohio State University" shortName="OSU" xmlns:ns53="gme://caGrid.caBIG/1.0/gov.nih.nci.cagrid.metadata.common">
         <ns53:Address country="US" locality="Columbus" postalCode="43210" stateProvince="OH" street1="3190 Graves Hall" street2="333 W. 10th Ave."/>
         <ns53:pointOfContactCollection>
          <ns53:PointOfContact affiliation="OSU" email="John.Doe@osumc.edu" firstName="John" lastName="Doe" phoneNumber="(555) 555-5555" role="Maintainer"/>
         </ns53:pointOfContactCollection>
        </ns53:ResearchCenter>
       </ns1:hostingResearchCenter>
      

      Note By default, the Authentication Service registers with and publishes its service metadata to the Index Service. The default Index Service is configured as the Index Service of the target grid you selected when you installed the Authentication Service. You can find configuration details on registering and publishing to the Index Service, including disabling registration and changing which Index Service to register with, on the Registration and Discovery page.

Step 5: Implement the Subject Provider Interface

The SubjectProvider defines a java interface for authenticating users with an identity provider and for returning user attributes describing information about the user and how the user authenticated.  The interface is defined in the class:

org.cagrid.gaards.authentication.service.SubjectProvider

The interface requires the implementation of two methods: (1) getSubject() and (2) getSupportedAuthenticationProfiles().  The getSubject() method takes a credential (org.cagrid.gaards.authentication.Credential) as input and returns a Subject (javax.security.auth.Subject).   The credential should be used to authenticate the user with their organization's identity provider.    Upon successfully authenticating the user, the SubjectProvider should create and return a Subject object.  The Subject object should contain the following principles, each representing an attribute describing the user:

1. gov.nih.nci.security.authentication.principal.LoginIdPrincipal - The user's unique user id within their organization's identity provider.
2. gov.nih.nci.security.authentication.principal.FirstNamePrincipal - The user's first name.
3. gov.nih.nci.security.authentication.principal.LastNamePrincipal - The user's last name.
4. gov.nih.nci.security.authentication.principal.EmailIdPrincipal - The user's email address.

The getSupportedAuthenticationProfiles() method specifies the type of credentials that the SubjectProvider accepts as a valid means of authentication.     This method does not require an input however returns a set (java.util.Set) of valid QName(s) (javax.xml.namespace.QName).  Each QName corresponds to the XML schema definition for the credential.

Below is an example implementation of a Subject Provider that will authenticate a user as long as:

1. There provide a User Id and Password credential.
2. The password they provide is password.

The SubjectProvider below will return a Subject with the userId provided and the same first name, last name, and email address for each user. (Keep in mind this is just an example)

package org.cagrid.gaards.authentication.test;

import gov.nih.nci.security.authentication.principal.EmailIdPrincipal;
import gov.nih.nci.security.authentication.principal.FirstNamePrincipal;
import gov.nih.nci.security.authentication.principal.LastNamePrincipal;
import gov.nih.nci.security.authentication.principal.LoginIdPrincipal;

import java.security.Principal;
import java.util.HashSet;
import java.util.Set;

import javax.security.auth.Subject;
import javax.xml.namespace.QName;

import org.cagrid.gaards.authentication.BasicAuthentication;
import org.cagrid.gaards.authentication.Credential;
import org.cagrid.gaards.authentication.common.AuthenticationProfile;
import org.cagrid.gaards.authentication.common.InvalidCredentialException;
import org.cagrid.gaards.authentication.service.SubjectProvider;


public class ExampleSubjectProvider implements SubjectProvider {

    private Set<QName> profiles;


    public ExampleSubjectProvider() {
        this.profiles = new HashSet<QName>();
        this.profiles.add(AuthenticationProfile.BASIC_AUTHENTICATION);
    }


    public Subject getSubject(Credential credential) throws InvalidCredentialException {
        if (credential instanceof BasicAuthentication) {
            BasicAuthentication c = (BasicAuthentication) credential;
            if (c.getPassword().equals("password")) {
                String userId = c.getUserId();
                Set<Principal> principals = new HashSet<Principal>();
                principals.add(new LoginIdPrincipal(userId));
                principals.add(new FirstNamePrincipal("John"));
                principals.add(new LastNamePrincipal("Doe"));
                principals.add(new EmailIdPrincipal("jdoe@example.com"));
                Subject subject = new Subject(true, principals, new HashSet(), new HashSet());
                return subject;
            } else {
                throw new InvalidCredentialException("Invalid password specified!!!");
            }
        } else {
            throw new InvalidCredentialException("Invalid credential specified!!!");
        }

    }


    public Set<QName> getSupportedAuthenticationProfiles() {
        return profiles;
    }

}

Step 6: Package and Distribute the SubjectProvider

Once you have completed your implementation of the SubjectProvider interface, build it and create a jar file containing your implementation and any other implementation files required. Place the jar file containing your implementation and any jar files your implementation depends on into AUTHENTICATION_SERVICE_HOME/lib.

Step 7: Configure the Authentication Service

The Authentication Service leverages the Spring Frameworkfor configuration.  The use of the Spring Framework provides provides the Authentication Service alot of flexibility in being able to replace components such as the AuthenticationProvider and the SubjectProvider.  The Authentication Service configuration file is contained in the file AUTHENTICATION_SERVICE_HOME/etc/authentication-config.xml, this file contains the Spring Beans for the configurable components of the Authentication Service. For this approach we must configure the Authentication Service to use the Subject Provider you just implemented.  This can be done by changing the class attribute of the subjectProvider bean to be the classname of your implementation.

The second configuration file the Authentication Services uses is the Authentication Service properties file, which is contained in the file AUTHENTICATION_SERVICE_HOME/etc/authentication.properties.  The Authentication Service properties file contains commonly edited properties for configuring the Authentication Service.  Below we have provided a list of properties that must be edited for this approach:

gaards.authentication.saml.cert

The full path to the file containing the certificate that corresponds to the private key that should be used for signing the SAML Assertions.  It is required that the certificate be in PEM format.  If you dont have a specific certificate for issuing assertions, you may user the host certificate you created earlier.

gaards.authentication.saml.key

The full path to the file containing the private key that should be used for signing the SAML Assertions.  It is required that the private key be in PEM format.  If you dont have a specific private key for issuing assertions, you may user the host private key you created earlier.

gaards.authentication.saml.key.password

The password (if one exists) used for encrypting/decrypting the private key. If you are using the private key you created earlier, leave this blank as that private key was not encrypted.

Step 8: Build the Authentication Service

To build the Authentication Service, please type the following at the command line:

 > cd AUTHENTICATION_SERVICE_HOME
 > ant clean all 

Step 9: Deploy and Start the Authentication Service

At this point we have completed configuring the Authentication Service and the Tomcat container the Authentication Service will run in.  We are now ready to deploy the Authentication Service to the Secure Tomcat Container.  This can be done as follows from a command prompt:

 >cd AUTHENTICATION_SERVICE_HOME
 > ant deployTomcat 

 > cd AUTHENTICATION_SERVICE_HOME
 > ant deployJBoss 

 > cd AUTHENTICATION_SERVICE_HOME
 > ant deployGlobus 

Once you deployed the Authentication Service, please start your container. Please make sure that there is outside connectivity to your Authentication Service through your firewall.

Step 10: Register Your Identity Provider with the Training Dorian

To allow users with accounts on your Identity Provider to use their credentials to access the Grid you must register your Authentication Service/Identity Provider with Dorian such that Dorian will trust your identity provider and issue grid credentials to your users.  Registering your Identity Provider with Dorian requires the following information:

1. Certificate - The certificate (PEM Format) that corresponds to the private key that is used by your Authentication Service for signing SAML Assertions.
2. Authentication Service URL - The service URL for your Authentication Service.
3. Authentication Service Identity - The grid identity of your Authentication Service, if you are not sure what this is, please provide your host certificate (this may be the same certificate used for SAML Assertions).

Please send the above information to knowledge@osu-citih.org, you should be contacted within 1-2 business days.  Once you have received confirmation that your identity provider has been registered with Dorian, pleaes proceed to the next step.

Step 11: Test Logging onto the Training Grid

Once you Identity Provider has been registered with Dorian, we are ready to validate that your Authentication Service/Identity Provider is operating properly. Before doing so make sure your Authentication Service is running and that is available outside of your firewall. To validate that you Authentication Service is operating properly, please complete the following: Type the following from a command prompt: $ cd GAARDS_UI_HOME $ ant ui Click the Login button, this will bring up a Login screen. From the Credential Provider drop down select Training. From the Organization drop down select your Organization. In the User Id text box enter your user id for the account assigned to you by your organization In the Password text box enter the password for this account. Click the Authenticate button.

Login Window Successful Login

After clicking the Authenticate button you will be logged onto Dorian using the credentials issued by your organization. If the login is successful a dialog will be displayed informing you that you have succesfully logged on.

Congratulations you have successfully integrated your Identity Provider into the Grid!!!