Stanford University is in the process of migrating from its homegrown authentication system, WebAuth, to the widely deployed and feature-rich SAML-based authentication. This brings a lot of benefits, like better compatibility, wider application support and easy federation with other institutions.
There are multiple SAML (Security Assertion Markup Language) implementations, but this article is focuses on two of them, Shibboleth and SimpleSAMLphp.
Shibboleth is well-documented and there are Stanford UIT documentation pages with high level descriptions of how it fits into the Stanford infrastructure. In this article I will talk about the practical steps one has to take to migrate from WebAuth to Shibboleth or SimpleSAMLphp, how to set them up and what adjustments have to be made to the configuration files on the SP (Service Provider) side.
Parts of the article are a rehash of the official UIT Shibboleth documentation with some corrections and explanations of the steps pertinent to the topic of migration from WebAuth. The content is based on our client’s questions and the issues we encountered while performing these migrations for our clients.
Shibboleth
Shibboleth is probably the closest drop-in replacement for WebAuth you can get and it would work both as a way to secure particular directories/pages as well as an authentication method integrated into an application. Many popular open source applications such as Drupal and WordPress have modules for Shibboleth.
What has to change
Both WebAuth and Shibboleth are designed with Apache web server in mind, so with the transition to SAML you don’t have to change the web server or how your web sites are organized and configured. Both WebAuth and Shibboleth include Apache modules. In case of WebAuth these are mod_webauth and mod_webauthldap. The first is used for authentication and the second to query LDAP for additional information about the users, beyond their user name. Shibboleth has a single module, mod_shib, responsible for web server integration, but all the heavy lifting is done by a separate service called shibd, always running in the background.
Shibboleth does not require a separate module to obtain user information from LDAP because it is directly released by the IdP (Identity Provider). For the application the result will be the same set of server variables or, I’d rather say, almost the same. There are a few minor differences in the attributes when the default Shibboleth configuration is used, but it can be adjusted to mimic WebAuth fairly closely. One exception is a workgroup information. Both Shibboleth and WebAuth Apache modules can be configured to authorize users based on the membership in certain workgroups (suPrivilegeGroup in LDAP). The list of these workgroups is returned as a server variable. WebAuth can do it either as a single delimited string or as a set of variables named WEBAUTH_LDAPPRIVGROUPXX, where XX is an ordinal number. Shibboleth returns the same information as an array, so if your application relies on WebAuth returning groups as a set of variables, it has to be modified to take them as an array instead. In all other respects Shibboleth can be customized to behave exactly like WebAuth from the point of view of the application.
Installing Shibboleth
Installing Shibboleth on Linux is just a matter of getting a package from a repository.
Linux, Debian family
The package is available in public repositories as libapache2-mod-shib2:
# apt-get install libapache2-mod-shib2
This would install both Shibboleth service and Apache module. The configuration files will be in /etc/shibboleth directory.
Make sure the Apache module is enabled:
# a2enmod shib2
Linux, Red Hat family
There is no Shibboleth package in Red Hat or CentOS repositories, but you can use the one provided by SUSE (CentOS 6, Red Hat 6, CentOS 7, Red Hat 7). Just drop one of these files in your /etc/yum.repos.d. Stanford also mirrors these repositories on yum.stanford.edu (CentOS 6/Red Hat 6, 32-bit, CentOS 6/Red Hat 6, 64-bit, Red Hat 7/CentOS 7). Then install shibboleth package:
# yum install shibboleth
Copy Shibboleth service startup file to the init.d directory, enable and start the service:
# cp /etc/shibboleth/shibd-redhat /etc/init.d/shibd # systemctl enable shibd # systemctl start shibd
Enable the module in httpd.conf or create a corresponding file in /etc/httpd/conf.modules.d:
LoadModule mod_shib /usr/lib64/shibboleth/mod_shib_22.so
Generate certificate
Shibboleth signs assertions, so the next step is to generate a certificate for your SP (your server). Since the private key would always remain on the SP and the public key will be used only by IdP, there is no need to use commercial certificates for that. In fact, it is much better and more convenient to use self-signed certificate with a long lifespan. You can use openssl to create it, but conveniently Shibboleth offers a special utility for that. On Debian it is
# /usr/sbin/shib-keygen
while on Red Hat it is functionally identical
# /etc/shibboleth/keygen.sh
This is it. The utility would generate a private key and a certificate valid for 10 years, put them in the correct place and apply correct permissions.
Shibboleth configuration file
Main shibboleth configuration file is shibboleth2.xml. Download the linked version already preconfigured for Stanford IdP. This is an XML file and there are a few fields that you have to replace:
- PROVIDERID. This is an entity ID of you SP. Can be any string, which just have to be unique. To avoid collisions there is a convention to format entity ID as https://server.stanford.edu/shibboleth, where server is the name of your server in DNS.
- EMAIL. An email address for server support. Usually a mailing list of the support team.
- SSLKEY. sp-key.pem. This is the default file name of the key generated by shib-keygen.
- SSLCERT. sp-cert.pem. Default name of the certificate generated by shib-keygen.
In this file you also specify what would be returned as REMOTE_USER variable. By default it is eppn (EDU Person Principal Name), which is scoped as sunetid@stanford.edu. WebAuth, on the contrary, returns an unscoped user name. If you do not want to modify your application to deal with the scope, just add uid in front of eppn in ApplicationDefaults tag like this:
<ApplicationDefaults entityID="https://server.stanford.edu/shibboleth" REMOTE_USER="uid eppn persistent-id targeted-id">
Once the file is ready, restart the shibboleth and Apache services:
# systemctl restart shibd # systemctl restart apache2
If authentication to your application happens during the POST transaction, Shibboleth saves the POST data in memory (by default) and then passes it on to the application after the successful authentication and redirects to an IdP and back. The code which resubmits the data is in JavaScript and is located in /etc/shibboleth/postTemplate.html. By default it also creates a form for the users with no JavaScript support in their browsers. The form adds a field to the POST data which may interfere with your application. If you see this happening, you can edit the code in postTemplate.html to remove the INPUT button.
Metadata generation
Now you need to generate a metadata file, which contains the information about your SP and which will be installed on Stanford IdP. Download the metadata file from here:
https://server.stanford.edu/Shibboleth.sso/Metadata
Replace server with the name of your server. Your browser will download the file named Metadata, which is actually an XML file. Open this file in a text editor and verify the entity ID. It should match whatever you have entered in shibboleth2.xml configuration file. If you have just a single web site running on your server, the only thing you have to add is the contact information for the administrator of the server or preferably a mailing list for the group or administrators at the end of the file:
</md:SPSSODescriptor> <md:ContactPerson contactType="technical"> <md:GivenName>Our Team</md:GivenName> <md:EmailAddress>our_team@lists.stanford.edu</md:EmailAddress> </md:ContactPerson> </md:EntityDescriptor>
If you run multiple web sites on the same server, you have to add AssertionCounsumerService binding for each of them:
<md:AssertionConsumerService Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST" Location="https://website1.stanford.edu/Shibboleth.sso/SAML2/POST" index="1"/> <md:AssertionConsumerService Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST" Location="https://website2.stanford.edu/Shibboleth.sso/SAML2/POST" index="2"/>
In the downloaded metadata you’ll see AssertionConsumerService tag for a number of bindings. In 99% of the cases you’ll need only the first, HTTP-POST. HTTP-POST-SimpleSign is not used in the modern browsers. HTTP-Artifact and browser-post are the relics from SAML 1.0 era, which are not widely used any more, and in case of artifact require quite unorthodox Apache configuration. PAOS is used for non-browser clients and most likely that’s not what you need.
It is time to upload the metadata file to the Stanford IdP. Go to the Stanford SAML Configuration Manager web site. Click “Add New Service Provider” button, paste the metadata into the Metadata field, add your contact email. Enter the URL of your website into the Login URL field. If your administrator team has a workgroup, you can specify it in the Owning Workgroup field. This way anybody in your team would be able to update the metadata later. By default it would be only you. Login URL and Contact are required by IdP administrators to facilitate troubleshooting and audit. There is no technical reason them since all the necessary information for your SP is the metadata.
Attribute release and mapping
There is a set of attributes for the users which are released by default to any Stanford SP:
- uid
- eduPersonPrincipalName
- givenName
- sn
- displayName
- eduPersonAffiliation
- eduPersonScopedAffiliation
- suAffiliation
If your application needs anything beyond that, workgroup information, for instance, you have to request the attribute release. Here is also a major difference from WebAuth. When attributes are released to a WebAuth principal, they are released for all Stanford users. With Shibboleth this process is much more granular. The attributes are released only for a particular set of users defined by a workgroup. Obviously you’ll have to create this workgroup first, before requesting an attribute release. Also you must be an administrator of the workgroup for the request to go through. The workgroup must contain the list of all the users of your application. Once workgroup is created, submit a request to release a particular set of attributes to your SP by specifying its entity ID and a workgroup name.
You do not need to use LDAP access request form, like you did with WebAuth when you need only workgroup information, HelpSU ticket would suffice. You still have to submit LDAP access request for other attributes according to the current SAML Attribute Release Policy. In the form you can specify an attribute bundle, as you did for WebAuth. Unfortunately the actual list of attributes in each bundle is not documented by UIT yet. If in doubt you can specify the list of attributes you need.
The names of the attributes in Shibboleth configuration can differ from the ones returned by WebAuth, but can be easily adjusted by editing the file /etc/shibboleth/attribute-map.xml. First of all, download the version of attribute-map.xml file customized for Stanford IdP. Uncomment the Attribute tags you need in the “Examples of common attributes” sections. If you need to change the name of the attribute as it is returned by Shibboleth, change the “id” parameter value. You can add more attribute names as needed by your application. For instance, WebAuth returns the attribute WEBAUTH_USER and some applications may use it instead of REMOTE_USER. Shibboleth does not return such an attribute, but has an equivalent one, uid. You just need to change the name of this attribute in the attribute map from
<Attribute name="urn:oid:0.9.2342.19200300.100.1.1" id="uid"/>
to
<Attribute name="urn:oid:0.9.2342.19200300.100.1.1" id="WEBAUTH_USER"/>
Now your application would receive WEBAUTH_USER attribute and you don’t have to modify it in any way. Note that with this change you renamed the uid attribute to WEBAUTH_USER, i.e. there will be no uid attribute available on your SP any more. The same goes for other WebAuth-specific attributes like WEBAUTH_LDAP_SUDISPLAYNAMEFIRST and WEBAUTH_LDAP_SUDISPLAYNAMELAST.
Apache 2.4 configuration
Now you can re-configure your web sites for Shibboleth. If your site is protected by WebAuth, its configuration file would have the lines like that:
AuthType WebAuth Require valid-user
This would allow anyone with SUNet ID to login. The equivalent statement for Shibboleth would be:
AuthType Shibboleth ShibRequestSetting requireSession 1 Require shib-session
If you are authorizing users by workgroup it probably looks like this:
AuthType WebAuth Require privgroup stem:workgroup1 Require privgroup stem:workgroup2 WebAuthLdapPrivgroup stem:workgroup1 WebAuthLdapPrivgroup stem:workgroup2
Change it to:
AuthType Shibboleth ShibRequestSetting requireSession 1 require shib-attr eduPersonEntitlement stem:workgroup1 require shib-attr eduPersonEntitlement stem:workgroup2
Of course, this would work only if IdP is releasing eduPersonEntitlement attribute to your SP, i.e. you have submitted this HelpSU, which I was talking about in the previous section. If the user can access the web site over HTTP, you should redirect them over to HTTPS when authentication is required:
ShibRequestSetting redirectToSSL 443
Once the configuration is updated, restart Apache and test authentication on your SP.
SimpleSAMLphp
If you run a PHP application, Shibboleth may not be you best SAML option. Applications like Drupal or WordPress have a better support for SimpleSAMLphp. With SimpleSAMLphp you even don’t have to stick with Apache and may switch to any other web server, like nginx or even node.js. Nevertheless, since the topic is the migration away from WebAuth, it must be an Apache web server, which you are running and the discussion below assumes that you are. Setup is a bit more involved than with Shibboleth, but it pays off with simple application configuration.
Installation
There is no Red Hat SimpleSAMLphp package, so all the setup steps apply to the Debian Linux family. In general you are better off using Debian/Ubuntu for any web-related setups anyway.
# apt-get install simplesamlphp
The software gets installed in /usr/share/simplesamlphp and most of the configuration files end up in /etc/simplesamlphp. File file /var/lib/simplesamlphp/secrets.inc.php contains the administrative password to the SimpleSAMLphp configuration. You may want to change it right away.
Certificates
As with Shibboleth you have to create a key and a certificate for signing communications with an IdP. For this purpose create a directory /etc/simplesamlphp/certs and generate a key pair using openssl:
# openssl req -new -x509 -days 3652 -nodes -out sp-cert.pem -keyout sp-key.pem
Both key and certificate have to be readable by the web server, i.e. www-data user.
Since the certificate will be used only to communicate with IdP, self-signed certificate with a long term validity is the best. Don’t use your commercial server SSL certificate. With the self-signed you’ll be able to renew your server SSL certificates without the need to resubmit the metadata to the IdP every time you do that.
SimpleSAMLphp Configuration
Download customized configuration file config.php and replace the following placeholders:
- CONTACT. The name of the administrator or a team
- EMAIL. E-mail of the administrator or a team’s mailing list.
- DATABASE. The name of the application’s MySQL database.
- DATABASEUSER. The name of the application’s database user.
- DATABASEPASSWORD. Password for this user.
SimpleSAMLphp requires a datastore for session management. It is a common practice to use the same database as an application itself as a datastore. For this reason you see the database connection variables in the list above.
Download another customized configuration file authsources.php and replace the placeholder PROVIDERID with the entity ID of your SP. Again, this can be any string, but it is agreed to follow convention https://server.stanford.edu/simplesamlphp, where server is the hostname of your server.
And finally download saml20-idp-remote.php file and drop it into /etc/simplesamlphp/metadata directory.
Apache configuration
To the Apache configuration in each virtual host add
Alias /simplesamlphp /usr/share/simplesamlphp/www
Make sure that SimpleSAMLphp configuration is activated:
# a2enconf simplesamlphp
Restart Apache service.
Obtain metadata
Login to the SimpleSAMLphp admin page
https://server.stanford.edu/simplesamlphp/
with the password you configured in /var/lib/simplesamlphp/secrects.inc.php. On the Federation tab click the link [Show metadata] and copy the XML metadata for your SP to the clipboard. Alternatively you can download the metadata directly from the URL:
https://server.stanford.edu/simplesamlphp/module.php/saml/sp/metadata.php/default-sp
Go to the Stanford SAML Configuration Manager web site to upload it to the Stanford IdP as described above for Shibboleth. If you run multiple web sites on the same server, you have to add AssertionConsumerService tag for each of the sites:
<md:AssertionConsumerService Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST" Location="https://website1.stanford.edu/simplesamlphp/module.php/saml/sp/saml2-acs.php/default-sp" index="1"/> <md:AssertionConsumerService Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST" Location="https://website2.stanford.edu/simplesamlphp/module.php/saml/sp/saml2-acs.php/default-sp" index="2"/>
Attribute release and mapping
If you use SimpleSAMLphp with your application, you may need to adjust the attribute mappings. They are defined in the file /etc/simplesamlphp/attributemap/oid2name.php. The mapping is between LDAP oids and the names. You can adjust the names to fit what your application requires. The file is also useful as a reference.
Attribute release works the same way as with Shibboleth. If your application requires attributes beyond provide by IdP “for free”, you have to request it. For just a workgroup information submit a HelpSU request. Any other attributes require data owner’s approval.
Application configuration
The only thing left is to configure your application for SimpleSAMLphp. For instance, install a corresponding Drupal module “SimpleSAMLphp Authentication“. WordPress also has plugins like “SAML Single Sign On” and “WP SAML Auth”.
Of course, the migration to SimpleSAMLphp for such applications as Drupal or WordPress would be a significant change in the application configuration. Even if you chose to use Shibboleth plugin rather than SimpleSAMLphp, it would still be needed. That’s why it makes sense to go for a better option.
Conclusion
During the UIT Unconference last year there was a session devoted to the future of the web authentication at Stanford. It was held in a large room which filled up with system administrators from all across the campus with no free seats left. One of the questions asked was about the way WebAuth is used. Vast majority of the admins concurred that most of the times it is not deeply integrated into the applications and used trivially for limiting web site access to a certain group of users. As shown above, the migration to SAML authentication for such sites is not complicated and in many cases can be done with very minor changes to the application code or none at all.
Where to get more information
- Shibboleth documentation (https://wiki.shibboleth.net)
- SimpleSAMLphp documentation (https://simplesamlphp.org/docs/stable/)
- ITS Shibboleth documentation (https://uit.stanford.edu/service/shibboleth)
Whom to contact for help
The best way to get advice and help for particular setups is to post to the mailing list shibboleth-partners@lists.stanford.edu.
Alex Tayts (atayts@stanford.edu)