Install SP 2.3

Obsolete

These are obsolete docs that should not be used. For new installations, please refer to our current Technical Docs.

1. Install the SP Software

This has been documented on the Shibboleth Installation page provided by Internet2. Installation on a Linux server is fairly straightforward: grab the RPM packages for the Shibboleth SP and supporting libraries and install them on your system. You may have to rebuild the packages from the SRPM files, but those instructions are provided as well.

RedHat EL6 installation of Shibboleth SP 2.4.x is pre-packaged in the Vision3 yum repository. See these instructions.

2. Choose an EntityID

Your new SP will need to be identified by a unique ID in the federation metadata. By common convention, that ID will look like a URL, although it does not need to be a valid URL. The format to use is:

https://yourservicename.ncsu.edu/sp/shibboleth

"yourservicename.ncsu.edu" should be the domain name of the server that is running your SP, but that is not required.

3. Generate the SP keys

NCSU Federation does not sign key certificates. (UNC-GA and InCommon/NC Trust used to, but now use self-signed as well.) You can generate your own key using the SP software and use the self-signed certificate that it creates. You can also reuse the certificate signed by one of the other federations, if you prefer. If you plan to join multiple federations, go ahead and use the self-signed certificate. You will be able to install multiple certificates, one for each federation.

For a linux installation, the RPM has probably already created a key pair for you. You should rebuild the key-pair to make sure the right information is saved inside it. Here is how I created a key-pair for my test SP, named mosa2.unity.ncsu.edu:

# on the server, logged in as root
cd /etc/shibboleth

# find the script
ls keygen.sh

# regenerate the key
sh keygen.sh -f -y 5 -h mosa2.unity.ncsu.edu -e https://mosa2.unity.ncsu.edu/sp/shibboleth

# verify that the keys exist
ls sp-*.pem

These commands re-create a self-signed key-pair, valid for 5 years, for the host and entityid as given.

Note that the keygen script may set your key file permissions wrong. By default, it makes the key mode 0600, owner root. The shibd process runs as user shibd. You should chown the file to shibd, and keep the 0600 perms.

4. Install the metadata signing certificate

The NCSU Federation metadata is signed by a private key. You will need to install the certificate for that key in order to verify that our metadata was signed correctly. You can simply grab the key from our website and save it in a file:

# on the server, logged in as root
cd /etc/shibboleth

wget https://docs.shib.ncsu.edu/federation/ncsu_federation.pem

# verify
ls ncsu_federation.pem

5. Configure the service provider

You can use most of the default settings on your service provider, at least to start. You will need to customize a few entries for your hostname, entityid, and to use our federation metadata.

# on the server, logged in as root
cd /etc/shibboleth
vi shibboleth2.xml

# find the Host declaration in the RequestMap for default (line 62)
# change the Host name="" to match your server

# find the ApplicationDefaults block (line 77)
# set the entityID="" to match your selection
# set the homeURL="" to a valid URL on our server

# find the default SessionInitiator block (line 106)
# set the entityID="https://shib.ncsu.edu/idp/shibboleth"
# which sends all users directly to the Unity login IdP (we have no WAYF page so far)

# find the example of a chaining metadata provider (line 217)
# insert the following code for NCSU Federation metadata

  <MetadataProvider type="XML"
    uri="https://docs.shib.ncsu.edu/federation/metadata.xml"
    backingFilePath="ncsu_fed-metadata.xml"
    reloadInterval="7200">
      <SignatureMetadataFilter certificate="ncsu_federation.pem"/>
  </MetadataProvider>

# save and close the file

Once the configuration is setup correctly, you can (re)start the shibd and httpd services.

You may also refer to this OLD sample shibboleth2.xml file from the mosa2.unity.ncsu.edu test SP.

6. Register your SP with the federation

Please use our web form to request SP registration in the NCSU Federation. To use this form, you will need:

The entityID, from step 2 above
The SP metadata XML data. We need to have either the URL to download this data ourselves, or you can cut-and-paste the metadata into the request form. If your SP is configured and running, then you should be able to connect your browser or wget to a URL like: "http://servername.ncsu.edu/Shibboleth.sso/Metadata". Once you have confirmed this URL is working, you can enter it on the form, or copy-and- paste the data from the file to the form if you prefer.
The name of the person responsible for this SP (presumably the person filling out the form)
A brief summary of the project that needs to use our Shibboleth identification. This section is mostly for our records. As we expand the attributes that are available through our IdP, we will need to get justification before we can release some of the sensitive attributes. We can negotiate these attributes later, as needed.

When you submit our form, your entry will be put into the Remedy system for future tracking. One of us in OIT will get your call, verify the data, and add your entry to the signed metadata on our servers. After this is completed, we will contact you again and let you know that your SP has been added to the federation. It may take a few hours for cached copies of the previous metadata to clear off our IdP and your SP, so be prepared to wait a little while before testing.

7. Basic Testing

One easy way to test your new SP is to create a test page in the /secure directory on your site. This directory is setup by default in the Shibboleth installation package. Assuming you have a standard httpd installation that uses /var/www/html as the document root, and PHP installed, you can create a test page like this:

cd /var/www/html
mkdir secure
cd secure
vi test.php

# add these three lines
<pre>
<?php print_r($_SERVER) ?>
</pre>

# save the file and exit vi

Once the page is created, point your browser at http://yourserver.ncsu.edu/secure/test.php. The website should redirect you to the NC State IdP to login. When you return to your site, the PHP page should display a dump of the environment variables that it received, which should include the Shibboleth login information.

Array
(
   ...
    [Shib-Application-ID] => default
    [Shib-Session-ID] => _6c45a07c8bc73190121212121221b7
    [Shib-Identity-Provider] => https://shib.ncsu.edu/idp/shibboleth
    [Shib-Authentication-Instant] => 2009-05-27T20:00:00.101Z
    [Shib-AuthnContext-Decl] => urn:oasis:names:tc:SAML:2.0:ac:classes:PasswordProtectedTransport
    [affiliation] => member@ncsu.edu;staff@ncsu.edu
    [eppn] => XXXXXX@ncsu.edu
    [unscoped-affiliation] => member;staff
   ...
    [REMOTE_USER] => XXXXXX@ncsu.edu
   ...
)

8. Passed Variables

You can change the names of the variables that are passed by editing /etc/shibboleth/attribute-map.xml. You can also add new variables here. Note that our Shib2 SP seems to pay attention to the "urn:oid:..." entries over the named entries. The default attribute-map has a lot of commented examples to use. See our page of attributes supported by the NC State IdP for a list of available variables.

The REMOTE_USER variable is set from one of a list of variables as defined in the shibboleth2.xml config file. If you change the named of the "eppn" attribute, be sure to update this file as well so REMOTE_USER gets picked up correctly.