Vhosts: Securing access with Shibboleth

Guide to securing CAE's vhosts with Shibboleth authentication

Securing access to a CAE virtual hosted website has many options available to you. This guide will explain some of the subset of these options that require authentication. In particular it covers shibboleth authentication mechanisms.

For each of the methods mentioned below, the authentication requirement is done by creating an .htaccess file (note, the leading dot is important in the name). The .htaccess file directs the web server with a new set of directives to use. These directives are effective in the directory where the .htaccess file exists, and all directories below.
See http://httpd.apache.org/docs/current/howto/htaccess.html for more details.

Before you Begin

NOTE: Due to resource limitations and performance considerations it has become necessary for CAE to disable the shibboleth module (shib2) on all apache vhosts that don't need it. If you would like to make use of the features mentioned in this article, please use the vhost control panel tools at the https://my.cae.wisc.edu/tools/account/vhosts/ site to add the shib2 Apache module to your site. It may take a moment for the change to take effect on our webservers and up to 30 minutes for the various IDP servers (ours and DoIT's) to notice the change.

Require Authentication

Access to web sites can be authenticated with one of two authentication systems (called IDPs):

  • CAE login credentials (caeid)
  • Campus NetID credentials (netid)

Sites are protected with one of these authentication systems using one of three schemes:

  • Allow caeid authentication only.
  • Allow netid authentication only.
  • Allow authentication from either system by letting the user choose which to authenticate with. This is the default, but which you choose to use is up to you. We refer to it as anyid in the rest of this document.

NOTE: These are just the authentication systems. Authorization is handled separately (see below).

Require AnyID Authentication

Preconfigured

For convenience, if you place your content in an auth-or-uw directory it will be configured to allow either hosts from UW Campus networks or an anyid authentication.

Manual Configuration

In the directory you wish to protect, create an .htaccess file that looks like:

AuthType shibboleth
ShibDisable Off
ShibRequireSession On
ShibRequestSetting applicationId your.vhost.fqdn

Require valid-user
Header merge Cache-Control private

As mentioned above, if left unspecified, your site defaults to an applicationId of your.vhost.fqdn which equates to the anyid authentication scheme.

Require CAE Authentication

Preconfigured

For convenience, if you put your content in a directory called cae-auth, the system will apply the following shibboleth rules for you without any need to create an .htaccess file yourself.

Alternatively, if you place your content in an auth-or-engr directory it will be configured to allow either hosts from CoE networks or a caeid authentication.

Manual Configuration

In the directory you wish to protect, create an .htaccess file that looks like:

AuthType shibboleth
ShibDisable Off
ShibRequireSession On
ShibRequestSetting applicationId your.vhost.fqdn-caeid

Require valid-user
Header merge Cache-Control private

Require Campus NetID Authentication

Preconfigured

For convenience if you put your files in a directory called netid-auth, the system will apply the following shibboleth rules for you without any need to create an .htaccess file yourself.

Manual Configuration

In the directory you wish to protect, create an .htaccess file that looks like:

AuthType shibboleth
ShibDisable Off
ShibRequireSession On
ShibRequestSetting applicationId your.vhost.fqdn-netid

Require valid-user
Header merge Cache-Control private

Authorization

The last line in the preceeding block (Require valid-user) is the authorization portion of the configuration. It allows any successfully authenticated user to proceed. The Shibboleth Apache module exports attributes about the user to environment variables for the .htaccess rules and your application to use to enforce different authorization rules or other application specific behavior. Below are other examples of authorization options you may wish to consider. Note that they are primarily CAE login related as netid authentication does not export many attributes for most sites without negotiating the release of such information with DoIT first.

Restrict access to a CAE Group

The above examples restrict access to anyone that has a campus netid or caeid. If you want to restrict access to just a group of people, you can do that as well.

After you create a user group on https://my.cae.wisc.edu/ you can restrict access to the members of that group. For example, suppose we wish to restrict access to the members of a group we created called mygroup. We would create an .htaccess file that looks like:

