IdP Installer for Active Directory

The IdP Installer for Microsoft Active Directory, which was designed and implemented by Rod Widdowson of SDSS, is documented on the I2 Wiki at 

   https://spaces.internet2.edu/display/SHIB/IdPActiveDirectory

The following notes are intended to be read in conjunction with the I2 Wiki information. Please pass on any comments or suggestions for improvement to SDSS.

1. Changing the entityID

The section describes how to change the entityID which your IdP is known as.

Prerequisites

You need to have the IdP installed and working (you know this is happening when member@scope, where scope is of the form name.ac.uk, is being asserted for eduPersonScopedAffiliation).

Why would you want to do this?

Your entity may have a non-standard name, or you may have initially installed against one tree in your Active Directory forest (e.g. staff.coll.ed.ac) and you want to make the entity more general.

What to do

You have to edit C:\program files\internet2\etc\idp.xml and C:\program files\internet2\idp\metadata-segment.xml:

  1. In idp.xml there is an attribute to the top-level <IdPConfig/> element called “providerId”. Change it to your entityID value.

  2. In metadata-segment.xml there is an attribute to the top-level <md:EntityDescriptor/> element called “entityID”. Change it to your entityID value.

  3. Don’t forget to mirror the metadata-segment.xml change in TestShib (or any other federations with which you are associated).

  4. Stop and start Tomcat:
    sc stop tomcat5
    sc start tomcat5
  5. Retest to make sure that nothing has regressed.

2. Customizing the login screen

(i.e. fixing the screen you see after you fail to log in)

Prerequisites

You need to have the IdP installed and working (you know this is happening when member@scope is being asserted for eduPersonScopedAffiliation).

Why would you want to do this?

  1. By default the login screen is a generic Shibboleth branded screen.
  2. There is a bug in the installer which means that if login fails, by default you get a blank screen instead of an error page.

What to do

  1. Stop Tomcat:
    sc stop tomcat5
  2. Delete the old installed WARfile and unpacked contents:
    del "\Program Files\Internet2\CaptiveTomcat5.5\webapps\shibboleth-idp.war
    rd /s/q "\Program Files\Internet2\CaptiveTomcat5.5\webapps\shibboleth-idp
  3. Set up variables to allow the rebuild to take place:
    set JAVA_HOME=c:\Program Files\Internet2\CaptiveJava
  4. Go to the install folder:
    cd C:\Program Files\Internet2\IdPInstall
  5. Copy the login file to the login error file:
    copy webApplication\login.jsp webApplication\login-error.jsp
  6. Edit both these files as appropriate. You will need to use WordPad because of CR/LF issues. I cannot help you much with the JSP programming, but if you think HTML type thoughts it should be relatively easy.
  7. Do a build:
    ant
    Accept all the defaults.

    You may find that you get an error when running ant, in which case you will have to edit the file build.properties to set up values for “tomcat.password” and “tomcat.url”. These can be set to any values: they are not actually used during or after the installation.
  8. Start Tomcat:
    sc start tomcat5
  9. Test it. You will need to look at the Tomcat logs to debug any issues you have.

3. Declaring a CA-signed certificate to Tomcat and the IdP

The idea here is to create a new java keystore (jks file) which we will associate with the SSO (browser facing) port. In order to do this you need to use the “keytool” program, which is available at c:\program files\Internet2\captiveJava\bin\KeyTool.

The (somewhat turgid) documentation is here and in general this is well documented on the web. The following is based on the notes of some who did this for real, using the JANET Server Certificate Service.

Overview

There are four steps to creating a certificate chain in the key store:

  1. Create the keystore and a public & private key.
  2. Generate a signing request and get it signed by a Certfication Authority (CA); we used the JANET Server Certificate Service.
  3. Import root and intermediate certificates as required.
  4. Import a trusted signed certificate from your chosen CA.

Step by Step Guide

