Documentation for WebAAI developers

WebAAI is not designed to be an application development tool in the usual sense. It's middleware, like your web server, ideally doing its job without making the developer consciously aware of it. The reason for this is that WebAAI has no interest in dictating to you how you should develop your applications. It does not matter if they are implemented in PHP, Perl, Java or ASP.NET, until your web server is configured as an AAI service provider. By the time your application gets control, the user has already been authenticated and the attributes that were obtained are available for your application in the same way as other information about the request, in so-called ""request" or "header" variables. The specific way you access them depends on your programming environment (see some common examples below).

1. Protecting web application with AAI

It is the resource administrator's responsibility to configure the correct access rules for a protected resource. A resource can be either protected with acces rules defined in the web server configuration or by the application itself by checking certain attributes. In both cases, a Shibboleth session must be enforced on the file, location or directory to protect. Second, there must be an authorization rule based on attributes that determines how the access is granted.

When using web server access rules, there are three ways to define rules:

Web Server config file
E.g. you can set rules for a directory, file or loacation directly in the Apache configuration file httpd.conf.
The downside of this method is that the web server has to be restarted each time the configuration file is changed.
Directory config file
In Apache you can use '.htaccess' files in directories to overwrite the web server static configuration settings. The rules defined in that file are dynamic, which means that they can be changed without restarting the web server. This can also be used to set Shibboleth access rules.
Be sure to check the directory for which you use a '.htaccess' file, if it is configured with 'AllowOverride AuthConfig' file to allow usage of '.htaccess' files.
The downside of this method that you cannot protect locations but only existing files and directories.
XML Access rules in Shibboleth config (for IIS)
Needed expecially for the IIS web server, there is a way to define access rules directly within the Shibboleth configuration file or in a linked external file that contains access rules which are defined with a special XML syntax. The inline access rules as well as the externally linked file are loaded dynamically by Shibboleth and thus are also suitable to protect locations for Apache.

Once your resource is ready for use, you have to configure access rules which protect your resource properly.

1.1 Attribute Release Policy

The Attribute Release Policy is set by IdP and it states which attributes are released to which Service Providers (SP).
After users's successful login at IdP, user's attribute set is released via SAML assertion to SP. Then SP puts attributes in environment variables or HTTP Header which makes them accessible to the web application (see examples bellow).

Common attribute set:

In most cases, new applications that need some kind of persistent user identifier should consider using eduPersonPrincipalName for this purpose. It is the most useful option of the currently supported username attributes, because it is globally unique.

Applications that are already using the username or "uid" as an internal identifier should consider migrating to eduPersonPrincipalName, and this can usually be accomplished by appending "" to any existing usernames.


1.2 Examples of Apache Access Rules for Shibboleth SP

Once you have set up your Service Provider, you can protect every resource on that web server, either with web server access rules or within the application itself.

For testing purposes (in Apache) it is OK to start with the most simple access rule that grants access to any user with a valid AAI login and redirects all non-ssl http requests to https before being processed by Shibboleth, which is recommended:

AuthType shibboleth
ShibRequireSession On
ShibRedirectToSSL 443
require valid-user
In continuation some common rules are shown, together with a description of what effect they have.
More information on this topic can be found in the corresponding Shibboleth Wiki page.

1.3 <Location> tag can protect the whole application directory structure or just selected files/folders.

<Location "/oneapp/index.php">
<Location ~ "/onedir">
<Location ~ "/secdir">
LocationMatch expects a regex. As it is it will match a lot more than intended (e.g. /some/completely/unrelated/secdirfoo/bar). Drop the '~' character to get the intended behaviour. If you really wanted to use regexes you could replace both of the above directives with e.g.
<Location ~ "^/(onedir|secdir)/">
or -- if it really is a directory in the filesystem -- even better with a Directory (or DirectoryMatch) directive, which will be in effect for all requests reaching this directory, no matter what the requested URI looks like, what vhost they matched, etc.

2. Retrieving attributes from environment variables or HTTP Headers, examples:

Recommendation: application should store received attributes to it's session scope. Since attributes are sent to SP whenever user logs in, there is no need to store them permanently.

3. Logout

Logout can be "local" or "global". Local logout means that the SP's session is removed, but no communication with the IdP or other SPs is involved. Global logout implies that the IdP is also informed about the logout operation. The SP software includes user interface support for presenting a different template depending on which kind of logout takes place. Types of logout:

Exiting the browser remains the easiest and safest way of ensuring that a Shibboleth session is terminated.

Bear in mind to logout from applications which are NOT entirely protected by SP (they handle sessions themselves).

Preparing a Web Application for Single Logout