AuthType shibboleth
ShibDisable Off
ShibRequireSession On
ShibRequestSetting applicationId your.vhost.fqdn-caeid

Require caegroup mygroup
Header merge Cache-Control private

Substitute mygroup above with your group name. Note that you can also use a space separated list of groups.

Restrict access to a particular account type

CAE supports many different account types including (though not limited to) things like students, staff, collaborators, etc. This example discusses how to restrict access to a page to a particular account type.

In order to comply with Shibboleth standards, we map our account types into scoped names like student@cae.wisc.edu, staff@cae.wisc.edu, member@cae.wisc.edu. The first two are what you'd expect, whereas the last behaves as a catch all for all others.

In order to restrict part of your site to just students and staff you can use something like the following in your .htaccess file:

AuthType shibboleth
ShibDisable Off
ShibRequireSession On
ShibRequestSetting applicationId your.vhost.fqdn-caeid

Require affiliation student@cae.wisc.edu staff@cae.wisc.edu
Header merge Cache-Control private

If your site has been authorized to receive such details for netid authentication, the following will also allow students and staff authenticating with netids or caeids by removing the scoped restriction and using anyid authentication:

AuthType shibboleth
ShibDisable Off
ShibRequireSession On
ShibRequestSetting applicationId your.vhost.fqdn

Require affiliation ~ ^student@.*wisc.edu$ ^staff@.*wisc.edu$
Header merge Cache-Control private

A note on attributes, affiliations, authentication, and authorization.

NOTE: The definition of student or staff is not particularly clear and may change based on who is providing the data (eg: CAE, DoIT, Registrar, etc.). This issue is further muddled by the expanding access to NetIDs. This is in general a good thing since it helps lessen the barrier for outside collaborators and the separation between authentication and authorization, but should be taken into consideration when constructing your authorization Require directives.

Restrict access to a Manifest Group

If you have configured a group using DoIT's Manifest service, you can use it to restrict access to members of that group using netid authentication. For this to work,

  1. Manifest must be configured to deliver ismemberof attribute information to your applicationId. To do this, you need to list the entityID corresponding to your vhost's netid applicationId. Use the table below to determin the format.
  2. You need to adjust your .htaccess rules to require the ismemberof attribute to be populated with a value matching your Manifest group. The format of this can best be seen on the Manifest documentation site listed below.

For example, you might have a set of .htaccess rules as follows:

AuthType shibboleth
ShibDisable Off
ShibRequireSession On
ShibRequestSetting applicationId your.vhost.fqdn-netid

Require ismemberof uw:domain:domain:mygroup

Header merge Cache-Control private

Substitute mygroup above with your Manifest group name and domain with the group's path in Manifest. Note that you can also use a space separated list of groups id path.

Accessing Login Information and other Attributes

Once a user has been authenticated, the shibboleth module will populate some CGI application environment variables (by default) holding any attributes about the user's session that the IDP has exposed to your application.

For example, the following PHP code will check that the user has a valid session and print the username that they authenticated with.

	if (!empty($_SERVER['Shib-Application-ID'])) {
		print $_SERVER['REMOTE_USER'].' has a valid shibboleth session!';
	}

Attributes that have multiple values are separated by a semicolon ;. The following PHP code will split them into an array and then check for a particular value.

	$uids = array_unique(explode(';', $_SERVER['uid']));
	if (in_array('bpktest', $uids)) {
		print 'uid bpktest found!';
	}

Further information on accessing attributes can be found here: NativeSPAttributeAccess.

Passive Authentication

The preceding configurations all handle protection and sessions for your web application before the request gets to it. This is referred to as "active" mode. However, some applications may wish to perform their own session management or mix and match public and private data or change the layout dynamically based on whether or not the user has a session. This can be accomplished with "passive" authentication mode.