Notes:

  • Replace placeholders (italicised items in command lines) with your own values.
  • Remember to take backup copies of the files.
  • Although command lines may appear broken over more than one line below, in each case they should be typed as a single line.
  • The following notes are referenced in the commands below.
    1Replace inst_abbrev by an abbreviation for your institution’s name.
    2Choose your own password; use it consistently below.
    3Misleading: this will become the CN of the certificate. For example, shib.inst.ac.uk
    4The name of the relevant department.
  1. Generate Keystore & Public/Private keys:
    keytool -genkey -alias shib -keystore inst_abbrev.jks1
    Enter keystore password: ******2
     
    keytool -genkey -alias shib -keystore inst_abbrev.jks
    Enter keystore password: ******
     
    What is your first and last name?3
    [Unknown]: anystring.instscope
     
    What is the name of your organizational unit?4
    [Unknown]: DeptName
     
    What is the name of your organization?
    [Unknown]: InstName
     
    What is the name of your City or Locality?
    [Unknown]: CityName
     
    What is the name of your State or Province?
    [Unknown]: CountyName
     
    What is the two-letter country code for this unit?
    [Unknown]: GB
     
    Is CN=anystring.instscope, OU=DeptName, O=InstName, L=CityName, ST=CountyName, C=GB
    correct? [no]: y
  2. Generate signing request file.
    keytool -certreq -file shib-csr.txt -alias shib -keystore inst_abbrev.jks
    Enter keystore password: *****
     
    Send the shib-csr.txt file to your chosen CA.
    Wait until the CA returns a signed certificate file before continuing.
  3. Add root certificate to keystore:
    keytool -import -trustcacerts -alias root
      -file sureserversv.cer -keystore inst_abbrev.jks
    Enter keystore password: ******
     
    Add intermediate certificate(s) to keystore. The CA should be able to provide you with these (in particular the JANET SCS certificates do need the intermediates):
    keytool -import -trustcacerts -alias sureserveredu.cer
      -file sureserveredu.cer –keystore inst_abbrev.jks
    Enter keystore password: ******
  4. Add to keystore the CA signed certificate returned at step 2.
    keytool -import -alias shib
     -file anystring.instscope.pem -keystore inst_abbrev.jks
    Enter keystore password: ******
     
    Once you have the new keystore, you should edit the following file:
    c:\program files\Internet2\CaptiveTomcat5.5\Conf\Server.xml
     
    Change the <Connector> for port 8442. You need to change the keystoreFile and keystorePass values appropriately. Stop & restart Tomcat and test again.

4. Bugfix to idp.xml

The generated idp.xml has a typo in it towards the top:

AAUrl=”https://$IDP_ADDR:8443/shibboleth-idp/AA”

The DNS name of your IP (inst.ac.uk) should replace the ‘$IDP_ADDR’.

5. Registering the IdP with the UK Federation

This is described at http://www.ukfederation.org.uk/content/Documents/Registration

When you register you should mention that this is a QuickInstall-based IdP. You will be asked for the “AA Certificate name”, to which the response is “self-signed cert”, and you should also attach the certificate itself:

c:\program files\internet2\etc\idp.crt

not the idp.key file, which must remain confidential.

During registration, as part of the security checking, the federation operators will contact you and ask to verify the “certificate fingerprint”. You can get the fingerprint using keytool:

keytool –list –keystore c:\program files\internet2\etc\idp.jks

6. Security

Check that only system and admin have access to c:\program files\internet2.

7. Modifying a Quick Install IdP to authenticate using LDAP

By default the Quick Install IdP authenticates using Kerberos. This section describes how you might want to change this to using LDAP authentication.

Prerequisites

  1. You need to have the IdP installed and working (you know this is happening when member@scope is being asserted for eduPersonScopedAffiliation).

  2. You need to have configured the IdP to speak to LDAP (you know this is happening when eduPersonTargetedID (ePTID) is being asserted (but note that the default ARP in c:\program files\internet2\idp\etc\arps\arp.site.xml does not release ePTID).
    Here is an example of a testshib screen with ePTID highlighted (it is called ‘targeted-id’).

Why would you want to do this?

In the situation we ran into, the Active Directory was a forest with separate domains for staff and students. Using Kerberos meant that the user had to specify the domain when logging in rod@staff.coll.ac.uk or 37940@student.coll.ac.uk). This was considered cumbersome and, since the login names were unique across both domains, we decided to authenticate against the global catalogue of the forest using LDAP.

