Windows Preparation for Participants
This training course is intended for people with limited to no experience with Shibboleth, but having some other fundamental skills will let you focus on learning Shibboleth.
You will be able to use these VMs with the InCommon Training SP from anywhere for at least 1 month following your training, such as if you want to revisit the training materials or tinker with it. You will need to update any manual hostname mapping if your VM acquires a new IP address.
- Basic understanding of XML, specifically how to correctly nest elements and properly close tags
- Knowledge of your favorite XML Editor (we recommend Notepad++ for the course; it is pre-installed on the VMs)
- Basic understanding of Internet Information Services (IIS) and the Jetty web server
- Basic understanding of authentication, how it's done at your organization, and familiarity with single sign-on concepts
- Basic knowledge of Windows Server 2008 administration
Helpful Knowledge to have:
- Basic familiarity with Java, Active Server Pages (ASP) and optionally PHP
- Basic knowledge regarding how to find and use log files to troubleshoot issues with applications
- Basic understating of LDAP, specifically your LDAP or Active Directory server, its structure, and who to contact for access (especially if it isn't you ☺ )
- Experience using the Windows Command Prompt
Shibboleth requires that messages passed between the IdP and the SP are in close synchronization time-wise. Please ensure that Windows Time Service is running. If the VM clock falls far out of synch with reality, you may need to manually synchronize the clock:
- Right-click on the clock (lower right of VM screen)
- Select "Adjust Date/Time"
- Click on "Internet Time" tab
- Click "Change Settings"
- Click "Update now"
Installation on a hosted VM
This VM is not intended for production use. If it will ever contain sensitive information or access to sensitive information, you must secure it accordingly. The InCommon training team maintains no documentation on how to do this.
You will need administrator (or root) access in your host environment.
Beware of "security" software, particularly on Windows hosts, that is able to prevent communication between your host environment and your VM.
It's much easier to use Remote Desktop (RDP) to connect to your VM rather than using the VMWare console. It's also nice to give it a name (see steps 5 and 6 below).
VMWare is the only supported virtualization platform for this training. VirtualBox and other platforms will generally not work due to limited networking options and the diverse range of environments that host these classes.
- Install VMWare Player (http://www.vmware.com/go/downloadplayer for Linux or Windows host environments) or VMWare Fusion (http://www.vmware.com/go/downloadfusion for Mac host environments).
- Please download this Windows Server 2008 training VM (4.2GB; allow plenty of time for the download).
- Ensure your VM environment is providing a NAT interface for the first network adaptor instead of a Bridged interface. This can be generally done through the toolbar icons on the bottom of the VM window or through the configuration menus. Don't worry about the unused second interface.
- Start the VM. 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.
- "Please wait while Windows sets up your computer..." (black screen)
=> no action needed (may take several minutes)
- "Please wait while Windows continues setting up your computer..." (GUI)
=> no action needed (may take several minutes)
- <VM Reboots>
- "Set Up Windows" screen #1: (regional settings)
Country or region:
Time and currency:
==> Click Next (defaults are fine)
- "Set Up Windows" screen #2: (license/product key)
==> Click Next (leave box blank)
- "Set Up Windows" screen #3: (license terms)
==> Click the box for "I accept the license terms"
==> Click next
- "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
- "The user's password must be changed before logging on the first time."
==> Click OK
- (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
- "Your password has been changed."
==> Click OK
- Open up a Windows command prompt and run
ipconfig. Look for the IP address associated with the Ethernet adapter Local Area Connection.
Assign a unique, creative FQDN hostname of the form
host.domain.tldto your VM by editing the
hostsfile. In your host environment, edit the
hostsfile generally at
C:\WINDOWS\system32\drivers\etc\hostsusing 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.
On a Windows host, you may need to edit the hosts file as an administrator. If you get a permission error, try right-clicking on the hosts file and select "Open as administrator".
- Use the Microsoft Remote Desktop client to connect to
my.special.namevia RDP, and login as user
Administratorwith the password you chose during sysprep. This is the environment in which you will complete the session.
This VM may be used for both IdP day and SP day, as long as only Jetty or IIS is listening on port 443. On IdP day, make sure you shut down IIS before starting Jetty, and vice versa.
Please remember the unique domain name you gave your VM. It will be referred to many times in the documentation as
- 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 adaptor 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.
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. You should reset the account credentials on this schedule task (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.
Installation on a remote VM
If you choose to use a VM hosted in an environment external to the classroom, please be aware that you will be responsible for addressing any unique, host-related issues. We will try to help but we may be unable to. Consider hosting a local copy of our distributed VMs using the instructions above as a precaution.
Participants without sysadmin experience are encouraged to use the hosted VM method instead.
Select an OS that is supported by the Shibboleth project(or a distribution that is similar) after reading the SP installation instructions for that OS so you know what you're up against. The installers should work with all common versions of Windows, but your mileage may vary. Building from source during the class is a tedious, slow, perilous, and solitary adventure. The instructors are only knowledgeable about supported versions of Windows.
- Your VM will need to accept inbound TCP requests from your host machine on 443 (https for users), 8443 (https for services), and 22 (ssh).
- You will need Administrator-level access to a VM with sufficient disk(at least 2GB) and memory(at least 1GB).
- If you are using a different VM, you may need to install some packages included in our distribution, such as a JDK and Apache Tomcat 6.
- Ensure your VM has a reasonably stable IP address and DNS mapping. You may want to define a custom hostname by assigning your VM a unique, creative FQDN hostname of the form
host.domain.tldby editing the
hostsfile in your host environment.
- Especially if you are using a different version of Windows Server, you may need to interpret the instructions, which are written specifically for Windows Server 2008.
MySpecialNamewill be your VM's domain name.
- RDP to your VM and get started.