Pre-flight checklist.

The goal of this exercise is to confirm some assumptions about our environment.

Summary:

  • Is our Windows XP workstation on the domain?
  • Are we logged onto the domain?
  • Do we have a domain account for the app server?
  • Do we know the address of the KDC?
  • Do we have the latest version of the JDK installed?
  • Test connection to KDC using HelloKDC.java
  • A successful test of the connection to the KDC using the sample program HelloKDC.java is one of the best ways to prove that we are ready to install/configure the servlet filter. The HelloKDC program will give us more confidence that we have our krb5.conf and login.conf files configured properly.

    Is our Windows XP workstation on the domain?

    We can confirm if our Windows XP workstation is on the domain by going to Start > Settings > Control Panel and opening the "System Properties" window. If you have Windows XP in classic mode, then you should see an icon labeled "System". Otherwise, you will have to go into Performance and Maintenance to see the icon.

    The "System Properties" window will tell us two things:

    1) The "Full computer name" (FQDN)
    2) The "Domain" name

    How these two names appear in this window is important. Most developers do not reference computers by their FQDN. For example, we sometimes use the ping command to help us determine if a host is up or down. But most of us type in prompt>ping hercules instead of prompt>ping hercules.athena.local because it's easier.

    Also, notice that in this example the domain name is "athena.local". Yet when we login into our workstations we select the "ATHENA" domain from the drop-down (backwards compatibility with Net BIOS). If you have ever been prompted for a username and password, you probably typed-in athena\dfelix or just dfelix instead of athena.local\dfelix as your username.

    The FQDN and Domain name will become important later when we start configuring our krb5.conf file and in registering Service Principal Names. For this example, the name of the Realm and the name of the Domain are the same. Be sure to put the name of the Domain for the Realm.

    Are we logged onto the domain?

    You may not have even realized it but you probably do this every morning. Log-off your workstation now and log back in. This time pay attention to the login screen.

    Click the "Options > >" button to expand.

    Some organizations have multiple domains running. Hence, this drop-down may have more than a couple of options. Just be sure you do NOT login locally by selecting the one with the parenthetical expression "(this computer)" option. Select "ATHENA" instead.

    Do we have a domain account for the app server?

    A service account is conceptually very similar to a regular domain user account; both of which are more commonly known as Windows NT accounts. In fact, your organization's Admin/OPS department probably performs the same steps during creation of the accounts; except that they set the password to never expire on service accounts.

    It is possible to have the app server "run as" some domain account and have another domain account for the purpose of pre-authentication. However, it is more likely that the app server will "run as" Local System.

    Also, pre-authentication is configured in Tomcat's web.xml file. The SPNEGO HTTP Servlet Filter uses the servlet's init params (defined in web.xml) to obtain the domain account and password to use to pre-authenticate to the KDC:

    Once you receive the username and password from your OPS team, confirm that the username and password you received is correct by attempting to login on some workstation. However, keep in mind that it is possible to create an account such that it can only run as a service and not be used to login onto workstations.

    Do we know the address of the KDC?

    The best way to know the address(es) of the KDC is to have a conversation with your OPS team. However, if you know the IP address or host name of Active Directory, then you probably already know the address of the KDC (they are usually on the same host).

    Another way to determine the address of the KDC is to use the ping command:

    Notice that by ping-ing the domain, we were able to get the IP of the KDC (your organization may be running multiple KDCs so you may get a different IP each time).

    It is preferred that we use host names instead of IP addresses. Run the ping command on the IP address and use the -a flag to get the host name associated with the IP address.

    Do we have the latest version of the JDK installed?

    Java 6 is required (1.6.x and above). It is best to have both the Java Runtime Environment (JRE) and the Java Developer Kit (JDK) installed on your workstation. Your app server will only need the JRE installed. Your workstation will only need the JDK if you want to do some advanced configurations, or if you want to build the SPNEGO project from source, or if you want to write a java client that uses SPNEGO.

    We can confirm the version of the JRE and JDK installed by running each program with the -version flag:

    Notice that in both cases the JRE and JDK are at the same version and patch level (1.6.0_16).

    Test connection to KDC using HelloKDC.java

    The final part of the pre-flight is to confirm that we can connect to the KDC using a simple java program which we will configure to use some information we gathered earlier. Specifically, we will create a krb5.conf file, create a login.conf file, and then modify and compile HelloKDC.java. However, we will be starting with a pseudo-template for each. Meaning, you'll simply have to replace the values in the files with the values from your environment.

    For convenience, place all three files in the same directory.

    1) Creating the krb5.conf file. Download and open the file in notepad. Replace the references to ATHENA.LOCAL and cerberus.athena.local with the values from your environment. Notice below that the name of the Domain and Realm is ATHENA.LOCAL. Replace the Domain and Realm values with the name of your Domain.

    Save the file.

    2) Creating the login.conf file. Download and open the file in notepad. It is not necessary but feel free to change the module names spnego-client and spnego-server. Part of the servlet filter install will require you to enter these module names in the web.xml file.

    Save the file.

    3) Creating the HelloKDC.java file. Download and open the file in your favorite source code editor.

    Replace the empty string values on lines 22 thru 34 with the values from your environment.

    Save the file.

    4) Compile HelloKDC.java and then run it from a command prompt.

    If things worked as expected, you should see "Connection test successful." in the output.

    Troubleshooting HelloKDC.java

    If the test was not successful, take a look at the Troubleshooting HelloKDC.java page.

    Links:
    pre-flight checklist
    install guide - tomcat
    install guide - jboss
    install guide - glassfish
    reference docs
    api docs
    download

    Troubleshooting:
    HelloKDC.java
    hello_spnego.jsp
    HelloKeytab.java
    hello_delegate.jsp
    SpnegoHelloClient.java
    ExampleSpnegoAuthenticatorValve.java

    Examples:
    create keytab for client
    create keytab for app server
    credential delegation
    protected SOAP Web Service
    tomcat authenticator valve
    jboss authenticator valve

    Licensing:
    GNU LGPL


    © 2009 Darwin V. Felix. All rights reserved.