Preparing the installation

It is a good idea to get the installation working in all other aspect before starting this. In particular, you should get attribute resolution working.

Only a very small part of this job entails configuring Shibboleth – mostly we are configuring Tomcat.

  1. Download the latest version of the Virginia Tech LDAP authorization module as described at http://www.middleware.vt.edu/doku.php?id=middleware:opensource:ldap
    and place the downloaded jar file (it will be called something like vt-ldap-2.8.1.jar) into
    C:\program files\Internet2\CaptiveTomcat5.5\Server\Lib
  2. Modify the Tomcat’s <Realm>, in the file:
    C:\program files\Internet2\CaptiveTomcat5.5\Conf\Server.xml
    to read:
    <Realm
      className="org.apache.catalina.realm.JAASRealm”
      appName="Tomcat"
      userClassNames="edu.vt.middleware.ldap.jaas.LdapPrincipal"
      roleClassNames="edu.vt.middleware.ldap.jaas.LdapRole" />
  3. You now need to instruct JAAS to use the VT LDAP library and to give it a few parameters.You do this by editing the file: C:\program files\Internet2\CaptiveTomcat5.5\Conf\jaas.conf
     
    Here is the example we used:
    Tomcat {
      edu.vt.middleware.ldap.jaas.LdapLoginModule required
      host="gcserver.coll.ac.uk"
      base="DC=int,DC=coll,DC=ac,DC=uk"
      port="3268"
      serviceUser="username@coll.ac.uk"
      serviceCredential="password"
      userField="sAMAccountName"
      userRoleAttribute="objectClass"
      subtreeSearch="true";
    };
     
    Notes:
    • Host has to point to a root AD server, and one with the Global Catalogue
    • The port has to be 3280 (which is the Global Catalogue).
    • serviceUser and serviceCredential may not be required, so once you get going, try without them. If you supply them, use the same username & password that you used in resolver.xml.
    • userRoleAttribute is used to supply a role to JAAS, which Tomcat will then use to police which users can access the IdP (we’ll see how to do this below). In the example I used “objectClass”, so I could test in Tomcat against “user”. You might want to experiment with “memberOf” if you want finer granularity of control.
  4. We now need to set up Tomcat to listen to these new roles we have defined. To protect the root of the service (we’ll use this to test) edit this file:
    C:\Program Files\Internet2\CaptiveTomcat5.5\webapps\ROOT\WEB-INF\web.xml
     
    In two places you will see a line:
      <role-name>idpuser</role-name>
    In both places add another line:
      <role-name>user</role-name>
  5. Start and stop Tomcat and try to browse to:
    https:\\localhost:8442\
    You will be prompted for a BasicAuth username & password (a dialogue box will pop up). Enter the username and password from a user inside the forest. You should get to the Tomcat home page.
  6. We now need to declare these roles to the Shibboleth application. To do so make an edit similar to what you did in step 4 (defining the new <role-name> “user”) to the file:
    C:\Program Files\Internet2\IdPInstall\webAppConfig\dist.idp.tomcat2k3.xml
  7. Stop Tomcat and redeploy the war file. Carry out the latter by going to:
    C:\Program Files\Internet2\IdPInstall
    from a command line and typing “ant”, and accepting (<CR>) all the defaults. You may find that you get an error when running ant, in which case you will have to edit the file build.properties to set up values for “tomcat.password” and “tomcat.url”. These can be set to any value: they are not actually used during or after the installation.
    There are some issues with deploying into Tomcat like this so I usually delete the old war file and directory from the webapps directory before I run ant.
  8. You should then be ready to test again.