Moving from WRAP to Shibboleth
How WRAP Works - an explanation of the login process for WRAP, and why it needs to be replaced.
How Shibboleth Works - an explanation of the login process for Shibboleth, for comparison with WRAP.
Shibboleth Versus WRAP - a comparison of the problems with WRAP and how they are addressed by Shibboleth.
Installing Service Providers
If you are running your own web servers, you will need to install the Shibboleth Service Provider software and setup one or more SP Entities. If all you want to do is replace WRAP with Shibboleth, these notes will help guide you through the planning process in step 1 below.
- You still need to run the SP software on each server.
- You should run SSL for the handler on each server, if possible.
- If you are setting up a department of servers, all of which just need to replace WRAP, then you should consider registering a single department SP Entity shared by each of your hosts.
- You want to register with the NCSU Federation.
- You want to ask for the attributes needed to replace WRAP. That will give you eduPersonPrincipalName (=email@example.com) and uid (=unityid). Let us know that you are replacing WRAP to justify these attributes.
- Planning For a New SP
- Install SP Software
- Configure the SP
- Register the SP
- Test the SP
- Advanced Configuration
Hosted Service Providers
If you are not running your own servers, you will need to make sure your hosting provider is prepared to setup and run a Shibboleth Service Provider on your behalf.
At this time (April 2015), OIT web hosting supports Shibboleth SPs as follows:
- AFS-hosted servers: generally available.
- CPanel-hosted servers: generally available.
- Drupal-hosting servers: not yet available.
- Wordpress-hosting servers: partially available.
- WolfWare Classic: generally available.
You can verify that Shibboleth is setup and running correctly for your domain using this guide: Testing htaccess on a Hosted Server.
Migrating .htaccess files
Once your service is running a Shibboleth SP, you will need to convert any .htaccess config files from WRAP to Shibboleth. You may also need to re-write some code to look for the user attributes under different environment variable names.
For more information:
We also provide a Perl Script to Help Find WRAP Entries. This may be useful to people who are trying to upgrade a lot of directories on a single site or multiple sites.
Your applications have probably been getting the Unity Userid from WRAP from one of the environment variables: the Apache standard REMOTE_USER, or the WRAP standard WRAP_USERID.
The default Shibboleth configuration populates this variable with the value from SHIB_EPPN, which is "firstname.lastname@example.org". You have three options:
Modify your programs to expect the new scoped format of this data. This is the recommended path, as it will allow you to consider accepting authentications from institutions other than NC State.
Modify your programs to use SHIB_UID instead of REMOTE_USER. This variable passes "unityid" unscoped, so it should work the same way that you expected.
Modify your Service Provider configuration to populate REMOTE_USER with the value provided by SHIB_UID. Doing so will make your server different from others running on campus, and could cause confusion if you ever try to migrate to another service provider.
If you must take this route: modify your shibboleth2.xml file, find the ApplicationDefaults tag, and change the list under REMOTE_USER="..." Remember to restart your shibd and httpd processes after any changes.
This variable is obviously not used by Shibboleth. However, to make the transition a little easier, our standard Attribute Mapping configuration file for Shibboleth already provides a map for SHIB_UID to WRAP_USERID. You can continue to use this alias as long as it is still supported by the SP software. (The Wiki warns that this feature is deprecated now.)
In the longer term you should:
Modify your programs to use SHIB_EPPN and to expect the new scoped format of this data. This is the recommended path, as it will allow you to consider accepting authentications from institutions other than NC State.
Modify your programs to use SHIB_UID instead of WRAP_USERID. This variable passes "unityid" unscoped, so it should work the same way that you expected.