To use passive mode requires two steps:

  • Add the following to your .htaccess rules:
    ShibDisable Off
    ShibRequestSetting applicationId your.vhost.fqdn
    ShibRequestSetting isPassive On
    
    NOTE: the applicationId can be any of the set presented above.
    This will enable the shibboleth module for that subpath of your site.
  • The user needs a way to get a session. This can be done by having them visit the appropriate SessionInitiator URL. For CAE these are of the following form:
    Authentication Scheme applicationId entityID SessionInitiator (Login) URL LogoutInitiator URL
    anyid your.vhost.fqdn https://your.vhost.fqdn/shibboleth https://your.vhost.fqdn/Shibboleth.sso/Login https://your.vhost.fqdn/Shibboleth.sso/Logout
    caeid your.vhost.fqdn-caeid https://your.vhost.fqdn/caeid-shibboleth https://your.vhost.fqdn/caeid-Shibboleth.sso/Login https://your.vhost.fqdn/caeid-Shibboleth.sso/Logout
    netid your.vhost.fqdn-netid https://your.vhost.fqdn/netid-shibboleth https://your.vhost.fqdn/netid-Shibboleth.sso/Login https://your.vhost.fqdn/netid-Shibboleth.sso/Logout

Additional parameters can be fed to the SessionInitiator URL to give it further instructions. For instance, to have the user be redirected back to a particular URL after they've obtained a session, you can add an html encoded target parameter in a GET query. Other sites may also need the isPassive parameter set for the SessionInitiator as well. Here's an example:
https://your.vhost.fqdn/Shibboleth.sso/Login?isPassive=On&target=https://your.vhost.fqdn/some/path

Similarly, the LogoutInitiator URL can be told to return you to a particular place after the local session has been removed. Here's an example:
https://your.vhost.fqdn/Shibboleth.sso/Logout?return=http://your.vhost.fqdn/some/other/path
NOTE: please see the further notes below on Logout and why this may be a bad idea and give the user a false sense of security. The default logout page has further instructions for the user to more completely logout.

Further information on passive mode and session creation can be found here:

Here's a more complete example of a known working passive authentication scheme that uses the special Require value of shibboleth:

  1. # .htaccess
    AuthType shibboleth
    ShibDisable Off
    ShibRequireSession Off
    ShibRequestSetting isPassive On
    ShibRequestSetting applicationId your.vhost.fqdn
    
    Require shibboleth
    
  2. Direct users to login to a url of the form https://your.vhost.fqdn/Shibboleth.sso/Login?isPassive=On&target=http://your.vhost.fqdn/some/path/with/the/given/htaccess/directives

Logout

Since sessions in shibboleth are actually split across the application (SP) and authentication source (IDP) in order to provide a single-sign-on (SSO) environment, logging out requires logging out of both the application and the IDP. For the application session, the URLs for logout are given in the table above. For IDPs both CAE and NetID have extended their IDPs to provide basic logout functionality at the following URLs:

Please note that all of these are subject to a slew of browser and cookie management issues as well.

Further information on logout can be found here:

Common Problems

This section tries to give some tips on handling common problems.

  • The following error message is received:
    Unable to map non-default applicationId to an ApplicationOverride, check configuration.
    This can happen for one of two reasons:
    1. Your site has just recently been configured for the shib2 Apache module. It takes up to 30 minutes for that change to filter through both our systems and then DoIT's.
    2. Your .htaccess file is specifying the wrong applicationId.

More Information

For more information on configuring the shibboleth module via .htaccess rules see the following:

For some information on using Shibboleth with UW's Manifest service please see the following:

See Also:




Keywords:vhost vhosts web website shib shibboleth secure login netid caeid caelogin groups affiliation logout sso attributes attrs manifest   Doc ID:22643
Owner:Brian K.Group:Computer-Aided Engineering
Created:2012-02-14 10:00 CDTUpdated:2016-07-05 14:12 CDT
Sites:Computer-Aided Engineering
Feedback:  2   0