Perl Script to Help Find WRAP Entries
We've written a perl script that will look down a directory tree to try to find .htaccess files containing AuthType WRAP configuration entries. The script can do three things:
Simply report on where it found .htaccess files containing WRAP.
Attempt to rewrite those entries to use Shibboleth, saving the update as a new .htaccess.shib file.
If you trust the results, it can leave the updated .htaccess files in production, with a backup of the WRAP copy saved as .htaccess.wrap.
WARNING: This script will only look for and correct .htaccess entries. It will not find or modify any PHP code. You are still responsible for reviewing any code located in the protected directories.
Requirements and Usage
The script is written to run on a Linux machine with perl installed. It should not require any non-standard libraries. It will not run on Windows, as it relies heavily on Linux-like front-slash '/' characters in paths. It might work under CygWin.
You will need read permissions on the directory that you are scanning, and all subdirectories. You may need write permissions as well if you use either of the options to write updated .htaccess files.
- Download the script file here: find_htaccess_entries.pl.
- Make the script executable.
- Check that perl is found at /usr/bin/perl on your system, or edit the first line of the script to use the correct path.
Usage, per the internal help option:
Usage: ./find_htaccess_entries.pl [options] /path/to/doc/root -d dir where to write reports (default /tmp) -f fix htaccess files separately - as .htaccess.shib -F fix htaccess files in place - keeps backup as .htaccess.wrap -h show this help -r filename write report to this filename (default last part of docroot) -v verbose messages
Example 1: Reporting Only
This is an example run where we are looking for WRAP entries in an AFS web locker. Using '-v' so we can see the progress, which can take a little time in AFS.
./find_htaccess_entries.pl -v /afs/unity.ncsu.edu/web/w/weblocker Spidering /afs/unity.ncsu.edu/web/w/weblocker .......... ... (many more dots, its a deep dir) ... ......done Found htaccess files under /afs/unity.ncsu.edu/web/w/weblocker: htdocs/project1/.htaccess htdocs/project1/app/.htaccess htdocs/prj2/.htaccess ... (-v reports all .htaccess files found) ... Found WRAP in htdocs/project1/.htaccess Found WRAP in htdocs/project1/app/.htaccess Found WRAP in htdocs/prj2/.htaccess ... (-v reports when an .htaccess file contained WRAP code) ... Found 95 files with WRAP rules Wrote report to /tmp/weblocker.txt
Next, we can look at the report that it generated. It will show the full path to each .htaccess file that it found, along with a copy of the actualy WRAP code that it identified.
less /tmp/weblocker.txt /afs/unity.ncsu.edu/web/w/weblocker/htdocs/project1/.htaccess AuthType WRAP require affiliation ncsu.edu require user userid1 userid2 /afs/unity.ncsu.edu/web/w/weblocker/htdocs/project1/app/.htaccess AuthType WRAP require valid-user /afs/unity.ncsu.edu/web/w/weblocker/htdocs/prj2/.htaccess AuthType WRAP require user userid1 userid3 userid4
Example 2: Suggest Fixes
This example uses a temporary document root that we've setup to use with this script.
cd /tmp/weblocker ./find_htaccess_entries.pl -vf /tmp/weblocker Spidering /tmp/weblocker .....done Found htaccess files under /tmp/weblocker: docroot/anyusers/.htaccess docroot/optional/.htaccess docroot/someusers/.htaccess Found WRAP in docroot/anyusers/.htaccess ... fixed. Found WRAP in docroot/optional/.htaccess ... fixed. Found WRAP in docroot/someusers/.htaccess ... fixed. Found 3 files with WRAP rules Wrote report to /tmp/weblocker.txt
In this case, we've used lowercase -f to fix .htaccess files by writing a new .htaccess.shib file in the same directory. We can review the changes that were suggested by viewing those files.
ls -1 docroot/*/.htaccess* docroot/anyusers/.htaccess docroot/anyusers/.htaccess.shib docroot/optional/.htaccess docroot/optional/.htaccess.shib docroot/someusers/.htaccess docroot/someusers/.htaccess.shib cat docroot/anyusers/.htaccess.shib AuthType shibboleth <IfVersion < 2.3> ShibCompatWith24 On </IfVersion> ShibRequestSetting requireSession true require shib-session cat docroot/someusers/.htaccess.shib AuthType shibboleth <IfVersion < 2.3> ShibCompatWith24 On </IfVersion> ShibRequestSetting requireSession true require shib-user email@example.com firstname.lastname@example.org cat docroot/optional/.htaccess.shib AuthType shibboleth <IfVersion < 2.3> ShibCompatWith24 On </IfVersion> ShibRequestSetting requireSession false require shibboleth
Example 3: Fix Everything
This example uses the same temporary document root as above.
cd /tmp/weblocker ./find_htaccess_entries.pl -vF /tmp/weblocker Spidering /tmp/weblocker .....done Found htaccess files under /tmp/weblocker: docroot/anyusers/.htaccess docroot/optional/.htaccess docroot/someusers/.htaccess Found WRAP in docroot/anyusers/.htaccess ... fixed. Found WRAP in docroot/optional/.htaccess ... fixed. Found WRAP in docroot/someusers/.htaccess ... fixed. Found 3 files with WRAP rules Wrote report to /tmp/weblocker.txt
In this case, we've used the uppercase -F to force the fixes to replace the existing .htaccess files. These changes are immediately live. The original .htaccess files are saved as .htaccess.wrap.
ls -1 docroot/*/.htaccess* docroot/anyusers/.htaccess docroot/anyusers/.htaccess.wrap docroot/optional/.htaccess docroot/optional/.htaccess.wrap docroot/someusers/.htaccess docroot/someusers/.htaccess.wrap
This script only makes changes to the .htaccess files. When converting a PHP-based site to Shibboleth, you will also need to review the PHP code to ensure it is not looking for the WRAP_USERID environment variable to see if a user has logged in. You should change those to SHIB_UID to see the same results. Even better, if you can, update your code to accept scoped userids via SHIB_EPPN instead. That way if you even need to accept users from outside of NCSU, your code is ready to support other scopes.
This script assumes you are running on an Apache 2.2 webserver. It uses the compatibility flag "ShibCompatWith24 On" to allow us to use the new configuration structures. When you later upgrade the webserver to run Apache 2.4, it will throw an error when it sees this flag. You will get 500 Server Error messages when visiting an directory with one of these .htaccess files.
To fix this problem, go to each of the .htaccess files and remove or comment out the "ShibCompatWith24 On" line when you upgrade to Apache 2.4.