Typical Use
In most cases, Shibboleth is just part of your web server, and works invisibly to your application based on the rules that you give it. By the time your application gets control, the user has already been authenticated and any attributes that were obtained are available to 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, but some common examples are below:
- CGI
- getenv("HTTP_AFFILIATION")
- Java
- HttpServletRequest.getHeader("affiliation")
- ASP
- Request.ServerVariables("HTTP_AFFILIATION")
- Cold Fusion
- CGI.AFFILIATION
The rules controlling what attributes are placed into which headers are controlled by the Shibboleth configuration and can be configured per-application using more advanced techniques. It is suggested that you use a common set of headers when possible to increase consistency across applications. Refer to this wiki topic for details.
REMOTE_USER
As you may already know, by long-held convention, a username or login name is typically accessed using the REMOTE_USER variable. Shibboleth supports this, but the situation is more complicated because a username is an attribute just like any other. Some applications may not be given access to it for privacy reasons, and many different attributes could plausibly be mapped to REMOTE_USER. Of course, only one attribute at a time is typically given that designation.
In most cases right now, new applications that need some kind of persistent user identifier should consider using eduPersonPrincipalName for this purpose. It is the most useful of the currently-supported username attributes because it is globally unique rather than only unique to LSU. This may not be important to you, but you never know when requirements might change. It also simplifies the task of supporting some kind of local account structure because those accounts won't conflict.
Applications that are already using the Kerberos principal name or "name.n" as an identifier should consider migrating to eduPersonPrincipalName, and this can usually be accomplished by appending "@lsu.edu" to any existing usernames. Applications that specifically relied on Kerberos ID may have to migrate a few of them into name.n format, but you can easily check for that in your database and OCIO can assist with conversion. In the event that migration is not feasible in the short run, the legacy username attributes can be made available for compatibility.
IIS Note
The use of REMOTE_USER directly is not supported because Microsoft restricts its use in ways that cannot be worked around. On this platform only, any attribute mapped to REMOTE_USER is actually placed in a header named HTTP_REMOTEUSER. This is a case where applications cannot be made portable between IIS and other web servers.
Advanced Development with Lazy Sessions
One advanced feature of Shibboleth is providing some control at runtime to applications over whether to initiate the user login process. With some systems, protecting content is a binary choice, on or off. With Shibboleth, applications can allow for a user session at runtime, and obtain attributes that are present, but 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 when attributes are no longer provided with the request and take appropriate action by requesting a new session be created. Essentially the automatic redirection features of the Shibboleth software are turned off and the application is responsible for that process. In other respects, nothing else is different.
For detailed information on the use of this feature, see this wiki topic.
