1. Shibboleth Overview

Shibboleth is a system designed to exchange information across realms for authentication and authorization. It provides a secure framework for one organization to transmit attributes about a web-browsing individual across security domains to another institution. In the primary usage case, when a user attempts to access a resource at a remote domain, the user's own home security domain can send certain information about that user to the service provider site in a trusted exchange. These attributes can then be used by the resource to help determine whether to grant the user access to the resource. The user may have the ability to decide whether to release specific attributes to certain sites by specifying personal Attribute Release Policies (ARP's), effectively preserving privacy while still granting access based on trusted information.

A service provider(SP) protects resources, while an identity provider(IdP) provides information about users from an organization to service providers. When a user first tries to access a resource protected by a Shibboleth SP, they are redirected to a service which asks the user to specify the organization from which they want to authenticate. If the user has not yet locally authenticated for that IdP, the user will then be asked to authenticate using any mechanism of that site's choosing. After the user authenticates, the Shibboleth IdP at the local institution generates a temporary reference to the user, known as a handle, for the individual and sends this to the SP. The SP can then use the handle to ask for attributes about this individual. Based on these attributes, the SP can decide whether or not to grant access to the resource. The user may then be allowed to access the requested materials.

There are several controls on privacy in Shibboleth, and mechanisms are provided to allow users to determine exactly which information about them is released. A user's actual identity isn't necessary for many access control decisions, so privacy often is needlessly compromised. Instead, the resource often utilizes other attributes such as faculty member or member of a certain class. While these are commonly determined using the identity of the user, Shibboleth provides a way to mutually refer to the same principal without revealing that principal's identity. Because the user is initially known to the service provider site only by a randomly generated temporary handle, if sufficient, the service provider site might know no more about the user than that the user is a member of the identity provider organization. This handle should never be used to decide whether or not to grant access, and is intended only as a temporary reference for requesting attributes.

1.a. Identity Provider (IdP)

There are four primary components to the identity provider side in Shibboleth: the attribute query handler, the SSO handler, the directory service, and an authentication mechanism. The attribute query and SSO handlers are provided with Shibboleth. An authentication mechanism will be included with 2.0, but until then, a <Location> block is used to trigger an authentication mechanism such as a local authentication system, Kerberos, or the web server's own basic auth. Shibboleth is able to interface with a directory or database exporting a JDBC or JNDI interface containing user attributes, and is designed such that programming interfaces to other repositories is straightforward.

From the identity provider site's point of view, the first contact will be the redirection of a user to the handle service, which will then consult the SSO handler to determine whether the user has already been authenticated. If not, then the browser user will be asked to authenticate, and then sent back to the assertion consumer service URL with a handle bundled in an attribute assertion. Next, a request from the Shibboleth daemon, shibd , will arrive at the attribute query handler which will include the previously mentioned handle. The IdP then consults the ARP's for the directory entry corresponding to the handle, queries the directory for these attributes, and releases to shibd all attributes the service provider is entitled to know about that user.

1.b. Service Provider (SP)

There are three primary components to the service provider side in Shibboleth: the assertion consumer services (ACS's), the Shibboleth daemon, shibd, which interfaces directly with identity providers, and the resource manager (RM). An implementation of each of these is included in the standard Shibboleth distribution. These components are intended to run on the same web server.

From the service provider's point of view, a browser initially makes a request for a Shibboleth-protected resource. The resource manager allows the service provider to step in, which will use the WAYF to acquire the name of an identity provider to ask about the user. The IdP will then reply with a SAML authentication assertion containing a handle, which the assertion consumer service then hands off to shibd. shibd uses the handle and the supplied address of the corresponding attribute query handler to request all attributes it is allowed to know about the handle. The resource manager performs some basic validation and analysis based on attribute acceptance policies (AAP's). These attributes are then handed off to the application or used internally to decide whether to grant access.

1.c. Where are you from? (WAYF)

The WAYF service can be either outsourced and operated by a federation or deployed as part of the service provider. It is responsible for allowing a user to associate themself with an institution of their specification, then redirecting the user to the known address for the SSO handler of that institution.

1.d. Federations

A Shibboleth federation provides part of the underlying trust required for function of the Shibboleth architecture. A federation is a group of organizations(universities, corporations, content providers, etc.) who agree to exchange attributes using the SAML/Shibboleth protocols and abide by a common set of policies and practices. In so doing, they must implicitly or explicitly agree to a common set of guidelines. Joining a federation is not explicitly necessary for operation of Shibboleth, but it dramatically expands the number of service providers and identity providers that can interact without defining bilateral agreements between all these parties.

A federation can be created in a variety of formats and trust models, but must provide a certain set of services to federation members. It needs to supply a registry to process applications to the federation and distribute membership information to the identity provider and service provider sites. This must include distribution of the PKI components necessary for trust between identity providers and service providers. There also needs to be a set of agreements and best practices defined by the federation governing the exchange, use, and population of attributes before and after transit, and there should be a way to find information on local authentication and authorization practices for federation members.

1.e. Relying Parties

