Shibboleth Developers

[Nate Klingenstein <>]

(from Steve C - I've forwarded on this note from  Nate....)

Coders,

This represents my best attempt at a preliminary deploy guide.  I 
want to preface everything by saying that my experience in middleware 
is almost entirely on the theoretical face, with virtually no 
hands-on implementation or coding experience.  This in mind, I'd ask 
you all to review the layout of the document so far, the parts of the 
text that are relevant to your efforts, and to send me any 
information you're able which will help me begin to populate the rest 
of the document.

Thanks for your help,
Nate.

Shibboleth Deployment Guide

draft-internet2-mace-shibboleth-shib-deploy-00.txt
Nate Klingenstein
15 February, 2002
Comments should be directed to 
.


1.      Shibboleth Overview

	Shibboleth is a system designed to exchange attributes across 
realms for the primary purpose of authorization.  It provides a 
secure framework for one organization to transmit attributes about an 
indexically referenced principal 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 target 
site in a trusted exchange.  These attributes can then be used as a 
means of deciding access control to the resource by the same 
indexically referenced principal.
	When a user first tries to access a resource protected by 
Shibboleth, they are redirected to the a service which asks the user 
to specify the organization from which they want to authenticate.  If 
the user has not yet locally authenticated to a WebISO service, the 
user will then be redirected to their home institution's login page. 
After the user authenticates, the Shibboleth components at the local 
institution will generate a temporary indexical reference, known as a 
handle, for the individual and send this to the target site.  The 
target site then use the handle will ask for attributes about this 
individual, then, based on these attributes, decide whether or not to 
grant access.  The user may then be redirected to the requested 
materials.
	There are several controls on privacy in Shibboleth, and 
mechanisms are specified to allow users to determine exactly which 
information about them is released.  In many access control 
decisions, the actual identity isn't so important as other attributes 
that are then associated with the principle, such as faculty member 
or member of a certain class.  Because the user is known to the 
target site only by a randomly generated handle, if sufficient, the 
target site might know no more about the user than that the user is a 
member of the origin organization.  The handle should never be used 
to decide whether or not to grant access, and is intended only as a 
temporary means to request attributes.

   a.   Origin

	There are four primary components to the origin side in 
Shibboleth: the Attribute Authority (AA), the Handle Service (HS), 
the directory service, and the local sign-on system(SSO).  The AA and 
HS are provided with Shibboleth, and an open-source WebISO solution 
produced by the University of Washington known as Pubcookie is also 
supplied; the directory is provided by the origin site.  Shibboleth 
is designed to easily interface with legacy directory and sign-on 
systems, but this may require some degree of coding to implement.
	From the origin 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 system 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 target URL with a handle 
bundled in a SAML attribute assertion.  Next, a request from the 
Shibboleth Attribute Requester (SHAR) will arrive at the AA which 
will include the previously mentioned handle.  The AA then consults 
the ARP's for the directory entry corresponding to the handle, 
queries the directory for these attributes, and releases to the SHAR 
all attributes the SHAR is entitled to know about that user.

   b.   Target

	There are three primary components to the target side in 
Shibboleth: the Shibboleth Indexical Reference Establisher (SHIRE), 
the Shibboleth Attribute Requester (SHAR), 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 target's point of view, a browser will hit the RM 
with a request for a Shibboleth-protected resource.  The RM then 
allows the SHIRE to step in, which will use the WAYF to acquire the 
name of a handle service to ask about the user.  The handle service 
(HS) will then reply with a SAML attribute assertion containing a 
handle, which the SHIRE then hands off to the SHAR.  The SHAR uses 
the handle and the supplied address of the corresponding attribute 
authority (AA) to request all attributes it is allowed to know about 
the handle.  These attributes are then handed off to the RM, which is 
responsible for using these attributes to somehow decide whether to 
grant access based on attribute acceptance policies (AAP's).

   c.   Where are you from?  (WAYF)

	The WAYF service can be either outsourced and operated by a 
club or deployed as part of the SHIRE.  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 
handle service of that institution.

   d.   Clubs

	A Shibboleth club is a crucial part of the underlying trust 
required for function of the Shibboleth architecture.  A club is a 
group of organizations(universities, corporations, content providers, 
etc.) who agree to exchange attributes using the SAML/Shibboleth 
protocols.  In so doing, they must implicitly or explicitly agree to 
a common set of guidelines.  Joining a club is not explicitly 
necessary for operation of Shibboleth, but it dramatically expands 
the number of targets and origins that can interact without defining 
bilateral agreements between all these parties.
	A club can be created in a variety of formats and trust 
models, but must provide a certain set of services to club members. 
It needs to supply a registry to process applications to the club and 
distribute membership information to the origin and target sites. 
This must include distribution of the PKI components necessary for 
trust between origins and targets.  There also needs to be a set of 
agreements and best practices defined by the club 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 club members.

2.      First Steps

	There are several essential elements that must be present in 
the environment to ensure Shibboleth functions well, both political 
and technical.  Shibboleth is primarily written in Java, though C++ 
is used for some portions of the attribute authority.  These are the 
requirements for a successful Shibboleth implementation.

   a.   Origin

	i.   A common institutional directory service should be 
operational; Shibboleth comes with LDAP and MySQL abilities built in, 
and the attribute authority has a C++ API which will allow 
specification of interfaces with legacy directories.  This is 
discussed further in Chapter 5.
	ii.  A WebISO service should be available to provide 
authentication services.  While this is not explicitly necessary for 
Shibboleth, without a single-sign on solution of some form, users 
will have to repeatedly authenticate to the home organization for 
each new target application domain they wish to visit.
	iii. A web server must be deployed that can host a Java 
servlet and JSP apps.

   b.   Target

	i.   Currently, Shibboleth is only available as an apache 
module.  The target's web servers must be running Apache v1.3.x.

   c.   Join a Club

	While it is not necessary for a target or origin to join a 
club, doing so greatly facilitates the implementation of multilateral 
trust relationships.  Each club will have a different application 
process.  To join Club Shib, please fill out the application at 
http://middleware.internet2.edu/foo/ and submit this application to 
Renee Frost at .  (design a club metadirectory?) 
For more information on Clubs, refer to 1.d or the Shibboleth v1.0 
architectural document.

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

	i.   SSL should be used for all interactions with client 
machines to provide the necessary authentication and encryption to 
ensure protection from man-in-the-middle attacks.
	ii.  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 targets and origins are not used, 
generally by development of the trust model underneath Shibboleth. 
Shibboleth also leverages DNS for a fair deal of security, which is 
not uncommon, but attacks concerning bad domain information should be 
considered.
	iii. The identification and authentication of both origin 
users and target applications should be carefully performed to ensure 
that all requests the SHAR performs and all information the origin 
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 is 
advised against.
	iv.  Server platforms should be properly secured, and cookie 
stores on client machines should be well protected.

   e.   Server Certs

	In the Shibboleth architecture, the SHIRE, SHAR, HS, and AA 
must all have server certificates for use in signing assertions and 
creating SSL channels.  These should be issued by a commonly accepted 
CA, which may be stipulated by some Club rules.

   f.   Designate an administrative contact

	The contact will give other sites a business entry point to 
discuss matters related to interoperation.  This contact address 
should be given to any Clubs of which the organization is a member.

   g.   Browser Requirements

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

   h.   Clocks

	NTP should be run on all web servers, as with Shibboleth's 
short handle issuance time to protect against replay attacks, any 
degree of clock skew can hinder the ability of users to access sites 
successfully.

   i.   Consult Relevant Legislation

	Especially in higher education, there is 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 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.

3.      Installation

   a.   Origin
        i.   Deploy HS Behind WebISO
        ii.  Deploy AA alongside HS and directory
   b.   Target
        i.   Deploy SHIRE and SHAR
        ii.  Implement Resource Manager

4.      Getting Running

   a.   Origin
        i.   Design AA plug-ins for attributes(Java API)
        ii.  Establish default ARP's for community
        iii. MyAA
        iv.  WAYF
   b.   Target
        i.   Design AAP's
             A.   Algebratize Business Rules
             B.   Understand who can administer AAP's
        ii.  Add SHAR plug-ins for attribute processing(C++ API)
        iii. Club Shib Registry Files

5.      Advanced Configuration

   a.   Origin
        i.   ARP Syntax
   b.   Target
        i.   Caching
        ii.  Application Domains
        iii. AAP Syntax
   c.   Use of Shibboleth for other apps
   d.   Shibboleth's use of cookies
   e.   Non-standard attributes
   f.   Client Certs

6.      More Information

------------------------------------------------------mace-shib-design-+
For list utilities, archives, subscribe, unsubscribe, etc. please visit the
ListProc web interface at 

   http://archives.internet2.edu/

------------------------------------------------------mace-shib-design--