Perl Script to Help Find WRAP Entries
Overview
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 userid1@ncsu.edu userid2@ncsu.edu
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
Possible Problems
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.