ArnesAAI

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).

References

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:

eduPersonPrincipalName (username, e.g. user@org-domain.si)
eduPersonTargetedID (persistent pseudonymous ID, e.g. p0e7efdd37e431b5b0ecfc868212691dfcaf43f7)
eduPersonAffiliation (e.g. staff)
eduPersonPrimaryAffiliation (e.g. member)
schacHomeOrganization (e.g. org-domain.si)
schacHomeOrganizationType (e.g. faculty)
schacExpiryDate (UTC date and time e.g. 20071030235959Z)

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 "@org-domain.si" to any existing usernames.

Limitations:

web application is not allowed to request/query attributes!
attribute set is released only when login takes place, further attribute requests/updates and requests for additional attributes are not possible!
communicating directly with IdP is not an option!
There is just one attribute, which is released in every single attribute set and that is eduPersonTargetedID. All the other attributes are optional

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.

All users with an AAI login

AuthType shibboleth
ShibRequireSession On
require valid-user

All university users with an AAI login

AuthType shibboleth
ShibRequireSession On
require homeOrganizationType university

All staff members from university with an AAI login

AuthType shibboleth
ShibRequireSession On
require affiliation staff
require homeOrganizationType university

Login page where user can login with local username or with AAI login (lazy session with landing page)
```
AuthType shibboleth
ShibRequireSession Off
require shibboleth
```
Advanced Development with Lazy Sessions

One advanced feature of Shibboleth provides some control at runtime over applications to initiate the user login process. With some systems, protecting content is a binary choice, on or off. With Shibboleth, applications can allow session at runtime for a user, and obtain attributes that are present, but do not require a session. This, so-called "lazy session", is only established if the application decides at runtime that a session is needed. This provides most of the advantages of a more API-oriented design in which an application would invoke a "doLogin" function without introducing actual language-dependent features into the system. It works with any application development tool because it relies on HTTP redirection alone to invoke the session.

If the user's session times out, the application will need to detect this by recognizing that attributes are no longer provided with the request and take appropriate action by requesting a new session to be created. Essentially the automatic redirection features of the Shibboleth software are turned off and the application is responsible for that process. In other aspects, nothing else is different.

For detailed information on the use of this feature with Shibboleth 2.x, see this wiki topic.

NOTE: Lazy session is usually triggered manually by user, when opening a specific URL, e.g.:

https://sp.arnes.si/Shibboleth.sso/DS?target=https://sp.arnes.si/system/login

where target represents webapp's landing 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:

PHP (mod_php):

```
$_SERVER["eduPersonPrincipalName"]
```
```
$_ENV["eduPersonPrincipalName"]
```

Perl (CGI/1.1)

```
$ENV{'eduPersonPrincipalName'}
```
```
getenv("eduPersonPrincipalName")
```

Python

req.add_common_vars()
env, si, so = apache.setup_cgi(req)
req.subprocess_env["eduPersonPrincipalName"]

Ruby

cgi = CGI.new
puts cgi.header
ENV['eduPersonPrincipalName']

ASP.NET:

Request.ServerVariables("http_eduPersonPrincipalName")

Cold Fusion:
- ```
CGI.eduPersonPrincipalName
```
Java:
- ```
request.getHeader("eduPersonPrincipalName")
```
If you want to protect Java Applications with Shibboleth 2.x and if the applications should be able to read Shibboleth attributes, you have to do one of the following things:
1. Use the old Shibboleth 1.3 behaviour where attributes are stored in the web server environment as header variables. This can be done using an Apache directive called ShibUseHeaders On
2. Tell mod_jk, which is the bridge between Apache and your servlet container, to forward certain environment variables. This is an Apache configuration to pass particular environment variables:
```
JkEnvVar Shib-Application-ID
JkEnvVar Shib-Session-ID
JkEnvVar Shib-Identity-Provider
JkEnvVar Shib-Authentication-Instant
JkEnvVar Shib-SwissEP-UniqueID
JkEnvVar Shib-InetOrgPerson-givenName
JkEnvVar Shib-Person-surname
[...]
```
The reason for this is, that Shibboleth 2.x by default doesn't put the attributes as header variables into the web server environment but it uses environment variables directly. This has the effect that mod_jk won't forward the attributes anymore to the servlet container unless you use one of the above solutions. More information about this topic can be found on the Shibboleth Wiki.
In case of using mod_jk, be aware that mod_jk will handle ISO-8859-1 encoding only. Following example shows, how this limitation can be avoided (by using getBytes):
```
for(Enumeration en = request.getHeaderNames(); en.hasMoreElements();){
     String headerName = (String) en.nextElement();
     String headerValue = new String(request.getHeader(headerName).getBytes("ISO-8859-1"), "UTF-8");
	....
}
```

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:

Logout from application (non-AAI logout)
Local logout (logout from specific SP)
Global logout/SLO (logout from IdP and from all logged-in SPs)

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:

eduPersonScopedAffiliation
eduPersonPrincipalName
eduPersonUniqueId

have a special syntax. Each is a string-valued attribute of the form

value@scope

For example, the value of eduPersonPrincipalName for Internet2 staff is:

username@internet2.edu

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