Child pages
  • Windows Identity Provider v2
Skip to end of metadata
Go to start of metadata

Shibboleth Curriculum Windows IdPv2

If you are looking for IdPv3, please look here.

 

Course 1 Basics of Installation and Operation of the Shibboleth Identity Provider

Knowledge required:

  • Basic understanding of XML, specifically how to correctly nest elements and properly close tags.
  • Knowledge of your favorite XML Editor, like Notepad or Notepad++ (which has been installed on the VM).
  • Basic understating of LDAP, specifically your LDAP, its structure, and who to contact for access (if it isn't you ☺ ).
  • Basic understanding of Microsoft Windows (Server 2008).
  • Basic understanding of authentication, how it works at your campus, and familiarity with single sign-on concepts.
  • You will need to have the VMware player installed (http://www.vmware.com/go/downloadplayer).
  • You will need to have downloaded the training VM (~4.5 GB).

Helpful Knowledge to have:

  • Basic knowledge of Tomcat/Java
  • Basic knowledge regarding how to find and use log files to troubleshoot issues with applications

Important Hints for using this walkthrough

  • Read each task completely (to the end of the numbered step) prior to executing the commands. Often times examples are a bit further down.
  • Helpful definitions in the Security Glossary
  • If you freeze a VM, upon restart verify the IP and hostname.
  • Remember that sometimes when using DHCP the IP and hostname changes (from day to day).
  • Some tasks in which you edit configurations will have portions of the config you are editing "commented out." Be certain to remove these enclosing comment tags to allow the IdP to pick up the configuration. In situations like this, it is not uncommon for there to be no error in the logs to indicate the problem.

Outcomes:

  • A working Shibboleth Identity Provider (IdP) Service, capable of authenticating users and releasing specific attributes to specific service providers.
  • Familiarity with the IdP documentation available on the Shibboleth wiki (http://wiki.shibboleth.net)

Notes: This document is not meant to be a complete discussion on anything you might ever do with an IdP. There are many topics of potential interest that are left out of this document in an attempt to keep it more focused on getting a basic IdP up and running. This document is meant as a guide to help you get your IdP working and in understanding how to care for it. Please read all documentation which is linked from this document - it is the authoritative source for all things related to the Shibboleth IdP software.

Information about your VM's installation of Windows

  • Your VM is running a trial/unregistered copy of Windows 2008 (32-bit), with all patches as of the April 2013 patch cycle.
  • Your VM's Windows has been setup by the 'sysprep' utility.  Therefore, you will be able to provide a unique name and administrator password for your VM, but it will also start a new evaluation period for the trial license.
  • The base evaluation period is 60 days, but this can be extended to a maximum of 240 days.  There is a scheduled task on the VM that should automatically reset the eval period to 60 days (see tip below about this task).

The first time you boot your VM, you will have to go through the final stage of machine setup that results from using the sysprep utility.  There are 10 stages, detailed below.

1. "Please wait while Windows sets up your computer..."  (black screen)
    => no action needed (may take several minutes)

2. "Please wait while Windows continues setting up your computer..."  (GUI)
    => no action needed (may take several minutes)

3. <VM Reboots>

4. "Set Up Windows" screen #1:  (regional settings)
      Country or region:
      Time and currency:
      Keyboard layout:
    ==> Click Next (defaults are fine)

5. "Set Up Windows" screen #2: (license/product key)
      Product key
    ==> Click next (leave box blank)

6. "Set Up Windows" screen #3:  (license terms)
    ==> Check the box for "I accept the license terms"
    ==> Click Next

7. "Set Up Windows" screen #4:
      Type a computer name:
    ==> enter a unique computer name (suggestion: <your last name>.<your campus domain>  [* do not use a dash in the hostname ])*
    ==> Click Start

8. "The user's password must be changed before logging on the first time."
    ==> Click OK

9. (change administrator password)
    ==> Enter and confirm a new password for the 'Administrator' account (you will use this account for the remainder of this training)
    ==> When done, press enter or click the blue right-arrow icon

10. "Your password has been changed."
    ==> Click OK

TIPS:

  • You should reset the account credentials on the scheduled task that extends the Windows evaluation period (it is the only scheduled task on the VM).  You will need to use the administrator password you created upon the first boot of your VM.
  • You may want to create a shortcut to the Tomcat Monitor utility in your Windows Start menu's 'Startup' folder so that it always runs.  The utility is located in the Start Menu's 'Apache Tomcat 6.0' folder.

NOTE: VM Information

  • To access to your VM, login as user 'administrator' with the password you created during the first boot of the VM.
  • If you would like to view this training page directly on your VM, you will need to add this site to your IE "trusted sites" in order to get the code boxes below with XML config samples to display correctly.
  • Login on the VM console once, run 'ipconfig', make note of your VM's DHCP-assigned IP address, then it will be easier for this course to just RDP to that IP address, rather than using the VM console.

Preconfiguration

Task: Prepare your VM for the Session

1. Ensure that your VM's network adapter is configured to use NAT (not bridged mode). You can view this setting from the menus at the top of the VMWare player window, or the icons at the bottom.
2. Make sure you're logged in to your VM.
3. Check to see what IP address the VM has been assigned by using ipconfig.
4. Assign a unique FQDN hostname of the form host.domain.tld (ensure there are at least 2 dots in the name) to your VM by editing the hosts file. In your host environment, edit the hosts file generally at C:\WINDOWS\system32\drivers\etc\hosts using a text editor of your choice. Add a line following the existing mapping definitions with your chosen FQDN and the VM's IP address to create the mapping. The following is an example.

127.0.0.1       localhost
#::1            localhost

169.254.42.42   my.special.name

Please remember the unique name you gave yourself. It will be referred to many times in this document as YourAssignedHostname.

  • Why do we ask you to do this? We have run into many situations where network authorization is required, which then usually requires interaction from the client(e.g. usr/pass on a webform). In many cases, a VM with a bridged network adapter will be prompted to supply credentials for authorization. Doing this programmatically is not feasible, so we just use a NAT interface to allow your VM to talk to the world via the authorized interface of your host machine.
  • Why does this work? In a standard Shibboleth environment using only the most common profile for SSO and attribute supply, there is no direct communication between the IdP and SP required. The only entity that needs to make inbound requests to both the IdP and the SP is the client – which just happens to be your host machine.
  • What else is neat? You can now continue to use your VM with the InCommon Test SP from anywhere, such as if you want to revisit the training materials or tinker with it. You may need to update the mapping if your VM suddenly somehow acquires a new IP address.

Section 1: Install/Configure

1. Task: Understand the model and the Big Picture

  • Objective:
    • Understand the basics about Shibboleth, how it integrates into a modern IT infrastructure, and what advantages it has over other SSO Systems.
  • Success Factors:
    • Able to explain the basic concepts of federated identity management
    • Able to explain the components of the Shibboleth IdP software
    • Able to explain how Shibboleth fits into the IT infrastructure
    • Able to explain what makes Shibboleth different from other SSO Systems

2. Task: Plan/Think/Decide

  • Objective: Decide on the basic configuration and integration options for your new IdP.
  • Options to consider:
    • Authentication Type
      • LDAP
      • Kerberos
      • X509 coming in the next release (3.0)
      • ActiveDirectory can do either Kerberos or LDAP
    • Authentication integration
    • What is your data/attribute store
      • LDAP
      • SQL
    • Do you have the needed service accounts
      • LDAP service account for the attribute resolver
      • For LDAP Authentication, an LDAP service account for LDAP authentication (can be same as above)
      • NOTE: It may be important to consider FERPA when creating your LDAP service account. If your LDAP service account has access to restricted information, you may need to consider the potential implications for FERPA when releasing attributes from your IdP.
    • SSL Certificate
      • You will want an SSL certificate for your user login page. We will use a dummy certificate for this course, but you will want a certificate from a commonly trusted root when you go to production.
      • This will need to be a cert trusted by your users' browsers (a commercial cert, most likely).
      • This cert will typically not be used by Shibboleth for anything (although some deployment scenarios will protect their SOAP handler with a commercial cert)
      • It will need to be contained in a Java keystore file (.jks) or, if Tomcat 6.x, it can also be a PKCS#12/PFX file.
      • Note: these points are valid only if Tomcat is fronting port 443 (as opposed to Apache/mod_jk or mod_proxy_ajp)

3. Task: Prepare to install the Shibboleth IdP software

  • Objective:
    • Obtain the Shibboleth IdP software
  • Tasks:
    • A recent version of the IdP software is already on your IdP VM at c:\installfest\distro\shibboleth-identityprovider-2.3.8-bin.zip.
    • Do not use that version (it is no longer the most recent version).  Instead, download the latest version here: http://shibboleth.net/downloads/identity-provider/latest/ (do not use the .msi file - while useful, this course's training curriculum is not designed for it)
    • Untar/zip the file using Windows native support for zip files by right-clicking the file and choosing 'Extract All'.  Extract the files into a subdirectory of the same name in the c:\installfest\distro directory (the default option).
  • Resources:
  • Success Factors:
    • You have all of the files available in order to begin installation of the IdP software. 

4. Task: Prepare Java/Tomcat

**Tomcat and Java are already installed on your VM

      ** Tomcat is installed at 'c:\Program Files\Apache Software Foundation\Tomcat 6.0' **
      ** The Java 6 JRE is installed at 'c:\Program Files\Java\JRE6' **

  • Objective:
    • Prepare the java and tomcat environment to run the IdP software.
    • Endorsed libraries
    • Download tomcat6-dta-ssl-1.0.0.jar
    • Endpoints configured
    • Context Deployment fragment?
  • Tasks:
    • Copy all libraries from download/unzip directory's "endorsed" sub-directory (c:\installfest\distro\shibboleth-identityprovider-2.4.2\endorsed) to Tomcat's c:\Program Files\Apache Software Foundation\Tomcat 6.0\endorsed directory (you will need to create this folder)
    • Download the file "tomcat6-dta-ssl-1.0.0.jar" from https://build.shibboleth.net/nexus/content/repositories/releases/edu/internet2/middleware/security/tomcat6/tomcat6-dta-ssl/1.0.0/tomcat6-dta-ssl-1.0.0.jar and copy it to c:\Program Files\Apache Software Foundation\Tomcat 6.0\lib (you will likely find that using Firefox will work better for downloading this file to your VM)
    • Configure Tomcat for endpoints on both ports 443 and 8443 (configure in $TOMCAT_HOME\conf\server.xml). Port 8443 will require client certificates on incoming connections (this is called the SOAP endpoint). Add these endpoints near the existing port 8080 Connector element. Remember the password you used, you will need it when you run the installer.
    • Here is a basic configuration for both port 443 as well as port 8443 (this configures port 443 to use the self-signed cert generated by the IdP installer - substitute an appropriate commercial certificate before moving to production) - just put these near the other <Connector> elements in your config:

      <Connector
        port="443"
        protocol="HTTP/1.1"
        SSLEnabled="true"
        maxThreads="150"
        scheme="https"
        secure="true"
        clientAuth="false"
        sslProtocol="TLS"
        keystoreFile="c:\opt\shibboleth-idp\credentials\idp.jks"
        keystorePass="YourSecretPassword" />
      
      <Connector port="8443"
                 protocol="org.apache.coyote.http11.Http11Protocol"
                 SSLImplementation="edu.internet2.middleware.security.tomcat6.DelegateToApplicationJSSEImplementation"
                 scheme="https"
                 SSLEnabled="true"
                 clientAuth="true"
                 keystoreFile="c:\opt\shibboleth-idp\credentials\idp.jks"
                 keystorePass="YourSecretPassword" />
      
    • Production deployments should use a Tomcat "context deployment fragment" to automatically load the .war file that is built by the Shibboleth installer. Upgrades and changes to the Shibboleth IdP's source that require a re-build (like the login page content) can then be done without messing with Tomcat's folder structure and caching. Use of a context deployment fragment is optional for this workshop. If you don't use one, you'll need to manually deploy the .war file by copying it into Tomcat's webapps folder. Some prefer this behavior, and it can be useful for development. If you want to use a context deployment fragment, create the file c:\Program Files\Apache Software Foundation\Tomcat 6.0\conf\Catalina\localhost\idp.xml and place the following content in it:

      <Context docBase="c:\opt\shibboleth-idp\war\idp.war"
               privileged="true"
               antiResourceLocking="false"
               antiJARLocking="false"
               unpackWAR="false"
               swallowOutput="true" />
    • Do not start/restart tomcat when you are done with this step because the keystoreFile parameter above points to a file that will not exist until you complete the next step. If you suspect tomcat configuration errors after restarting tomcat following the next step, you can check tomcat's main logfile (c:\Program Files\Apache Software Foundation\Tomcat 6.0\logs\catalina.[YYYY-MM-DD].log) for any startup errors.
    • For a context deployment fragment as described above,
  • Resources:
  • Success Factors:
    • Tomcat knows of the correct libraries for Xerces, Xalan and the other endorsed libraries
    • The tomcat6-dta-ssl-1.0.0.jar library has been installed to Tomcat's \lib folder
    • Tomcat is configured to listen on the appropriate ports (443 and 8443)

5. Task: Install Shibboleth

  • Objective:
    • Install the Shibboleth IdP software
  • Tasks:
    • Normally, you would make changes to 2 pages before running the installer - you may do these if you wish, but the default pages will work fine for training purposes (customize these according to your institution's specific styles and needs):
      • Edit the default login and error *.jsp pages located in the download/zip directory's src\main\webapp\ directory
      • Edit the IP ACL for the IdP's status handler by editing the AllowedIPs parameter in the download/unzip directory's src\main\webapp\WEB-INF\web.xml file. CIDR notation is used. This is not necessary for the training course.
    • You will need to set the JAVA_HOME environment variable on your VM prior to running the installer (next step).  You can do this by typing (from a command prompt): "set JAVA_HOME=c:\Program Files\Java\jre6"
    • From a command prompt, run the install.bat batch file found in the location you unzipped the shibboleth installfest download in step 3. It's important to do this from a command prompt, so that any error messages will remain visible after the batch file terminates.
    • Accept default values, other than hostname; for this, enter the fully-qualified hostname for your IdP host (<YourAssignedHostname> from above). This is the external name your users' browsers will use and see.
    • Enter the password for the java keystore created by the installer. This password should be the same password you configured in Tomcat's server.xml in the previous step.
    • If you did not create a context deployment fragment file, deploy the idp.war file created by the installer in c:\opt\shibboleth-idp\war by copying it to Tomcat's webapps folder, (c:\Program Files\Apache Software Foundation\Tomcat 6.0\webapps). 
    • Now, you will need to start/restart tomcat using either the Windows services MMC or the Windows 'Tomcat Monitor' configuration utility (right-click the icon with the green arrow down by the clock).
      • Make sure Tomcat starts successfully (service should show as "started" or the icon should have a green arrow on it)
      • check which ports the server is listening on: netstat -an | find "TCP" | find "LISTEN"  (it should now be listening on 443 and 8443)
C:\>netstat -an | find "TCP" | find "LISTEN"
  TCP    0.0.0.0:443            0.0.0.0:0              LISTENING
  TCP    0.0.0.0:8443           0.0.0.0:0              LISTENING

6. Task: Test basic operation

  • Objective:
    • Verify that your new IdP is up and running
  • Tasks:
    • Confirm the results of Task 5 (specifically, the netstat command)
    • Access the following URL from the IdP server itself
      • https:///idp/status  (IMPORTANT: use 'localhost' instead of <YourAssignedHostname> if you did not set the IP ACL in web.xml)
      •  - OR -
      • From the command line: curl -k https://localhost/idp/status (on some Windows installs, you may need to use '127.0.0.1' instead of 'localhost'
    • You should see lots of information about your IdP that starts with the following (or something very similar):

      ### Operating Environment Information
      operating_system: Windows Server 2008
      
    • If you get an error, you can also try the old deprecated status handler from your browser at this URL (it simply responds with "ok"):
    • If this test fails, please notify an instructor.
  • Resources:
  • Success Factors:
    • You can see a status page successfully.

7. Task: Register your IdP with the administrator's machine for your training session.

  • Objective:
    • Make your IdP's metadata visible in the metadata set for this training session so that you can test logins to external resources using your new IdP.
  • Tasks:
    • Your IdP's metadata can be found in the IdP's installation directory in the /metadata folder as idp-metadata.xml (by default, c:\opt\shibboleth-idp\metadata\idp-metadata.xml). It can also be downloaded from https://<YourAssignedHostname>/idp/profile/Metadata/SAML.
    • Create a local copy of your idp-metadata.xml file on your host machine and give the copy a unique filename, such as idp-<YourAssignedHostname>-metadata.xml (and upload this copy).
    • Upload a copy of your IdP's metadata at the classroom metadata aggregator page: https://md.training.incommon.org/mdupload/
    • The upload page requires a password.  The classroom instructors will communicate the top-secret upload password to you.
    • Classroom metadata is built approximately every 2 minutes.  This is designed as a special test for the impatient, so please wait a couple of minutes before trying to test your new IdP.
  • Success Factors:
    • You can check to see whether your IdP is recognized by the test SP by accessing https://sp.training.incommon.org/secure and using the ugly discovery interface. Don't try to login yet: your IdP doesn't trust the classroom SP yet, and it will say that by indicating that the SAML 2 SSO Profile is not configured for it. This prevents any attribute or authentication data from leaking to unidentified SPs.
    • Your IdP's metadata is visible in the training session metadata (after a couple of minutes).

8. Task: Understand the IdP's configuration files and options

  • Objective:
    • Understand the different configuration files and what's contained in each of them.
  • Configuration Files:
    • There are 9 different configuration files (1 is optional) for the IdP.
    • They are located in the installation directory (c:\opt\shibboleth-idp) inside the conf sub-directory.
    • In this training, we will likely be editing all of these except for the last one, tc-config.xml.
    • Each file is described below:
      • attribute-filter.xml
        • This is where you configure attribute release policies. The Shibboleth IdP has a very flexible rules engine. You can release (or block) attributes to single SP, a list of SPs, or all SPs in a given federation. This is the file you will touch most often.
      • attribute-resolver.xml
        • This is where you configure how the IdP gets or builds attributes. This is perhaps the most powerful feature of the IdP software. The attribute resolver is very flexible, allowing you to retrieve attributes, both textual and binary (jpegPhoto, userCertificate, etc), in the conventional sense from either LDAP or SQL data sources, but also allowing you to create attributes in a variety of interesting ways, ranging from the use of regular expressions to writing custom script. Suffice it to say that the IdP can meet almost any attribute need.
      • login.config
        • This file is used for configuring the authentication parameters for JAAS (Java Authentication and Authorization Service). It is not used if your will be running your IdP in "REMOTE_USER" authentication mode or with 'External' authentication (described in section 1, step 2).  It's format is not XML, in particular, pay careful attention to semicolons and comments (both '//' and '/.../'). The commented examples should give you most of what you need. If you have questions, refer to documentation on the shibboleth wiki (link below in the section on configuring authentication).
      • handler.xml
        • This is where the IdP's various handlers are defined. A handler is basically a mapping between a "special" URL that the IdP uses and the underlying SAML aspect for which that handler answers. Specifically, there are three types of handlers in the file: Error, Profile, and Login. The main configuration item in this file is the <LoginHandler> elements.
      • internal.xml
        • This is probably the least-touched configuration file. It contains much of the "glue" that connects the very-pluggable Shibboleth IdP software. The main configuration items of interest in this file are the frequency with which the logging.xml is re-loaded (defaults to 10 minutes) and the duration of the single sign-on sessions created by the IdP (defaults to 30 minutes).
      • logging.xml
        • The file is where all of the logging activity of the IdP is configured. The default settings are usually fine, but you may want to make changes in this file if you need DEBUG logging for the LDAP Authentication module, if you need DEBUG logging on your authentication events, or if you want to be notified via email when the IdP logs a message with a level of ERROR.
      • relying-party.xml
        • This file is where you define 3 things: sources of SAML metadata, the SAML characteristics of your IdP, and security credentials used by your IdP, both for its own use in signing SAML messages, but also to define certificates used by federations to digitally sign their metadata. The SAML settings can be defined for specific service providers or, of particular interest, is the <DefaultRelyingParty>. These are the settings that apply, if no provider-specific configuration is found in the file. NOTE: Your life with your new IdP will be much simpler if you can avoid creating custom relying party configurations as much as possible and have everything use the <DefaultRelyingParty> configuration.
      • service.xml
        • This file is similar to internal.xml in that it is mostly glue that binds a very pluggable system. The main configuration item of interest in this file is the ability to have your configuration files, usually just the attribute-filter.xml, automatically reloaded at a specified frequency, typically every 5 minutes. The default setting is to not automatically reload any of the configuration files (a restart is required). This is done to protect you from bringing your IdP down with a typo in a configuration file.
      • tc-config.xml (optional)
        • This file is used to configure the Terracotta system. You will only use Terracotta if you plan on load-balancing your IdP (an active/passive IdP pair would not require Terracotta). Terracotta is used to allow two balanced IdPs to share session information between them so that any IdP in the cluster can service any request, even if it originated on another of the IdPs in the cluster (as someone recently said, think of it as 'network-attached memory').
  • Success Factors:
    • Understanding of the IdP's configuration files.

9. Task: Define/load a source of SAML metadata

  • Objective:
    • Configure at least one source of SAML metadata for your IdP.
  • Tasks:
    • Configure the following MetadataProvider element inside (a child of) the main ChainingMetadataProvider element in your relying-party.xml config file:

      <!-- Shibboleth Training classroom metadata -->
      <metadata:MetadataProvider id="ShibbTrainMD" xsi:type="metadata:FileBackedHTTPMetadataProvider" xmlns="urn:mace:shibboleth:2.0:metadata"
      metadataURL="http://md.training.incommon.org/downloads/ShibTrain1-metadata.xml"
      backingFile="c:\opt\shibboleth-idp\metadata\ShibTrain1-metadata.xml" />
      
    • Restart tomcat when you are done (and consider re-checking the status page, as in step 6).
  • Resources:
  • Note:
    • For all non-test installations, it is important to require both the maxValidityInterval filter and Signature Validation filter on the metadata sources that you configure. These both help to improve the integrity of the federation metadata and make the environment more secure.  See the default IdP configuration files or the above URL for examples.
  • Success Factors:
    • Your IdP has retrieved and loaded SAML metadata from the configured source.
    • Check the c:\opt\shibboleth-idp\metadata directory to see if a cached copy of the metadata shows up (ShibTrain1-metadata.xml).

10. Task: Configure User Authentication

  • Objective:
    • Configure your IdP to authenticate your users using the UsernamePassword authentication handler
  • Tasks:
    • UsernamePassword: Can be either LDAP or Kerberos (we'll use this handler to perform LDAP authentication for this training session)
      • Configure the LDAP section of login.config in your IdP installation's config directory (c:\opt\shibboleth-idp\conf)
        • The training LDAP server is found at 'idp.training.incommon.org' on port 389. 
        • Configure your IdP to search for the user using a bindDn of 'uid=IdPServiceAcct,ou=people,dc=example,dc=org' and a bindCredential of 'password' as described int he link below defining IdPAuthUserPass).
        • NOTE: Be sure to remove the comment tags which surround this section of the login.config file.  (/* ... */)
        • BaseDN is ou=people,dc=example,dc=org
        • For production-grade scenarios, it's important to use LDAPS so that passwords do not traverse your network in clear text (not needed for this training session)
        • In such cases (ldaps), you may need to use the java keytool to add your LDAP server's certificate signing CA certificate to the java trust store - (filename: <jre>\lib\security\cacerts)

          keytool -import -trustcacerts -alias "sensible-name-for-ca" -file directory.crt -keystore %JAVA_HOME%\lib\security\cacerts
        • A completely configured login.config file will look like this:

          ShibUserPassAuth {
          
          // Shibboleth Installfest LDAP Server
          // See: https://wiki.shibboleth.net/confluence/display/SHIB2/IdPAuthUserPass
             edu.vt.middleware.ldap.jaas.LdapLoginModule required
                host="idp.training.incommon.org"
                port="389"
                base="ou=people,dc=example,dc=org"
                bindDn="uid=IdPServiceAcct,ou=people,dc=example,dc=org"
                bindCredential="password"
                userField="uid";
          
          };
    • Edit handler.xml (also in the IdP installation's /conf directory)
      • Uncomment the "UsernamePassword" login handler in handler.xml
      • *Make sure that the XML attribute 'jaasConfigurationLocation' that points to your login config file contains 3 slashes - file:///c:\opt\shibboleth-idp/conf/login.config
      • Comment out the "RemoteUser" login handler
    • Edit relying-party.xml (also in the IdP installation's /conf directory)
      • Add your authentication method's handler type as an XML attribute to the <DefaultRelyingParty> element in relying-party.xml (add it before the closing '>'.  It can be on a new line, just place it before the '>'.) 
        • defaultAuthenticationMethod="urn:oasis:names:tc:SAML:2.0:ac:classes:PasswordProtectedTransport"
    • Restart tomcat
  • Resources:
  • Test:
  • Success Factors:
    • IdP is able to successfully authenticate users

11. Task: Configure User Attributes/Attribute Resolver

  • Objective:
    • Configure the IdP's attribute resolver to understand common LDAP attributes and have the necessary information to retrieve them.
    • Tasks:
      • Uncomment the attribute definitions for Core, inetOrgPerson, and eduPerson in the IdP's conf\attribute-resolver.xml file.
      • Uncomment and configure the resolver:DataConnector called myLDAP (towards the bottom of the file) to connect to the LDAP directory on the classroom admin machine (openldap installed on the classroom IdP - idp.training.incommon.org) and retrieve information for the authenticated user
      • Use the same service account credentials as in the previous step (uid=IdPServiceAcct,ou=people,dc=example,dc=org).
      • Your IdP's LDAP server is found at 'idp.training.incommon.org' on port 389.
      • The baseDN is ou=people,dc=example,dc=org
      • The IdP can retrieve attributes with a username of 'uid=IdPServiceAcct,ou=people,dc=example,dc=org' ('password').
      • A correctly configured DataConnector will look like this:

        <resolver:DataConnector id="myLDAP" xsi:type="dc:LDAPDirectory"
                ldapURL="ldap://idp.training.incommon.org:389"
                baseDN="ou=people,dc=example,dc=org"
                principal="uid=IdPServiceAcct,ou=people,dc=example,dc=org"
                principalCredential="password">
                <dc:FilterTemplate>
                    <![CDATA[
                        (uid=$requestContext.principalName)
                    ]]>
                </dc:FilterTemplate>
            </resolver:DataConnector>
      • This is also the file where you would define any custom or campus-specific attributes that you intend to use with Shibboleth. Of particular note here: be careful to not create arbitrary names for your attributes. They must be in a namespace that you control. There are examples in the file and on the Shibboleth wiki (see here: https://wiki.shibboleth.net/confluence/display/SHIB2/IdPAddAttributeExamples).
      • Restart tomcat when you are done.
  • Resources:
  • Success Factors:
    • Your IdP is able to retrieve and assert basic user attributes.  NOTE: It will not release attributes to any SP yet (that's the next task), but you can see the IdP gathering attributes if you adjust your logging levels in logging.xml to DEBUG.

12. Task: Configure Attribute Release Policies

  • Objective:
    • Successfully create and test an attribute release policy.
  • Tasks:
    • Create a new rule to release several attributes to the classroom's test SP located on the training machine by adding this to your attribute-filter.xml inside the main <AttributeFilterPolicyGroup> element:

      <afp:AttributeFilterPolicy id="releaseForClassroomSP" >
        <afp:PolicyRequirementRule xsi:type="basic:AttributeRequesterString" value="https://sp.training.incommon.org/shibboleth" />
        <afp:AttributeRule attributeID="eduPersonPrincipalName">
          <afp:PermitValueRule xsi:type="basic:ANY" />
        </afp:AttributeRule>
        <afp:AttributeRule attributeID="displayName">
          <afp:PermitValueRule xsi:type="basic:ANY" />
        </afp:AttributeRule>
        <afp:AttributeRule attributeID="email">
          <afp:PermitValueRule xsi:type="basic:ANY" />
        </afp:AttributeRule>
        <afp:AttributeRule attributeID="commonName">
          <afp:PermitValueRule xsi:type="basic:ANY" />
        </afp:AttributeRule>
        <afp:AttributeRule attributeID="surname">
          <afp:PermitValueRule xsi:type="basic:ANY" />
        </afp:AttributeRule>
        <afp:AttributeRule attributeID="givenName">
          <afp:PermitValueRule xsi:type="basic:ANY" />
        </afp:AttributeRule>
        <afp:AttributeRule attributeID="eduPersonAffiliation">
          <afp:PermitValueRule xsi:type="basic:ANY" />
        </afp:AttributeRule>
        <afp:AttributeRule attributeID="uid">
          <afp:PermitValueRule xsi:type="basic:ANY" />
        </afp:AttributeRule>
      </afp:AttributeFilterPolicy>
      
    • NOTE: each <AttributeFilterPolicy> element that you create needs a locally unique id.
    • Filter policies are cumulative. All the rules that apply to a given SP (either through direct reference or by inclusion in a group or regex) are processed.
    • You can also block/deny an attribute to a given SP which would have been released under a different policy. This is most helpful if you need to block the transient nameID from being released to an SP (e.g. Google) so that you can release a specific non-transient nameID.
    • You can create release policies for a specific SP, a list of SPs, or all SPs in a given federation (metadata file).
    • Finally, you can test your changes using the c:\opt\shibboleth-idp\bin\aacli.bat utility (see here: https://wiki.shibboleth.net/confluence/display/SHIB2/AACLI). It's very useful to verify that you've specified rules correctly before restarting the IdP.
    • Before using aacli, you'll need to ensure that servlet-api.jar, a library that is part of the Tomcat distribution, is in aacli's classpath. Copy the file c:\Program Files\Apache Software Foundation\Tomcat 6.0\lib\servlet-api.jar into c:\opt\shibboleth-idp\lib.
    • You will also need to set the IDP_HOME environment variable as follows:

      set IDP_HOME=c:\opt\shibboleth-idp
    • From a command prompt:

      cd \opt\shibboleth-idp\bin
      .\aacli.bat --configDir=..\conf --principal=staff1 --requester=https://sp.training.incommon.org/shibboleth
    • Remember to restart tomcat after you verify your rules work and you are done.
  • Test:
    • https://sp.training.incommon.org/secure (this time, it should display some user attributes after logging in)
    • You should be able to authenticate as staff1/password, student1/password, staff2/password, or student2/password.

Section 2: Advanced Tasks

For individuals who complete the basic curriculum quickly and want to learn more about the IdP, here are some suggestions.

1. IdP-Initiated SSO

Normal federated identity transactions begin with the user accessing the SP, and the SP then issues a SAML 2.0 AuthnRequest for the user to deliver to the IdP. Authentication occurs, an assertion is generated, and the user is launched back to the SP in a redirect.

Many commercial providers are unable or unwilling to issue these AuthnRequests. Furthermore, initiating the federated identity transaction at the IdP eliminates the need for discovery. Thus, in a variety of situations, it's desirable to start the federated identity transaction with the authentication of the user and issuance of the assertion, bypassing the use of an AuthnRequest.

https://wiki.shibboleth.net/confluence/display/SHIB2/IdPUnsolicitedSSO

Try creating a webpage that will log you into the training SP, which has the entityID of https://sp.training.incommon.org/shibboleth.

Bonus points: investigate the implications of this potential attack and its impact on IdP-initiated SSO, but shrug, because there is little that can be done if you want to use unsolicited SSO.

http://tools.oasis-open.org/issues/browse/SECURITY-12

2. Fancy Attribute Filter Policies

Our simple attribute release rule sends a lot of attributes to a single provider. Try creating a rule that will release EPPN for an affiliation of staff, but not for an affiliation of student. You can probably suss it out from the examples in the following Wiki page.

https://wiki.shibboleth.net/confluence/display/SHIB2/IdPAddAttributeFilterExamples

Finally, attribute filters can be written in two different ways. They can be grouped by provider – as we've seen here – or they can be grouped by attribute.

Ordered by provider: <afp:AttributeFilterPolicy>
<afp:PolicyRequirementRule xsi:type="basic:AttributeRequesterString" value="https://serverA.example.org/shibboleth" />

<afp:AttributeRule attributeID="givenName">
<afp:PermitValueRule xsi:type="basic:ANY" />
</afp:AttributeRule>
</afp:AttributeFilterPolicy>

<afp:AttributeFilterPolicy>
<afp:PolicyRequirementRule xsi:type="basic:AttributeRequesterString" value="https://serverB.example.org/shibboleth" />

<afp:AttributeRule attributeID="givenName">
<afp:PermitValueRule xsi:type="basic:ANY" />
</afp:AttributeRule>
</afp:AttributeFilterPolicy>Ordered by attribute: <afp:AttributeFilterPolicy>

<afp:PolicyRequirementRule xsi:type="basic:ANY" />

<afp:AttributeRule attributeID="givenName">
<afp:PermitValueRule xsi:type="basic:OR">
<basic:Rule xsi:type="basic:AttributeRequesterString" value="https://serverA.example.org/shibboleth">
<basic:Rule xsi:type="basic:AttributeRequesterString" value="https://serverB.example.org/shibboleth">
</afp:PermitValueRule>
</afp:AttributeRule>
</afp:AttributeFilterPolicy>
3. Attribute Release to another SP

We only have one SP for you to release attributes to. However, there's a general use SP that you can also use at TestShib.

http://www.testshib.org/testshib-two/index.jsp

Try registering your IdP with TestShib. After registering your IdP, you just need to load the TestShib SP's metadata, and set up attribute release. Go here to try it once you're done:

https://sp.testshib.org/

This is a good example of trivial onboarding.

Attribute release based on entity attributes

You can configure the IdP to release attributes based on information in metadata (so-called "entity attributes").  This can greatly simplify the onboarding process as attributes would automatically be released to new SPs with configured entity attributes in their metadata without the IdP operator having to configure a specific attribute release rule for these new SPs.

For information on how to configure this in the IdP, see this page: https://wiki.shibboleth.net/confluence/display/SHIB2/IdPFilterRequirementAttributeRequesterEntityAttributeExactMatch

InCommon will soon be announcing the first federation-wide category of SPs which will work with this type of configuration.

4. Deliberate Failure

Debugging failing federated identity transactions is difficult because you only have access to half of the logs and a fraction of the configuration. In this controlled environment, we encourage you to deliberately screw up some likely parts of your configuration (forgetting to add metadata, forgetting to do attribute release, using the wrong certificate, skewing your clock) to see what failure looks like in each common case. The trainers are available to suggest more ways to fail, and to help you understand the debugging process involved with each failure situation that you can create.

Here is a helpful Wiki article on common error messages.

https://wiki.shibboleth.net/confluence/display/SHIB2/IdPTroubleshootingCommonErrors

In the real world, excellent communication between you and the SP will be necessary to rapidly diagnose and remedy any issues. Phone calls are happy things.

Section 3: Move to Production - Tips, Tuning, & Things to Think About

1. Clustering and High Availability

We intend to write more about clustering at some point in the near future. For now, we ask you to refer to the official Shibboleth documentation and Wiki for what we intend to boil down into something cohesive.

https://wiki.shibboleth.net/confluence/display/SHIB2/IdPClusterIntro

https://wiki.shibboleth.net/confluence/display/SHIB2/IdPStatelessClustering

http://marc.info/?l=shibboleth-users&m=131116482108400&w=2 https://wiki.shibboleth.net/confluence/display/SHIB2/Contributions#Contributions-IdentityProviderExtensions

https://wiki.shibboleth.net/confluence/display/SHIB2/Contributions#Contributions-IdentityProviderExtensions

2.  Logging configuration

  • Notes:
    • 3 log files (in the logs folder of your IdP installation directory):
      • idp-process.log - the main log file and the place to look when troubleshooting
      • idp-access.log - a small parseable log of incoming requests
      • idp-audit.log - A parseable transaction log
    • Logging.xml is read every 5 (looks like it's been changed to 10) minutes, so no restart is required if you are trying to troubleshoot a problem.
    • Generally, leave the log levels at the default values of WARN or INFO. Set to DEBUG for a potentially massive amount of detail.
    • It will be necessary to set a logger for "edu.internet2.middleware.shibboleth.idp.authn" to DEBUG if you plan to parse your logs for successful and failed authentication events.
    • It is also possible to configure the IdP's logging system to send an email any time it sees a logged message at the ERROR level. Beware - while nice in concept, this can produce lots of spurious emails.
  • How to configure:
    • Configured in (IDP_HOME)\conf\logging.xml
  • Resources:

3. Authentication/Single Sign-On Window

  • Issue:
    • By default, the IdP sets 30 minute duration for the single sign-on window (the amount of time your session is valid without requiring the user to login again). Many institutions would prefer a longer window, typically 8 hours.
  • How to configure:
    • Edit your conf\internal.xml file.
    • Look for the line "<bean id="shibboleth.SessionManager""
    • Make sure these two elements appear inside that <bean> element (the setting is in milliseconds, this example sets your SSO window to 8 hours):
      • <constructor-arg ref="shibboleth.StorageService" />
      • <constructor-arg value="28800000" type="long" />
    • Edit your handler.xml
    • Look for the UsernamePassword LoginHandler
    • Add an authenticationDuration of PT8H as a parameter of the <LoginHandler> element (this also sets the SSO window for 8 hours):

      <ph:LoginHandler xsi:type="ph:UsernamePassword"
                       jaasConfigurationLocation="file:///opt/shibboleth-idp/conf/login.config"
                       authenticationDuration="PT8H">
  • Resources:

4. LDAP versus LDAPS

  • Issue:
    • If you use regular ldap (rather than ldaps), your users' passwords will traverse the network between your IdP and your LDAP server in clear text. This is never good and must not be the case for InCommon Silver (http://www.incommon.org/assurance/).
    • Also of concern is the retrieval of attributes by the IdP. Those attributes (and the service account password of your IdP) will all traverse the network between the IdP and the LDAP server in clear text, unless you configure LDAPS.
  • How to configure:
    • To use LDAPS for authentication and protect the privacy of user passwords during the authentication event, configure ldaps in the login.config file (by changing the LDAP URL to ldaps).
    • To use LDAPS for attribute retrieval, configure ldaps in your ldap data connector in the attribute-resolver.xml configuration file.
    • If your LDAP server does not use a well-trusted commercial certificate, then the CA which signed your LDAP cert will need its cert placed in the JRE's lib\security\cacerts file. You use the java keytool utility to do this (substitute as appropriate for %JAVA_HOME%).       

      keytool -import -trustcacerts -alias "sensible-name-for-ca" -file directory.crt -keystore %JAVA_HOME%\lib\security\cacerts
  • Resources:

5. Security/Hardening for your IdP

  • Issue:
    • It's always good to eliminate or turn off unneeded services and applications on your IdP.
  • How to configure:
    • Here's are some considerations for achieving this objective:
      • Remove default/unneeded tomcat apps from the ($TOMCAT_HOME)\webapps folder - possible candidates:
        • manager
        • host-manager
        • root
        • examples
      • Don't have tomcat listening on unneeded ports - comment these out in ($TOMCAT_HOME)\conf\server.xml:
        • 8009
        • 8080
      • Consider running tomcat as a non-privileged account - see https://wiki.shibboleth.net/confluence/display/SHIB2/IdPLinuxNonRoot for one possible method to do this.
      • Possible issue on some security tools with weak ciphers - see http://www.nessus.org/plugins/index.php?view=single&id=26928 for more info.
      • In addition to the Shibboleth IdP software, always check for critical updates to both Tomcat and Java as well. The respective user mailing lists are always a good way of doing this.

6. Monitoring

7. Reporting

  • Notes:
    • You can write a script to parse your IdP logs for useful reports (some may require DEBUG logging). Here are some useful search strings for various reports:
      • successful authentication events:
        • "Successfully authenticated user"
      • failed authentication events:
        • "User authentication" + "failed" (on same line)
      • assertions issued:
        • "[Shibboleth-Audit:"
      • possible security events (this is only a partial list):
        • "No metadata for relying party"
        • "Replay detected of message"
        • "Error decoding artifact resolve message"
  • For the failed/successful login messages to appear in your idp-process.log file, you must set DEBUG logging in your logging.xml file like this:

    add to logging.xml
    <logger name="edu.internet2.middleware.shibboleth.idp.authn">
            <level value="DEBUG" />   
    </logger>
    

8. Configuration reloading

  • Issue:
    • It can become rather irritating to have to experience a brief service outage (from a service restart) just to add an attribute release rule to your configuration.
    • You can configure the IdP to automatically reload your attribute-filter.xml file on a periodic basis.
    • CAUTION: If you make a typo, you could bring down the IdP so it's good to have a way to safely edit this file or be able to quickly test it after doing so.
  • How to configure:
    • Edit your conf\service.xml file.
    • Look for the line:
      • "<Service id="shibboleth.AttributeFilterEngine""
    • Add this to the end of that main <Service> element (it is in milliseconds, this example sets it to reload your attribute-filter.xml every 5 minutes):
      • configurationResourcePollingFrequency="300000"
  • Resources:

9. Memory options for Java (JAVA_OPTS)

  • Issue:
    • When you move your IdP to production, you should configure the memory settings for Java to ensure that it has adequate memory.
  • How to configure:
    • These options are typically set via the well-known JAVA_OPTS environment variable.
    • However, in Windows it is even easier since you can just use the Windows 'Tomcat Monitor' configuration utility to set the 2 different maximum memory settings described at the link below (click on the utility's 'Java' tab).
  • Resources:

10. Performance Tuning the Java VM

11. Handling Upgrades

Don't be afraid to upgrade. Be afraid not to upgrade. But upgrade wisely.

For all of these, using symbolic links can be very handy (e.g. c:\program files\java would always point to the version of java in use, but could actual refer to c:\program files\java6_25, etc).  On Windows, use mklink - see here for more info: http://technet.microsoft.com/en-us/library/cc753194%28WS.10%29.aspx)

  • Java
    • Install new java alongside old java
    • When ready to switch, change the version of Java that Tomcat is using by pointing to the new version in the Windows Tomcat configuration utility (on the Java tab).
    • Restart tomcat
  • Tomcat
    • Install new tomcat to new location
    • Create/Copy the endorsed directory from the previous installation
    • Copy "tomcat6-dta-ssl-1.0.0.jar" from the previous installation's (TOMCAT_HOME)\lib directory to the new installation's \lib directory** Move the configuration for Connectors for ports 443 and 8443 to the new installation (make sure that Tomcat has not changed the syntax between versions)
    • If you are using a context deployment fragment move/create it for the new Tomcat installation
    • Set the previous version to not auto start and set the new version to auto start.
    • Stop the previous version
    • Start the new version
    • Check the new version's (TOMCAT_HOME)\logs directory for any problems
  • Shibboleth IdP
    • Check the Shibboleth wiki for specific upgrade instructions related to the new version
    • Unzip package
    • Update any endorsed libraries that are new
    • Update (TOMCAT_HOME)\lib\tomcat6-dta-ssl-1.0.0.jar if it is new (check the wiki).
    • Customize web pages
      • Be careful about just copying your old pages since there may have been changes in the .jsp files related to the upgrade (check the wiki).
    • Customize IP ACL on the status handler in web.xml
    • Run install.bat
    • If not using a context deployment fragment in Tomcat, copy new war file from install location's "war" directory to Tomcat's webapps directory.
    • Restart tomcat
    • Check status URL

12. Troubleshooting

13. Support Resources

  • No labels