A web application developer should do one of two things to support single logout when using Shibboleth. The easiest is to remove all application level session management and rely solely on the Shibboleth SP's session management. In addition to gaining SLO support the modified application will immediately gain new session related features as they are added to the Shibboleth product and eliminate any confusion that may occur if the application's session's configuration differ from those of the Shibboleth SP configuration (e.g. different session timeouts). Web applications that do not rely on the Shibboleth SP session management will need to index their sessions by means of the Shibboleth session ID, provided by the SP in the Shib-Session-ID header. Then they must implement a callback script, that will be invoked when the SP receives a logout request, that will be destroy the user's session. Note, however, that the application MUST NOT assume that the incoming request bears the session cookie and the script must be designed with that in mind. Refer to NativeSPLogoutInitiator in references box. Check References box for more details.

4. Protect Multiple Applications with one SP

In most cases there will be only one service or application running on server, but in some there are requirements to run multiple applications on single web server. When creating an additional application in the configuration refer to steps 1 and 2. Step 1: Create and name the application via <ApplicationOverride> and the id property, Step 2: Map the applicable resources using a matching applicationId property.

Refer to Native SP Application Override for any further infromation and examples regarding Shibboleth and web server configuration.

5. A complete list of Shibboleth Apache directives and their values is below:

AuthType <string>

Use shibboleth for direct invocation, or Basic plus the ShibBasicHijack option described below.

ShibBasicHijack <on/off>

Controls whether Shibboleth should or should not ignore requests with AuthType Basic . Defaults to off.

AuthGroupFile <pathname>

Same as mod_auth ; collects values found in REMOTE_USER into a named group for access control. An attribute must be mapped to REMOTE_USER for this to work (defaults to eduPersonPrincipalName). mod_auth will not support group files when the Shibboleth module is loaded, since they share the same command.

ShibRequireSession <on/off>

Controls whether to require an authenticated session before passing control to the authorization phase or the actual resource. Defaults to off .

ShibRequireSessionWith <SessionInitiator_id>

Initiate a session using a specific SessionInitiator if no session exists.

ShibApplicationId <ApplicationId>

Set ApplicationId for this content.

ShibRequireAll <on/off>

Controls whether all Require rules specified must be satisfied before access to the resource is granted. Defaults to off , which means any single rule can be satisfied, the usual Apache behavior.

ShibDisable <on/off>

Disable all Shibboleth module activity here to save processing effort. Defaults to off . note: if a require statement is set, there needs to be another AuthType defined to handle it.

ShibRedirectToSSL <portnumber>

When this directive is set all non-ssl http GET or HEAD request are automatically redirected to https before processing by Shibboleth. Other methods (like POST) are presented an error page to block access. This is highly recommended in combination with setting your cookies to secure as it will prevent looping and enhance security. Of course you'll set it as ShibRedirectToSSL 443 most of the time. (available from v1.3d)

ShibURLScheme <http/https>

Used in advanced virtual hosting environments which need to generate SSL redirects from virtual servers that use only HTTP (eg when offloading SSL to another machine). With this directive you can force Shibboleth to send out a redirect to the HANDLER (eg Shibboleth.sso) on https, even though it runs on http when looking at the local machine. Supplements the Apache ServerName and Port commands with this missing option. Defaults to a null value in which the scheme for redirects is based on the physical connection to the server. This is a server-level command, while the rest of the commands listed are content commands that can appear anywhere.

ShibExportAssertion <on/off>

Controls whether the SAML attribute assertion provided by the AA is exported in a base64-encoded HTTP header, HTTP_SHIB_ATTRIBUTES . Defaults to off .

6. Shibboleth scope check:

Along with cross-domain SSO, attribute sharing is a primary benefit of federated access to resources. To facilitate the sharing of attributes, Federation participants conform to the MACE-Dir SAML Attribute Profiles, which specify the syntax of SAML attributes "on the wire." The scoped attributes:

have a special syntax. Each is a string-valued attribute of the form
For example, the value of eduPersonPrincipalName for Internet2 staff is:
As illustrated in the previous example, a scope is typically a DNS domain. In the case of eduPersonUniqueId, the scope actually is a DNS domain by definition.

Acceptance of Scoped Attributes

After receiving a scoped attribute from the IdP, some SP software can be configured to compare the asserted scope to the scope value(s) in metadata. The scoped attribute is accepted by the SP if and only if the asserted scope matches a scope value in metadata. The Shibboleth SP software is configured this way by default. Other SP software may require explicit configuration or in some cases may not support the <shibmd:Scope> element at all.

Source: Scope in Metadata @Internet2 wiki