The primary unit of trust between Shibboleth providers is the "relying party", which allows for definition of access controls based on a site and application basis. To an identity provider, an application protected by a service provider is a relying party, while service providers consider identity providers to be relying parties (it's a matter of perspective). Certificates, policies, and other aspects of an interaction are specified on the basis of the relying party, and may or may not vary between relying parties depending on the deployment's needs.

Each identity provider and service provider is assigned a URI, a unique identifier to enable control over configuration down to the level of an individual partner (a single relying party). By convention, this is termed a "providerId". More frequently, an entire federation will be viewed by an identity provider or service provider as a single relying party to simplify management. An individual identity provider or service provider with which this deployment exchanges information may sometimes be part of multiple relying parties if there are multiple trust agreements under which these transactions are performed. Care should be taken to avoid conflicting or inconsistent configuration in such cases.

1.f. Applications

Shibboleth "applications" are the primary unit of service provider configuration. Applications as viewed by the service provider implementation are not the same as those viewed by the browser user, and are not necessarily defined by the same metrics as in other contexts. An individual application represents a set of web resources that operates using the same attribute handling and trust configuration and shares a common session with the browser user. As a user navigates between resources on a server that cross an application boundary, a new session is established, though user interaction may not be required. As a consequence of the relationship between applications and sessions (which are tracked with a cookie), an application usually does not span more than one virtual host. Apart from cookie-based constraints, web resources can be aggregated into applications in arbitrary ways.

A single service provider deployment may support a large number of applications, but it need not register or publish information about each one with the identity providers it accepts information from. Instead it can communicate using a more limited set of distinct "providerId" values (often just one). This allows service providers with a complex internal configuration to be treated as a single entity by identity providers for the purposes of attribute release.

1.g. Sessions

Much of the service provider implementation is concerned with establishing, and subsequently maintaining, sessions with the browser user on behalf of the applications at the service provider. A session consists of a cookie passed between the browser and web server, associated with a security context. The context contains the user's authentication information, and generally a set of attributes that make up the user's identity. Each application maintains distinct sessions with the browser by means of separate cookies. It is important to note that all such sessions are independent and distinct: any session can exist with or without any other session, and the expiration of any one session does not imply the expiration of any other session. Shibboleth also does not support any logout functionality beyond the termination of individual application sessions by deletion of respective cookies; also, there is no way for the service provider to cause identity provider sessions, such as a user's SSO login, to expire. This will change for Shibboleth 2.0, as SAML 2.0 includes provisions for single logout.

A browser user accessing a Shibboleth-protected resource may have two outcomes: standard session establishment, and lazy session establishment. The standard session establishment mechanism in which Shibboleth protects the resource in all circumstances results in the establishment of a cookie-based browser session and a set of attributes cached for that application.
Shibboleth >=1.2 also supports so-called lazy session establishment, in which the resource may be accessed without prior authentication. This means the application must be intelligent enough to determine whether authentication is necessary, and then construct the proper URL to initiate a browser redirect to request authentication; if the application determines none is necessary or uses other authorization mechanisms, then the request for authentication may not need to be triggered. This complex functionality is mostly useful to protect a single URL with different access mechanisms, or to require authenticated access only in instances where the application deems it necessary.

Independently of this, a web-based application protected by Shibboleth may have a need to establish its own session with the user. This session may persist well beyond the Shibboleth session, and logouts from this session, if supported, will not terminate a Shibboleth session initiated to access the resource. Application administrators should carefully evaluate the expiration of all sessions to limit vulnerability to attacks or user negligence. Logging out of the entire desktop session is usually the only (relatively) foolproof logout mechanism on the web.

2. Planning

There are several essential elements that must be present in the environment to ensure Shibboleth functions well, both political and technical. Shibboleth is
entirely written in Java on the identity provider side. The Identity Provider is written entirely in Java, while the Shibboleth SP is written in C++ with a Java version in development.

2.a. Requirements

IdP:

A common institutional directory service should be operational; Shibboleth comes with JNDI and JDBC capabilities built in, which encompasses SQL and LDAP, and the Attribute Authority has a Java API which will allow specification of custom connectors to other types of data sources. This is discussed in detail in the Attributes configuration section.

A method to authenticate browser users must be in place, preferably in the form of an enterprise authentication service. Some form of an SSO or a WebISO service is not explicitly necessary for Shibboleth; however, it is highly recommended. Implementation details of this are discussed in the User Authentication configuration section.

Shibboleth is known to work on Windows, Linux, Mac OS X, and Solaris, but should function on any platform that has a Tomcat implementation.

A Java servlet container; Shibboleth has been tested extensively with Tomcat.

It is recommended that a web server such as Apache be deployed in front of Tomcat to provide authentication services and to control the flow of requests to Tomcat. There may be issues surrounding the number of maximum connections to the web server and to the servlet container.

SP:

An IIS or Apache webserver must be deployed which is capable of SSL and running Shibboleth.
Web applications must be modified to be able to rely on attributes supplied by Shibboleth. Often this will overlap with the same header variables set by other authentication schemes, such as REMOTE_USER .
Access control schemes can often be simplified and rewritten to take advantage of the inherent power of attribute-based protection.

2.b. Join a Federation

While it is not necessary for an identity provider to join a federation, doing so greatly facilitates the implementation of multilateral trust relationships. Each federation will have a different application process. When an identity provider is accepted into a federation, its information is added to the sites file used by the WAYF and service provider sites.

Attribute release and acceptance policies, the use and caching of attributes, and definition of commonly traded attributes are examples of specifications a federation may make. The default configuration that ships with Shibboleth is designed around a BilateralDeployment along with some commented-out portions intended for use in testing against InQueue. However, InQueue has been deprecated, and now use of TestShib or a similar test environment is recommended.

2.c. Security Considerations

Shibboleth's protocols and software have been extensively engineered to provide protection against many attacks. However, the most secure protocol can be compromised if it is placed in an insecure environment. To ensure Shibboleth is as secure as possible, there are several recommended security precautions which should be in place at local sites.

SSL use is highly recommended for protection of all flows. Federation guidelines should be considered when determining whether to implement SSL, and, in general, SSL should be used for interactions with client machines to provide the necessary authentication and encryption to ensure protection from man-in-the-middle attacks. It is likely to be mandatory that all password traffic or similarly sensitive data should be SSL-protected.
Many other attacks can be made on the several redirection steps that Shibboleth takes to complete attribute transfer. The best protection against this is safeguarding the WAYF service and ensuring that rogue service providers and identity providers are not used, generally by development of the trust model underneath Shibboleth. Shibboleth also leverages DNS for security, which is not uncommon, but attacks concerning bad domain information should be considered.
Information regarding identity provider users is generally provided by the authoritative enterprise directory, and the acceptance of requests from service provider applications can be carefully restricted to ensure that all requests shibd performs are authorized and all information the identity provider provides is accurate. Proper security measures should also be in place on directory access and population (see Access Control in the LDAP Recipe for more information). Use of plaintext passwords anywhere -- ever -- is strongly advised against.
Server platforms should be properly secured, commensurate with the level that would be expected for a campus' other security services, and cookie stores on client machines should be well protected.

2.d. Server Certs

In the Shibboleth architecture, the identity provider and service provider must each have various client and/or server KeysAndCertificates for use in signing assertions and creating SSL channels. These should be issued by a commonly accepted CA, which may be stipulated by some Federation rules. Different federations may require the use of different CA's.

2.e. Attribute Release Policies

The Attribute Authority maintains a set of policies called Attribute Release Policies (or ARP's) that govern the sharing of user attributes with Shibboleth service provider sites. When a user attempts to access a Shibboleth-protected resource, that resource's SP queries the user's IdP for all attributes to which it is entitled. shibd provides the URI of the SP and the URI of the requesting application. The attribute query handler finds the attributes associated with the browser user, determines an "Effective ARP" for this user, and then sends to the SP only the attribute-value pairs allowed in this policy.

An ARP may be thought of as a sort of filter for outbound attributes; it cannot create attributes or data that aren't identity providerally present, but it can limit the attributes released and the values those attributes may have when released. It does not change the information in the data sources in any way.

Each ARP is comprised of one or more rules that specify which attributes and values may be released to a given application and that SP. The assignment of rules to various service providers is quite flexible and includes mechanisms for specifying: that a rule should affect all service providers (default rule), exact SP names for which a rule is applicable, regular expressions against which SP names should be matched to determine if a rule is applicable, and individual applications that may span hosts, URL's, or even SP's as necessary.

Various ARP's may be combined in forming the Effective ARP. For instance, the Site ARP is administratively maintained and applies to all users for which the IdP is authoritative. User ARP's apply to a specific user only, and can be maintained either administratively or by the users themselves. All ARP's are specified using the same syntax and semantics.

2.f. Designate Contacts

Since Shibboleth deals both with daily technical and operational issues and also with contractual issues, a set of contacts should be set up to support the user base and to facilitate interactions with other Shibboleth sites and federation members. It is recommended that at least technical and administrative contacts be designated. These contacts are then supplied to the federation and optionally to relying parties individually to facilitate communications and troubleshooting.

2.g. Browser Requirements

A primary Shibboleth design consideration was to require very little or no modification to client machines. The only requirement is that a browser is used which supports cookies, redirection and SSL. Browser users will have to perform an additional click to submit the authentication assertion if JavaScript is not functional.

2.h. Clocks

NTP should be run on all web servers. SAML, like many SSO technologies, relies on reasonably close time synchronization across servers to detect replay attacks and stale messages. Because of this, any significant degree of ClockSkew can hinder the ability of users to access sites successfully.

2.i. Other Considerations

Especially for higher education, there are a handful of laws enacted which may have important ramifications on the disclosure of personal information and attributes. Since Shibboleth does not necessarily need to transmit identity, it is an ideal solution for many higher education situations. Nevertheless, all parties within the United States of America are strongly advised to consult the Family Educational Rights and Privacy Act of 1974(FERPA), and all other relevant state and federal legislation before deploying Shibboleth.

Browser not supported