Shibboleth Origin Deployment Guide

From: cantor Date: Wed, 18 Jun 2003 05:35:54 +0000 (+0000) Subject: Moved to doc folders X-Git-Tag: 2.4~2328 X-Git-Url: http://www.project-moonshot.org/gitweb/?a=commitdiff_plain;h=a104587aae51423f5970050868a1325ae505b3b0;hp=aab95bcd2c47b5fd6af98280bd057bd3d90814c7;p=shibboleth%2Fsp.git Moved to doc folders git-svn-id: https://svn.middleware.georgetown.edu/cpp-sp/trunk@518 cb58f699-b61c-0410-a6fe-9272a202ed29 --- diff --git a/doc/DEPLOY-GUIDE-ORIGIN.html b/doc/DEPLOY-GUIDE-ORIGIN.html new file mode 100644 index 0000000..98f1b7c --- /dev/null +++ b/doc/DEPLOY-GUIDE-ORIGIN.html @@ -0,0 +1,2485 @@ + + + + + + + Shibboleth Origin Deployment Guide + + + + + + +

Shibboleth Origin Deployment Guide

+ + Shibboleth Origin Deployment Guide
+ draft-internet2-mace-shibboleth-shib-origin-deploy-30.html
+ Nate Klingenstein
+ 12 June, 2003
+ Comments should be directed to ndk@internet2.edu.
+ +

This version of the deploy guide is for Shibboleth v1.0. For + documentation related to prior versions of Shibboleth, please + consult the appropriate branch in the Shibboleth + CVS.

+ +

Federations have been abstracted out from the Shibboleth + documentation. For further information on using Shibboleth in a + federation, refer to the federation guide.

+ +

Shibboleth v1.0 is stable and secure enough to deploy in + production scenarios. While attempts have been made to include all + functionality that would represent a break of interoperability with + previous versions in v1.0, be aware that future versions of + Shibboleth are likely to be developed and may include further + implementation of the architectural document, functional + enhancements, and user interface improvements.

+ +

Functionality which has been added since the previous + version (v0.8) includes:

+ +

+
Various improvements to error handling. Origin sites are now + able to supply a URL to a federation for users to be referred to + when Shibboleth encounters a problem. Targets will be able to + utilize this URL in error templates.
+
+
The SHAR may now store its session and attribute cache in a + back-end database in addition to the previously available + in-memory option. The method by which sites.xml is refreshed has been + modified to improve robustness.
+
+
Attribute acceptance policies have been greatly enhanced, + with filtering of attribute values by sites supported.
+
+
OpenSAML now populates AuthType element in the SAML Subject + element using a value specified by origin sites using a + configuration directive. This value describes the type of + authentication mechanism used at the origin site(e.g. Kerberos, + PKI, etc.). This value is made available on the target side as + another variable that may be used in authorization + decisions.
+
+
Origin sites whose HS certificate is not signed by one of a + federation's trusted roots are able to provide that federation + with the certificate; this cert can now be stored in the sites + metadata, and targets will be able to use this certificate to + validate the HS' signature.
+
+
The AA implementation has been improved with a powerful + attribute resolver. This should greatly simplify the process of + configuring the AA to support additional general attributes, + while Java classes may still be written for more complex + evaluations.
+

+ +

Before starting, please sign up for all applicable + mailing lists. Announcements pertinent to Shibboleth + deployments and developments and resources for deployment + assistance can be found here.

+ +

Please send any questions, concerns, or eventual confusion + to mace-shib-users@internet2.edu. + This should include, but not be limited to, questions about the + documentation, undocumented problems, installation or + operational issues, and anything else that arises. Please + ensure that you have the appropriate + .tarball for your operating system.

+
+

+
+
+ + +

Shibboleth Origin -- Table of + Contents

+
+ + +

+
Shibboleth + Overview
+ +
1. Origin
2. Target
3. WAYF
4. Federations
+
+
Planning
+ +
1. Requirements
2. Join a + Federation
3. Security + Considerations
4. Server + Certs
5. Attribute Release + Policies
6. Designate + Contacts
7. Browser + Requirements
8. Clocks
9. Other + Considerations
+
+
Installation
+ +
1. Software + Requirements
2. Deploy HS and + AA
+
+
Getting + Running
+ +
+
+
Advanced + Configuration
+ +
1. + ARP + Overview + +
  1. ARP + Processing
  2. ARP + Syntax
  +
2. Sharing + certificate/key pairs between Apache and Java + keystores (optional)
3. The Attribute Resolver
+
+
Troubleshooting
+ +
1. Basic + Testing
2. Logging
3. Common + Problems
+

+
+

+
+ + +

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

+ +

When a user first tries to access a resource protected by + Shibboleth, 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 to + a WebISO service, the user will then be redirected to their + home institution's authentication system. After the user + authenticates, the Shibboleth components at the local + institution will generate a temporary reference to the user, + known as a handle, for the individual and send this to the + target site. The target site can then use the handle to ask for + attributes about this individual. Based on these attributes, + the target 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 target site + only by a randomly generated temporary handle, if sufficient, + the target site might know no more about the user than that the + user is a member of the origin 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. 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 Pubcookie can be obtained from + www.pubcookie.org; the directory is provided by the origin + site. Shibboleth is able to interface with a directory + exporting an LDAP interface containing user attributes, and is + designed such that programming interfaces to other + repositories should be readily implemented. Shibboleth relies + on standard web server mechanisms to trigger local + authentication. A .htaccess file can be easily used to trigger + either the local WebISO system or the web server's own Basic + Auth mechanism, which will likely utilize an enterprise + authentication system, such as Kerberos.
+ +
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 an 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.
+

+ +

1.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 + authentication 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. The SHAR performs some basic validation and + analysis based on attribute acceptance policies (AAP's). + These attributes are then handed off to the RM, which is + responsible for using these attributes 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 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.
+

+ +

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 targets and origins + 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 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 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.
+

+
+
+
+

+
+ + +

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 origin side. These are the recommendations and + requirements for a successful implementation of a Shibboleth + origin.

+ +

2.a. Requirements

+ +

+
A common institutional directory service should be + operational; Shibboleth comes with LDAP capabilities + built in, and the Attribute Authority has a Java API which + will allow specification of interfaces with legacy + directories. This is discussed further in section 4.d.
+
+
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 + section 4.c.
+
+
Shibboleth is known to work on Linux and Solaris, but + should function on any platform that has a Tomcat + implementation.
+
+
It is recommended that a web server must be deployed that + can host Java servlets and Tomcat, although not explicitly + necessary, as Tomcat can still host an origin without it.
+

+ +

2.b. Join a Federation

+ +

+
While it is not necessary for a target or origin to join a + federation, doing so greatly facilitates the implementation of + multilateral trust relationships. Each federation will have a + different application process. When an origin is accepted into a + federation, its information is added to the sites file used by the + WAYF and target sites.
+ +
It may be necessary to join multiple federations + depending on the sites with whom you wish to exchange + attributes and the terms under which these interactions will + take place. An origin site exists within the context of a + single federation, while a single target may accept assertions + issued by multiple federations if they are all recognized by + the SHAR. If an organization wishes to be a member of + multiple federations, it must run a separate origin site for + each federation, including a separate AA and HS.
+ +
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. For more information on federations, please refer to + the Deployer's Guide to Federations and the Shibboleth v1.0 + architectural document.
+

+ +

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 optional for origin sites. 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 strongly + suggested that all password traffic or similarly + sensitive data should be SSL-protected. Assessment of the + risk tradeoff against possible performance degradation + should be performed for all applications.
+
+ +
+
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 security, which is not + uncommon, but attacks concerning bad domain information + should be considered.
+
+ +
+
Information regarding origin users is generally + provided by the authoritative enterprise directory, and + the acceptance of requests from target applications can + be carefully restricted to ensure that all requests the + SHAR performs are authorized 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 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 SHIRE, SHAR, HS, and AA + must all have various client and/or 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 + 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 target sites. When a user + attempts to access a Shibboleth-protected resource, that + resource's SHAR queries the user's AA for all attributes to + which it is entitled. The SHAR provides its own name and the + URL of the resource on behalf of which it is making the + request. The AA finds the attributes associated with the + browser user, determines an "Effective ARP" for this user, and + then sends to the SHAR only the attributes/values 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 + originally 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 target or set + of targets. The assignment of rules to various targets is + quite flexible and includes mechanisms for specifying: that a + rule should affect all targets (default rule), exact SHAR + names for which a rule is applicable, regular expressions + against which SHAR names should be matched to determine if a + rule is applicable, URL trees for which a rule is + applicable.
+ +
For each request, an Effective ARP is determined by + locating all ARP's applicable to the designated user and + extracting each rule that matches the querying SHAR and + resource. Attributes and values that are specified for + release are included in the effective ARP, while those + specified for denial are blocked from release. See section 5.a.i for details on how ARP's are + processed.
+ + +
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 AA is answerable. 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.
+

+ +

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. Shibboleth employs a short handle + issuance time to protect against replay attacks. Because of + this, any significant degree of clock skew 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.
+

+
+
+

+
+ + +

3. Installation

+ +

3.a. Software Requirements

+ +

The following requirements are primarily recommendations + based on the most common ways to run Shibboleth. However, the + origin should be able to run under any servlet container + supporting Servlet API v2.3 and JSP specification + 1.2.

+ +

+
+
Apache + 1.3.26+ (<2.0)
+ +
Tomcat + 4.1.18-24 LE Java server
+ +
+ Sun J2SE v 1.4.1_01 SDK + +
+
Other versions of the JRE are not supported and are + known to cause errors when working with + certificates.
+
+
+ +
+ mod_jk + +
+
You may need to build mod_jk against Apache, which + will generally require GCC or a platform-specific C + compiler.
+
+
+ +
+ An enterprise authentication mechanism + +
+
Ideally, this will be a WebISO or SSO system such as + Pubcookie. The + minimal requirement is for the web server to be able to + authenticate browser users and supply their identity to + the Handle Server.
+
+
+ +
+ An enterprise directory service + +
+
Shibboleth currently supports retrieving user + attribute information from an LDAP directory. For + testing purposes, Shibboleth also supports a minimal + echo responder which will always return two pre-defined + attributes.
+
+
+
+

+ +

3.b. Deploy HS and AA

+ +

+
+
+
Ensure you have already obtained the proper .tarball.
+
+ +
+
The archive will expand into a shibboleth-origin-1.0/ + directory(/usr/local/ recommended).
+
+ +
+
Run the following command to move the Java files into + Tomcat's tree:
+ +
+ cp /usr/local/shibboleth-origin-1.0/dist/shibboleth.war + /usr/local/tomcat/webapps/ +
+
+ +
+
Tomcat 4.1.x requires that several Java jarfiles used + by Shibboleth be located in a special "endorsed" folder to + override obsolete classes that Sun includes with their JVM. + To deal with this problem use the following command, adjusting + paths as needed:
+
+ $ cp /usr/local/shibboleth-origin-1.0/endorsed/*.jar /usr/local/tomcat/common/endorsed +
+
Different versions of Tomcat or other Java servers may have + other locations in which to place these files or deal with this + problem. Refer to your application server's documentation to + find out how to properly endorse classes, if necessary.
+
+ +
+
Restart Tomcat, which will automatically detect that + there has been a new .war file added. This file will by + default be expanded into + /usr/local/tomcat/webapps/shibboleth.
+
+ +
+
Apache must be told to map the URL's for the + Shibboleth HS and AA to Tomcat. Two popular ways of doing + this are to include the following text directly in + httpd.conf, or to place Include + conf/mod_jk.conf in httpd.conf, and place + the following lines in + /etc/httpd/conf/mod_jk.conf:
+ +
+ --------- begin ---------
+ <IfModule !mod_jk.c>
+ LoadModule jk_module libexec/mod_jk.so
+ </IfModule>
+
+ JkWorkersFile + "/usr/local/tomcat/conf/jk/workers.properties"
+ JkLogFile "/usr/local/apache/logs/mod_jk.log"
+
+ JkLogLevel emerg
+
+ JkMount /shibboleth/* ajp13
+
+ --------- end --------- +
+
+ +
+
Tomcat's /conf/server.xml + ships by default with the Coyote/JK2 connector enabled, which + fails with Shibboleth due to the lack of support for REMOTE_USER. This connector must be + commented out. Then, uncomment and modify the traditional AJP + 1.3 connector as follows:
+ +
+
+
Add address="127.0.0.1" inside the + <Ajp13Connector> configuration + element to prevent off-host access.
+
+ +
+
Add tomcatAuthentication="false" to the + <Ajp13Connector> configuration element + to ensure that the user's identity is passed from + Apache to the servlet environment.
+
+
+
+
+

+
+

+
+ + +

4. Getting Running

+ +

4.a. Basic Configuration

+ +

+
The main configuration file for Shibboleth's origin side is + located in + /webapps/shibboleth/WEB-INF/classes/conf/origin.properties.. This file contains configuration information + for the origin side in several sections. The configuration + must be consistent with values elsewhere in the deployment, + such as the HS' certificate and with + directory access bindings, etc., or access errors may occur.
+ +
All pathnames are relative, and have an effective root + path of + $TOMCAT_HOME/webapps/shibboleth/WEB-INF/classes/. To + specify files outside of the webapp, specify a full URI, such + as file:///usr/local/shibboleth/.
+ +
Fields that are purple are optional; grey fields are + mandatory.
+ + +
These are the variables that may be specified for each + component of origin.properties:
+ +
+
General Configuration:
+ +
+
+ edu.internet2.middleware.shibboleth.hs.HandleServlet.issuer + = <domain name> +
+ +
+
Specifies the DNS name the HS should use for + itself in issuing assertions.
+
+ +
+ edu.internet2.middleware.shibboleth.hs.HandleServlet.siteName + = <URI> +
+ +
+
Specifies the the URI to use as the name of + the origin site as a whole. This field is primarily + meant to be populated in the context of the federation + in which the origin site resides, is intended to be + globally unique, and will typically be assigned by the + federation.
+
+ +
+ edu.internet2.middleware.shibboleth.hs.HandleServlet.AAUrl + = <url> +
+ +
+
Specifies the URL + at which the HS' corresponding AA may be + contacted.
+
+ +
+ edu.internet2.middleware.shibboleth.hs.HandleServlet.username + = <var> +
+ +
+
Specifies the HTTP request header that should be used + to acquire the user's principal name from the + authentication service. Defaults to REMOTE_USER.
+
+ +
+ edu.internet2.middleware.shibboleth.hs.HandleServlet.authMethod + = <uri> +
+ +
+
Specifes the URI used to populate AuthenticationMethod in the SAML + attribute assertion. This corresponds to the method used + to authenticate users by the authentication service used + by the HS. Some common authentication methods and + corresponding URI's are listed below; for a complete list, + please consult section 7.1 of the SAML 1.1 core + specifications or your federation's guidelines.
+ + + + + + + + + + + + + +
urn:oasis:names:tc:SAML:1.0:am:password The authentication was performed using a password.
urn:ietf:rfc:1510 The authentication was performed using Kerberos.
urn:oasis:names:tc:SAML:1.0:am:X509-PKI The authentication was performed using a + certificate and key issued to the end user. More + specific forms of PKI authentication such as SPKI and + XKMS are also assigned URN's in the SAML specs.
+
+
+ +
+
Assertion Signing:
+ +
+
+ edu.internet2.middleware.shibboleth.hs.HandleServlet.keyStorePath + = <pathname> +
+ +
+
Specifies the location of the Java keystore + containing the x.509 certificate and matching private + key to be used by the HS.
+
+ +
+ edu.internet2.middleware.shibboleth.hs.HandleServlet.keyStorePassword + = <password> +
+ +
+
Specifies the password to the referenced + keystore.
+
+ +
+ edu.internet2.middleware.shibboleth.hs.HandleServlet.keyStoreKeyAlias + = <alias> +
+ +
+
Specifies the alias used for accessing the private + key.
+
+ +
+ edu.internet2.middleware.shibboleth.hs.HandleServlet.keyStoreKeyPassword + = <password> +
+ +
+
Specifies the password used to retrieve the private key.
+
+ +
+ edu.internet2.middleware.shibboleth.hs.HandleServlet.certAlias + = <alias> +
+ +
+
Specifies the alias for the certificate + corresponding to the private key used by the HS. + Defaults to the private key's alias.
+
+
+
+ +
General AA Configuration:
+ +
+
+ edu.internet2.middleware.shibboleth.aa.AAServlet.authorityName + = <domain name> +
+ +
+
Specifies the name of the AA, which is typically + the domain name of the server running it.
+
+ +
+ edu.internet2.middleware.shibboleth.aa.AAServlet.passThruErrors + = <true/false> +
+ +
+
Specifies whether the AA should pass on internal errors + to the SHAR for debugging purposes. Defaults to false.
+
+
+ +
AA Attribute Resolution:
+ +
+
+ edu.internet2.middleware.shibboleth.aa.attrresolv.AttributeResolver.ResolverConfig + = <pathname> +
+ +
+
Specifies the location of the configuration file + for the resolver the AA uses to build attributes. + Defaults to /conf/resolver.xml. For + information on how to configure and use the attribute + resolver, consult section 4.e.
+
+
+ +
ARP Configuration:
+ +
+
+ edu.internet2.middleware.shibboleth.aa.arp.ArpRepository.implementation + = <string> +
+ +
+
References the type of ARP repository implemented. + Shibboleth provides a built-in ARP repository + specified by + edu.internet2.middleware.shibboleth.aa.arp. + provider.FileSystemArpRepository.
+ +
Note that the set of principals that an ARP applies + to is not expressed by the ARP itself, but rather the + implementation of the ARP repository. For example, if + the ARP repository were implemented in LDAP, the ARP's + that apply to a user would be attributes of that + user's personal LDAP entry, and the site ARP would be + an attribute of an entry representing the site. While + not performed by the built-in ARP repository, a + repository implementation might also implement group + ARP's; for example, in an LDAP directory, the user + entry might have some group membership attributes that + refer to group entries, and those group entries would + have ARP attributes, and all those ARP's would be + applicable.
+
+ +
+ edu.internet2.middleware.shibboleth.aa.arp.provider.FileSystemArpRepository.Path + = <pathname> +
+ +
+
Specifies the relative or absolute path to the + folder containing the ARP files.
+
+ +
+ edu.internet2.middleware.shibboleth.aa.arp.provider.FileSystemArpRepository.ArpTTL + = <seconds> +
+ +
+
Specifies the duration in seconds that ARP's may be + cached by the AA. Defaults to 0, or no caching.
+
+
+ +
Handle Repository Configuration:
+ +
+
+ edu.internet2.middleware.shibboleth.hs.HandleRepository.implementation + = <string> +
+ +
+
Specifies the method by which the HS and AA share + handles. These are by default passed by memory(which + can be specified explicitly using + edu.internet2.middleware.shibboleth.hs.provider. + MemoryHandleRepository), and may also be passed + using symmetric encryption with + edu.internet2.middleware.shibboleth.hs.provider.CryptoHandleRepository.
+
+
+ +
edu.internet2.middleware.shibboleth.hs.provider. + MemoryHandleRepository (specify + if + edu.internet2.middleware.shibboleth.hs.HandleRepository. + implementation is MemoryHandleRepository)
+ +
+
+
+edu.internet2.middleware.shibboleth.hs.BaseHandleRepository.handleTTL + = <seconds> +
+ +
+
Specifies the time in seconds for which issued handles + are valid. Defaults to 1800, or 30 minutes. The time + should be long enough to allow for clock skew and short + enough to protect against various attacks. Consult your + federation guidelines for further advice.
+
+
+
+ +
edu.internet2.middleware.shibboleth.hs.provider.CryptoHandleRepository (specify + if + edu.internet2.middleware.shibboleth.hs.HandleRepository. + implementation is CryptoHandleRepository)
+ +
In order to use the crypto repository implementation, you must + have a DESede secret key in a + keystore of type JCEKS. The + origin distribution includes a program that will automatically + generate such a key. In order to invoke it, run ./ant genSecret, which will create a + keystore in $SHIB_HOME/src/conf/handle.jks that + includes the key, with an alias of handleKey and a password of shibhs. If ./ant dist is run subsequently, this + keystore will be included in the webapp archive that is + created.
+ +
+
+
+ edu.internet2.middleware.shibboleth.hs.provider.CryptoHandleRepository.keyStorePath + = <pathname> +
+ +
+
Specifies the path to the keystore containing the + key used to encrypt passed principal identifiers.
+
+ +
+edu.internet2.middleware.shibboleth.hs.provider.CryptoHandleRepository.keyStorePassword + = <password> +
+ +
+
Specifies the password for the keystore.
+
+ +
+edu.internet2.middleware.shibboleth.hs.provider.CryptoHandleRepository.keyStoreKeyAlias + = <password> +
+ +
+
Specifies the alias for the appropriate encryption + key within the keystore.
+
+ +
+edu.internet2.middleware.shibboleth.hs.provider.CryptoHandleRepository.keyStoreKeyPassword + = <password> +
+ +
+
Specifies the password used to retrieve the key.
+
+ +
+edu.internet2.middleware.shibboleth.hs.CryptoHandleRepository.handleTTL + = <seconds> +
+ +
+
Specifies the time in seconds for which issued handles + are valid. Defaults to 1800, or 30 minutes. The time + should be long enough to allow for clock skew and short + enough to protect against various attacks. Consult your + federation guidelines for further advice.
+
+ +
+
+ +
Federation Configuration:
+ +
+
+ edu.internet2.middleware.shibboleth.audiences + = <URI's> +
+ +
+
Specifies a list of URI's that will be used for + the Audience field of + the SAML attribute assertion. All URI's listed will + be sent with any assertion issued by the AA. These + URI's are defined and provided by and correspond to + federations.
+ +
Note that the values of the URI's here must + match one of the policy URI's accepted by the + receiving target in the [policies] section of shibboleth.ini or + interoperation will fail by design. +
+
+ +

+
+ + +

4.b. Key Generation and Certificate + Installation

+ +

+
The SAML messages generated by the HS must be digitally + signed. Each HS must be issued a private and public keypair, + which is stored in a Java keystore. The current + implementation of Shibboleth requires the use of an ordinary + file-based keystore. The keytool program is included with the + Java development and runtime kits. Access parameters to the + keystore will need to be consistent with those specified in + origin.properties.
+ +
A sample keystore is included in the distribution and can + be found in + /usr/local/tomcat/webapps/shibboleth/WEB-INF/classes/conf/keystore + .jks with a password of shibhs. It is intended + to serve as an example and not as a production keystore.
+ +
The following commands will generate a new RSA keypair and + store it in the keystore.jks file, with a keyentry + alias of hs and new passwords of your choosing:
+ +
+ $ cd + /usr/local/tomcat/webapps/shibboleth/WEB-INF/classes/conf
+ $ keytool -storepasswd -keystore keystore.jks -new + <newpassword>
+ $ keytool -genkey -keystore keystore.jks -alias hs -keyalg + rsa -keysize 2048
+ +
+ +
You will be prompted for passwords during key generation + as needed, to access the keystore and assign the key itself + its own password. You will also be prompted for the + distinguished name components to associate with the key. This + DN will be placed in a self-signed certificate and will be + the name that is associated with your HS by Shibboleth. In + particular, the first component you enter for Name will be + the Common Name(when keytool asks for first and last + name, common name is intended), which in most cases should be + the hostname of the HS system. Note that a specific federation of + sites may dictate what type of key algorithm, key size, or + validity period is appropriate.
+ +
Once you have a keypair generated, the self-signed certificate + must be replaced with a certificate signed by a CA acceptable to + the federation you will be joining. Shibboleth is generally able to + climb trust chains to reach an intermediate CA's root CA. Note + that the intermediate CA's signing certificate must still be + signed by a root CA recognized by the federation.
+ +
To generate a certificate signing request for a CA, use + the following command:
+ +
+ $ keytool -certreq -keystore keystore.jks -alias hs + -file <csr-file>
+ +
+ +
The contents of <csr-file> can then be sent + to a CA for signing. You will receive a signed certificate in + return in a file. To install the new certificate into your + keystore, use the following command:
+ +
+ $ keytool -import -keystore keystore.jks -alias hs + -file <cert-file> +
+ +
Note that if the signing CA's certificate is not already + installed in your keystore as a trusted signer, you may need + to download the CA's root certificate and import it into the + keystore file under a different alias, using a command + similar to the above.
+ +
For information on sharing certificate/key pairs between Apache + and Java keystores see section 5.b..
+

+ +

4.c. Linking the Authentication System + to the HS

+ +

+
The interaction between the HS and the local authentication + system is implemented by supplying the HS with the identity of + the browser user. Most often, this will mean protecting the HS + servlet with some form of local authentication that populates + REMOTE_USER. Location blocks can be added to + httpd.conf, associating the appropriate + authentication mechanism with the URL of the HS servlet. The + following example demonstrates association of a very basic + authentication method with the HS:
+ +
+ <Location /shibboleth/HS>
+ AuthType Basic
+ AuthName "Internet2 Handle Service"
+ AuthUserFile /usr/local/apache/conf/user.db
+ require valid-user
+ </Location>
+ +
+ +
Note that .htaccess files cannot be used for this purpose + because URL's are "virtualized" by Tomcat.
+ +
It is recommended that the origin be tested at the end of + this process using the process described in section 6.a.
+

+ +

4.c.i. Enabling client certificate + authentication (optional)

+ +

+
+ +
Shibboleth supports client certificate authentication by + utilization of a filter that relies on the web server to do all + processing to ensure that the certificate is both valid and + appropriate for the application. An example deployment descriptor + is included with the Shibboleth distribution at $SHIB_HOME/webAppConfig/origin-client-cert.xml. + To enable the filter, add the following to the deployment + descriptor (web.xml):
+ +
+   <filter>
+     <filter-name>
+       Client Cert AuthN Filter
+     </filter-name>
+     <filter-class>
+       edu.internet2.middleware.shibboleth.utils.ClientCertTrustFilter
+     </filter-class>
+   </filter>
+
+
+   <filter-mapping>
+     <filter-name>
+       Client Cert AuthN Filter
+     </filter-name>
+     <url-pattern>
+       /HS
+     </url-pattern>
+   </filter-mapping>
+
+ +
By default, the filter pulls the principal name out of the CN of the cert's Subject by using regular expression + grouping. This may be done using patterns such as:
+ +
+ regex: '.*CN=([^,/]+).*' match group: 1 +
+ +
The servlet filter will accept two initialization parameters, + regex and matchGroup that can be used to extract + the principal name differently.
+ +
+

+ +

4.d. Establishing default ARP's for the + origin community

+ +

For a more basic introduction to ARP's, please refer to + section 2.e.

+ +

+
An ARP determines which attributes are released to a SHAR + when a user tries to access a resource. It acts as a sort of + filter on user information contained in the authoritative + directory, deciding what can be released to whom, but not + modifying or creating information itself. ARP's are generally + administered by the site, but Shibboleth will provide for users to + broker control of their own information and privacy by + allowing them to create ARP's pertaining to themselves.
+ +
It is recommended that a set of policies be established + between an origin and frequently accessed targets to specify + default releases of expected attributes. Federation guidelines may + provide more information on population of ARP's.
+ +
Currently, there is no direct mechanism for users to create + their own ARP's besides direct XML writing. In future + versions, a GUI will be provided for simpler management of + ARP's. Care should be given to balancing giving sufficient + control over information to users and avoiding access + problems. For example, users may decide to restrict the + release of their personal information to such a degree that + access to a site for a class may become impossible because + Shibboleth cannot release enough information to grant + access.
+ +
The Shibboleth distribution contains an example site arp that + releases the eduPersonScopedAffiliation attribute to all targets. For + more precise information regarding how ARP's are processed or + syntactically formed, please refer to section 5.a.i.
+

+ +

4.e. Modifying the default Attribute Resolver configuration

+
The resolver.xml file controls the retrieval of attributes from enterprise repositories, and the process of mapping them to Shibboleth/SAML attributes. For more precise information regarding how attributes are processed or syntactically formed, please refer to section 5.c.
+ +
In order to make the Shibboleth software operational, however, minor edits must be made to the example version of the resolver.xml file. The file can be found at /webapps/shibboleth/WEB-INF/classes/conf/resolver.xml. Two changes are necessary:
+ +
1. The value of the smartScope attribute should be changed to the Domain Name value submitted to the Federation. It appears on two SimpleAttributeDefinition elements: eduPersonScopedAffiliation and eduPersonPrincipalName.
+ +
2. The comment indicators should be removed from around the definitions of those two elements (  ).
+

+
+

+
+ +

5. Advanced Configuration

+ +

5.a. ARP Overview

+ +

+
This section applies primarily to the syntactic and + technical details of ARP's. For basic information on and + explanation of what an ARP is and how it should be managed, + please refer to sections 2.e and 4.d.
+ +
Every ARP file contains one ARP. ARP's may be specified either + as the site ARP or user ARP's. The site ARP pertains to every + principal for whom the AA retrieves information; a user ARP + applies only to the individual user for whom it is defined. The + set of principals to whom the ARP applies is defined by the name + of the ARP file: the site ARP is stored in arp.site.xml and user ARP's are stored as + arp.user.$PRINCIPALNAME.xml. + Up to two ARP's will apply to a principal: the site ARP, and the + user ARP for that principal.
+ +
Each ARP acts as a container that holds a set of ARP rules + that are applicable to the principals that ARP is effective + for. Each ARP rule specifies a single release policy within + the ARP container pertaining to a specific set of targets. + This set of targets may be specified as a specific SHAR, a + SHAR tree, or a regular expression, and becomes the ARP rule's + target definition. Each ARP rule may contain specifications + regarding the release of any number of attribute values to + requests matching that ARP rule for that user. ARP rules may + be flagged as default, implying that they are always applied + to any user matched by the ARP container. Note that ARP's may + also be used to restrict specific attribute/value pairs in + addition to restricting or releasing individual attributes.
+ +
When a query is received, the AA generates an effective + ARP, which is the fully evaluated set of ARP rules regarding + that SHAR based on all ARP containers applicable to the + principal. This effective ARP is then applied to attribute + values retrieved from the directory and the appropriate + assertion is constructed. Default rules are always + included in construction of the effective ARP.
+ + + +

+ +

5.a.i. ARP Processing

+ +

+
+
When a request arrives from a particular SHAR, the + applicable set of ARP rules are parsed into an effective + ARP. This parsing is done as follows:
+ +
+
Identify all ARP's that should be applied to a particular + principal. This is done by isolating the files in the folder + specified by edu.internet2.middleware.shibboleth.aa.arp.provider.FileSystemArpRepository.Path that have the + name either arp.site.xml or arp.user.$PRINCIPALNAME.xml.
+
Find all ARP rules relevant to the query: +
+
Any ARP rules within the identified ARP's designated + as defaults are automatically included in the effective + ARP without performing any matching functions.
+
For each non-default rule in each identified ARP, + the matching functions specified in the rule's target + definition are performed. A separate matching function + is performed for the requesting SHAR and the resource on + behalf of which the SHAR is making the request.
+
Each matching function evaluates to TRUE if + the match is successful or FALSE if it is + unsuccessful. If both functions evaluate to + TRUE, the rule is included in the Effective + ARP.
+
+
Construct the Attribute Filter: +
+
For each attribute, compile a temporary list of + associated rules that includes all values with a release + qualifier of permit.
+
Subtract from this list all attribute values with + rules specifying a release qualifier of deny. + The resulting list represents the allowable release + values for the attribute and is used as a mask for the + values which are returned from the Attribute + Resolver.
+
If a statement specifies that all values should be + permitted, then specific deny qualifiers for + specific values should still be enforced. If a + statement specifies that all values should be denied, + then permit qualifiers for specific values will + be ignored.
+
+
Using the mask and attributes returned from the + Attribute Resolver, an assertion is constructed.
+
+
+

+ + +

5.a.ii. ARP Syntax

+ +

+
+ +
Each ARP is described by an XML file based on a standard + .xsd schema. It consists of a standard + AttributeReleasePolicy element referencing the + appropriate xsi:schemaLocation and a self-explanatory + Description element followed by any number of + Rule elements. Each Rule element must + consist of a Target element and one or more + Attribute elements. The Target element + specifies the rules by which the target definition is formed. + The Attribute elements specifies the name and values + of the attributes that may be released.
+ +
The simplest possible ARP is as follows, which releases + eduPersonScopedAffiliation to any target for the + users the ARP applies to:
+ +
+ + <?xml version="1.0"?>
+ + <AttributeReleasePolicy + xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" + xmlns="urn:mace:shibboleth:arp:1.0" + xsi:schemaLocation="urn:mace:shibboleth:arp:1.0 + shibboleth-arp-1.0.xsd">
+ +          + <Description>Simplest possible + ARP.</Description>
+ +          + <Rule>
+ +           +        <Target>
+ +           +           +      <AnyTarget/>
+ +           +        </Target>
+ +           +        <Attribute + name="urn:mace:eduPerson:1.0:eduPersonScopedAffiliation">
+ +           +           +      <AnyValue release= + "permit"/>
+ +           +        </Attribute + >
+ +         </Rule + >
+ + </AttributeReleasePolicy>
+ + +
+
+ +
All ARP's must take the same basic form. A detailed + description of how each element of the Rule element + may be sub-populated follows:
+ +
The Target element:
+ +
+ +
Target may contain either the + AnyTarget element, which will cause the + Target to always return TRUE, or both the + Requester element, which provides for matches to be + performed against the SHAR name and the Resource + element, which provides for matches to be performed against + the requested URL.
+ +
There are three matches that may be performed by the AA + in evaluating ARP's by using the matchFunction + component of the Requester and Resource + elements. The following match patterns may be + specified directly following the Requester or + Resource elements, such as <Requester + matchFunction="urn:mace:shibboleth:arp:matchFunction:regexMatch">:
+ +
+
+
urn:mace:shibboleth:arp:matchFunction:exactShar +
+
+
May be used with the Requester + element.
+ +
Evaluates to TRUE when the string content + of the Requester element matches exactly the + name of the requesting SHAR. Otherwise evaluates to + FALSE. Serves as the default value + associated with Requester if none is + specified.
+
+
+
+
urn:mace:shibboleth:arp:matchFunction:resourceTree +
+
+
May be used with the Resource element.
+ +
Evaluates to TRUE when the location of + the resource either matches exactly or begins with + the string content of the Resource element. + Otherwise evaluates to FALSE.
+
+
+
+
urn:mace:shibboleth:arp:matchFunction:regexMatch +
+
+
May be used with both the Requester + and Resource elements.
+ +
Evaluates to TRUE when the name of the + requesting SHAR or the requested URL tree is a valid + match of the regular expression represented as the + content of the containing element. Otherwise evaluates + to FALSE. Regular expressions are evaluated in + accordance with the the Java 1.4 Pattern API.
+
+
+
+ +
+ +
The Attribute element:
+ +
+ +
The Attribute element must always specify the + URN of the attribute whose release parameters it specifies. + Additionally, it must contain either the AnyValue + element or one or more Value elements. These + elements, in turn, must specify either release = + permit or deny. The Value + element must then contain one value for which the rule + applies. Examples:
+ +
+ + <Attribute name="urn:mace:eduPerson:1.0:eduPersonPrincipalName">
+   <AnyValue release="Permit">
+ </Attribute>
+
+
Permits the release of eduPersonPrincipalName + with any value.
+
+ +
+ + <Attribute name="urn:mace:eduPerson:1.0:eduPersonScopedAffiliation">
+   <Value release="deny">member@example.edu</Value>
+ </Attribute>
+
+
Denies the release of + eduPersonScopedAffiliation value + member@example.edu. Other values of the + attribute may still be released if so specified by a + permit ARP.
+
+
+ + + +

5.b. Sharing certificate/key pairs + between Apache and Java keystores (optional)

+ +

+
+
The JDK includes the command line program + keytool for managing Java keystores. This utility + cannot import or export private key information, making it + difficult to use the same private key and certificate for + Apache and Java-based applications. The Shibboleth + distribution includes extkeytool, a program that + can be used in conjunction with keytool to perform + these tasks. Select the appropriate step-by-step procedure + for your situation from the following guides.
+ +
Before running extkeytool, the variable + SHIB_HOME must be set to the path to the directory where the + Shibboleth tarball was exploded(typically + /usr/local/shibboleth-origin-1.0/).
+ +
If you have a pre-exiting RSA key/certificate + combination in a keystore and you would like to use it with + Apache:
+ +
+
+
Determine the alias of the keystore keyEntry + containing the key you would like to use in your Apache + setup. Assuming that your keystore is named + yourstore, the following command should + present a list of the entries in the keystore.
+ +
+
$ keytool -list -v -keystore + yourstore
+
+
+ +
+
Assuming that you identified the appropriate alias + as youralias and the password for the keystore + is yourpass, enter the following command to + export the key in Base64-encoded pkcs8 format.
+ +
+
$ extkeytool -exportkey -keystore yourstore + -alias youralias -storepass yourpass -rfc -file + yourkey.pkcs8
+
+
+ +
+
In order to use this key with Apache, you must + convert it to PEM-encoded RSA native format. You have + the option of storing the key unencrypted or + encrypted:
+ +
+
+
To use the unencrypted format, enter the + following command for the conversion:
+ +
+
$ openssl pkcs8 -in yourkey.pkcs8 + -nocrypt|openssl rsa -out yourkey.key
+
+
+ +
+
To use the encrypted format, enter the following + command for the conversion:
+ +
+
$ openssl pkcs8 -in yourkey.pkcs8 + -nocrypt|openssl rsa -des3 -out + yourkey.enckey
+
+
+
+
+ +
+
The following command will export the corresponding + certificate.
+ +
+
$ keytool -export -keystore yourstore -alias + youralias -rfc -file yourcert
+
+
+ +
+
Set the mod_ssl + SSLCertificateKeyFile and + SSLCertificateFile directives to point to the + two files you have just created. Take care to remove + any temporary files you created (i.e. + yourkey.pkcs8) and set appropriate file + permissions, especially if you chose to store the key + in an unencrypted format.
+
+
+ +
If you have a pre-existing RSA key/certificate + combination that you use with Apache and would like to + import it into a java keystore:
+ +
+
+
Convert the private key to unencrypted DER-encoded + pkcs8 format. Assuming your PEM-encoded key is stored + in a file named yourkey.enckey, enter the + following command.
+ +
+
$ openssl pkcs8 -in yourkey.enckey -topk8 + -nocrypt -outform DER -out yourkey.der.pkcs8
+
+
+ +
+
Create a certificate bundle file. This file should + include a series of PEM-encoded X509 certificates + representing a complete trust chain, from the root CA + certificate to the certificate that matches your + private key. If your certificate is stored in a file + named mycert and the CA signer certificate is + stored in a file named ca.cert, you might + enter the following command to create the bundle.
+ +
+
$ cat mycert ca.cert > cert.bundle
+
+ + Note: mod_ssl-enabled Apache + installations include a number of commonly recognized + CA certificates in the ca-bundle.crt file + under the $ServerRoot/conf/ssl.crt/ + directory. +
+ +
+
Import the key and certificate into the keystore. + Assuming you have already created a keystore named + yourstore with a password of of + yourpass, enter the following command to store + the data under the alias youralias.
+ +
+
$ ./extkeytool -importkey -keystore yourstore + -alias youralias -storepass yourpass -keyfile + yourkey.der.pkcs8 -certfile cert.bundle -provider + org.bouncycastle.jce.provider.BouncyCastleProvider
+
+
+ +
+
You can verify that the import was successful by + listing entry. Use the command below.
+ +
+
$ keytool -list -v -keystore yourstore -alias + youralias
+
+
+ +
+
Remember to delete yourkey.der.pkcs8, as it + contains your unencrypted private key.
+
+
+ +
If you are starting from scratch and do not yet have + a certificate/key pair:
+ +
+
+
Generate an RSA private key. Use the command below, + substituting yourkey with an appropriate name + to use to refer to the key.
+ +
+
$ openssl genrsa -des3 -out yourkey.enckey + 1024
+
+
+ +
+
The following command generates a Certificate + Signing Request, which should be communicated to a + Certificate Authority.
+ +
+
$ openssl req -new -key + yourkey.enckey
+
+
+ +
+
The Certificate Authority should respond with a + PEM-encoded X509 certificate. Set the mod_ssl + SSLCertificateKeyFile directive to point to + the key file you just created and the + SSLCertificateFile directive to point to file + containing the certificate issued by the Certificate + Authority. Previous sections explaion how to share the + key/certificate pair with a Java keystore.
+
+
+
+

+ +
+

5.c. The Attribute Resolver

+ +

+
Shibboleth provides a powerful attribute resolver that allows + origins to quickly configure the retrieval of simple attributes + from standard types of attribute stores. The resolver is configured + using an xml file wich should be pointed to with the edu.internet2.middleware.shibboleth.aa. + attrresolv.AttributeResolver.ResolverConfig propety in origin.properties as described in + section 4.a. For more complex attributes or + those that require processing before release, customized Java + classes will need to be written. For more information, + consult the programmer's guide.
+ +
The resolver is essentially a directed graph from attribute + definitions to data connectors. The data connectors pull data, in + the form of attributes, from external data sources. The attribute + definitions then process this data into a from suitable for use + by Shibboleth. This procedure can be as simple as taking an + unmodified string value from a data connector and tagging it with + a name or can include arbitrarily complex business rules.
+ +
The resolver.xml file that is + pointed to by origin.properties + consists of zero or more attribute definitions followed by zero or + more data connectors. Each attribute definition consists of an + identifier corresponding to the URN of the attribute, and optional + references to data connectors on which it depends. Each data connector + consists of a string identifier which is used by attribute + definitions that refer to it, and one or more elements specific to + the configuration of that data connector.
+ +
Shibboleth comes with two attribute definitions provided in + version 1.0: the SimpleAttributeDefinition, which acts as + a basic proxy for attributes supplied by data connectors with some + name conversion and attribute scoping added, and a CustomAttributeDefinition, which can be + used to configure user-created attribute definition plugins. + Similarly, Shibboleth 1.0 comes with two data connectors: the + JNDIDirectoryDataConnector, which + pulls data from any source for which there is a JNDI Directory + Context implementation, including LDAP, NDS, etc., and the CustomDataConnector, which is used to + configure user-created data connector plugins.
+ +
A detailed explanation of each configuration option for the + provided connectors follows:
+ +
JNDIDirectoryDataConnector:
+ +
+
+ id = <string> +
+ +
+
Specifies a unique, textual name for the connector used by + attribute definitions to refer to and use it to build + attributes. Contained within the JNDIDirectoryDataConnector + element.
+
+ +
+ <Property name="<name>" value="<value>"/> +
+ +
+
An element of the element JNDIDirectoryDataConnector. + Specifies a set of name/value pairs that are used to configure + the JNDI Directory Context. This list of name/value pairs is + defined by the context itself, but is specified within resolver.xml. Refer to the Shibboleth + CVS for an example of names and values used to connect to + an LDAP directory.
+
+ +
+ <Search> +
+ +
+
An element of the element JNDIDirectoryDataConnector. This + element defines the DN filter used to perform the LDAP search. + The search string must return no more than one result.
+
+ +
+ <Controls> +
+ +
+
An element of the element Search. This + element grants some fine-grained control over the LDAP API + calls.
+
+ +
+ <cacheTime "<seconds>"/> +
+ +
+
An element of the element JNDIDirectoryDataConnector. + Specifies an optional duration in seconds for which the attribute + resolver may cache information retrieved from this + connector.
+
+
+ +
A representation of a properly constructed JNDIDirectoryDataConnector element would + look like:
+ +
+ <JNDIDirectoryDataConnector id="directory">
+   <Search filter="cn=%PRINCIPAL%">
+     <Controls searchScope="SUBTREE_SCOPE" returningObjects="false" />
+   </Search>
+   <Property name="java.naming.factory.initial" value="com.sun.jndi.ldap.LdapCtxFactory" />
+   <cacheTime="2400"/>
+ </JNDIDirectoryDataConnector> +
+ +
SimpleAttributeDefinition:
+ +
+
+ id = <string> +
+ +
+
Specifies a unique, textual name for the attribute which is + used as the attribute's name when it is sent over the wire by + Shibboleth. Contained within the SimpleAttributeDefinition + element.
+ +
Attributes are named in the format <URI>#<attributename>; + for example, urn:mace:dir:eduperson# + eduPersonScopedAffiliation.
+
+ +
+ <AttributeDependency / DataConnectorDependency requires="<id>"/> +
+ +
+
An element of the element SimpleAttributeDefinition, which may + contain 0 or more of either AttributeDependency or DataConnectorDependency. These + specify attributes and data connectors that can be utilized by + this attribute definition. Each of these elements must + contain a requires statement + which this attribute definition can then use to build its + value.
+
+ +
+ smartScope = "<domain>" +
+ +
+
Specifes a domain scope to be attached to the attribute. If + the value of the attribute as retrieved from the data + connector includes a pre-existing scope (bob@foo.edu), that scope is used + instead. Contained within the SimpleAttributeDefinition + element.
+
+ +
+ sourceName = "<string>" +
+ +
+
Specifies a different source attribute name to be used in + calls to the data connector, while the name on the wire will + be the specified id. This + would be useful to send a local UniversityID attribute as + eduPersonPrincipalName. If not supplied, the connector + tokenizes the id field and + uses the section following the # to query data connectors. + Contained within the SimpleAttributeDefinition + element.
+
+ +
+ <cacheTime "<seconds>"/> +
+ +
+
An element of the element SimpleAttributeDefinition. + Specifies an optional duration in seconds for which the attribute + resolver may cache this attribute for use in additional + assertions.
+
+ +
+ <lifeTime "<seconds>"/> +
+ +
+
An element of the element SimpleAttributeDefinition. + Specifies in the attribute assertion how long the attribute + should be cached and retained by the target upon receipt. + Federations and trust agreements may have some bearing on the + population and use of this field.
+
+
+ +
A representation of a properly constructed SimpleAttributeDefinition element would + look like:
+ +
+ <SimpleAttributeDefinition id="urn:mace:dir:eduperson#eduPersonPrincipalName" smartScope="shibdev.edu" sourceName="universityPerson">
+   <DataConnectorDependency requires="dataConnector"/>
+   <AttributeDependency requires="urn:mace:dir:eduperson#eduPersonAffiliation"/>
+   <cacheTime="600"/><br>
+   <lifeTime="3600"/><br>
+ </SimpleAttributeDefinition> +
+ +
A properly formed resolver.xml + file to automatically generate a simple response for EPPN may take + the form:
+ +
+ <AttributeResolver xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns="urn:mace:shibboleth:resolver:1.0" xsi:schemaLocation="urn:mace:shibboleth:resolver:1.0 shibboleth-resolver-1.0.xsd">
+
+   <SimpleAttributeDefinition id="urn:mace:dir:eduperson#eduPersonPrincipalName" smartScope="shibdev.edu">
+     <DataConnectorDependency requires="echo"/>
+   </SimpleAttributeDefinition>
+
+   <CustomDataConnector id="echo" + class="edu.internet2.middleware.shibboleth.aa.attrresolv.provider.SampleConnector" />
+ </AttributeResolver> +
+ +
There are additional examples of resolver.xml files provided in the Shibboleth CVS.
+ +

+ +
+
+

+
+ + +

6. Troubleshooting

+ +

This section provides basic information about testing, + logging, and error handling for Shibboleth origins. This + information is not intended to be comprehensive, but instead + rudimentary guidelines for basic configuration tests and + problems. For more detailed information or answers to specific + problems not addressed in this section, please mail mace-shib-users@internet2.edu + with a thorough description of errors and configurations + used.

+ +

6.a. Basic Testing

+ +

+
Internet2 provides a basic target that can be used to test + origin setup functionality. After your origin is recognized + by InCommon, simply use any browser to access https://wayf.internet2.edu/shibboleth/sample.jsp. + Select your origin's name and follow the login process as a + user would. Note that SSL must be used, and both the HS and + AA must be fully configured.
+ +
The test target will then display a simple page which + includes the basic information sent to it by your origin and + the authentication rules it is using.
+ +
For information regarding specific error messages that + may be generated if the origin does not work successfully, + please refer to section 6.c.
+

+ +

6.b. Logging

+ +

+
Shibboleth's origin components log various operations + which may prove useful for auditing, testing, and security + purposes. This data is sent through log4j's standard + mechanism. The location of + the log file, the level at which the log is output, the + formatting of the logs, and many more options may be + configured by editing + /WEB-INF/classes/conf/log4j.properties. By default, it is + setup to log to the console of the servlet container, with a + level of WARN, but there is also a commented out + example in the file to give a possible alternate + configuration.
+

+ +

6.c. Common Problems

+ +

+
A knowledge base is being developed in the + Shibboleth Deployer's FAQ. Please mail mace-shib-users@ + internet2.edu with any additional questions or problems + encountered that are not answered by this basic guide.
+

+ + + diff --git a/doc/DEPLOY-GUIDE-TARGET.html b/doc/DEPLOY-GUIDE-TARGET.html new file mode 100644 index 0000000..9b198c9 --- /dev/null +++ b/doc/DEPLOY-GUIDE-TARGET.html @@ -0,0 +1,2314 @@ + + + + + Shibboleth Target Deployment Guide + + + + + + +

Shibboleth Target Deployment Guide

+ + + Shibboleth Target Deployment Guide
+ draft-internet2-mace-shibboleth-shib-target-deploy-33.html
+ Nate Klingenstein
+ 9 June, 2003
+ Comments should be directed to ndk@internet2.edu.
+ +

This version of the deploy guide is for Shibboleth v1.0. For + documentation related to prior versions of Shibboleth, please + consult the appropriate branch in the Shibboleth CVS.

+ +

Federations have been abstracted out from the Shibboleth + documentation. For further information on using Shibboleth in a + federation, refer to the federation guide.

+ +

Functionality which has been added since the previous + version (v0.8) includes:

+ +

+
Various improvements to error handling. Origin sites are now + able to supply a URL to a federation for users to be referred to + when Shibboleth encounters a problem. Targets will be able to + utilize this URL in error templates.
+
+
The SHAR may now store its session and attribute cache in a + back-end database in addition to the previously available + in-memory option. The method by which sites.xml is refreshed has been + modified to improve robustness.
+
+
Attribute acceptance policies have been greatly enhanced, + with filtering of attribute values by sites supported.
+
+
OpenSAML now populates AuthType element in the SAML Subject + element using a value specified by origin sites using a + configuration directive. This value describes the type of + authentication mechanism used at the origin site(e.g. Kerberos, + PKI, etc.). This value is made available on the target side as + another variable that may be used in authorization + decisions.
+
+
Origin sites whose HS certificate is not signed by one of a + federation's trusted roots are able to provide that federation + with the certificate; this cert can now be stored in the sites + metadata, and targets will be able to use this certificate to + validate the HS' signature.
+
+
The AA implementation has been improved with a powerful + attribute resolver. This should greatly simplify the process of + configuring the AA to support additional general attributes, + while Java classes may still be written for more complex + evaluations.
+
+
Local time string values are now used in log files.
+
+
Targets may now also be run under Apache on a W2K box.
+

+ +

Before starting, please sign up for all applicable + mailing lists. Announcements pertinent to Shibboleth + deployments and developments and resources for deployment + assistance can be found here.

+ +

+
+

+
+
+ + +

Shibboleth Target -- Table of + Contents

+
+ + +

+
Shibboleth + Overview
+ +
1. Origin
2. Target
3. WAYF
4. Federations
+
+
Planning
+ +
1. Requirements
2. Join a + Federation
3. Security + Considerations
4. Server + Certs
5. Attribute Release + Policies
6. Designate + Contacts
7. Browser + Requirements
8. Clocks
9. Other + Considerations
+
+
Installation
+ +
1. Software + Requirements
2. Deploy the + Shibboleth Package
3. Configure + Apache
+
+
Getting + Running
+ +
1. Configuring + shibboleth.ini
2. Dynamic Error + Page Generation
3. Key Generation + and Certificate Installation
4. Protecting + Webpages
5. Designing + AAP's
6. Using Attributes + in Applications
7. siterefresh
+
+
Troubleshooting
+ +
1. Basic + Testing
2. Common + Problems
+

+
+

+
+ + +

1. Shibboleth Overview

+ +

1.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 Pubcookie is also supplied; the + directory is provided by the origin site. Shibboleth is able + to interface with a directory exporting an LDAP interface or a + SQL database containing user attributes, and is designed such + that programming interfaces to other repositories should be + readily implemented. Shibboleth relies on standard web server + mechanisms to trigger local authentication. A .htaccess file + can be easily used to trigger either the local WebISO system + or the web server's own Basic Auth mechanism, which will + likely utilize an enterprise authentication system, such as + Kerberos.
+ +
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 an 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.
+

+ +

1.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 + authentication 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. The SHAR performs some basic validation and + analysis based on attribute acceptance policies (AAP's). + These attributes are then handed off to the RM, which is + responsible for using these attributes 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 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.
+

+ +

1.d. Federations

+ +

+
A federation provides part of the underlying trust required for + function of the Shibboleth architecture. A federation in the + context of Shibboleth 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 targets and + origins 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 to support Shibboleth, it 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 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 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.
+

+
+
+
+

+
+ + +

2. Planning

+ +

There are several essential elements that must be present in + the environment to ensure Shibboleth functions well, both + political and technical. Shibboleth currently runs on a + specific range of platforms and web server environments. The + SHAR and SHIRE are implemented entirely in C/C++. These are the + recommendations and requirements for a successful implementation + of a Shibboleth target.

+ +

2.a. Requirements

+ +

+
Shibboleth currently only supports Linux and Solaris. At + present, Shibboleth consists of Apache plugins and a separate SHAR + process. The plugins use the ONC RPC mechanism to communicate with + the SHAR. The target's web servers must be running Apache 1.3.26+, but + not Apache 2. More precise technical details are discussed in 3.a.
+

+ +

2.b. Join a Federation

+ +

+
While it is not necessary for a target or origin to join a + federation, doing so greatly facilitates the implementation of + multilateral trust relationships. Each federation will have a + different application process.
+ +
For more information on federations, refer to 1.d or the Shibboleth v1.0 architectural + document.
+

+ +

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 optional for target sites. 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 strongly + suggested that all password traffic or similarly + sensitive data should be SSL-protected. Assessment of the + risk tradeoff against possible performance degradation + should be performed for all applications.
+
+ +
+
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 security, which is not + uncommon, but attacks concerning bad domain information + should be considered.
+
+ +
+
Information regarding origin users is generally + provided by the authoritative enterprise directory, and + the acceptance of requests from target applications can + be carefully restricted to ensure that all requests the + SHAR performs are authorized and all information the + origin provides is accurate. Use of plaintext passwords + 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 SHAR, HS, and AA must + all have various client and/or 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 + your federation. After understanding the CA's acceptible to your + federations, consult chapter 4.c for + information on certificate and key generation.
+

+ +

2.e. Attribute Release Policies

+ +

+
The Attribute Authority maintains a set of rules called + Attribute Release Policies (ARP's) that define which + attributes are released to which targets. When a browser user + tries to access a resource, the SHAR asks the origin site AA + to release all the attributes it is allowed to know. The SHAR + provides its own name and an optional URL on behalf of which + the attribute request is made which can further refine the + information the SHAR is allowed to know. The AA processes this + request using all applicable ARP's, determines which + attributes and values it will release, and then obtains the + values actually associated with the browser user. The AA sends + these attributes and values back to the SHAR.
+ +
Targets should work together with expected origin sites to + ensure that the sets of attributes that both sites expect to + correspond using are congruent.
+

+ +

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. Names, titles, e-mail + addresses, and phone numbers may all be useful information to + provide.
+

+ +

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. Shibboleth employs a short handle + issuance time to protect against replay attacks. Because of + this, any significant degree of clock skew 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.
+

+
+
+

+
+ + +

3. Installation

+ +

3.a. Software Requirements

+ +

The Shibboleth project makes binary packages available for + Solaris and Linux that are precompiled against recent releases + of various required libraries such as OpenSSL. It is highly + advisable to build from source when using Shibboleth in a + production environment in order to permit patching or updating + of packages as security holes and bugs are fixed. Building from + source is necessary to give you complete control over your + deployment platform. The binary packages represent a snapshot in + time only. To build from source, see the INSTALL.txt + files in the root of the OpenSAML and Shibboleth source + distributions.

+ +

+ Operating System: + +
+
+ RedHat 7.2-7.3: + +
+
+ Apache 1.3.27 + +
+
Apache must be compiled with mod_so for DSO + module support, and must include SSL + support (preferably using mod_ssl), and + EAPI support (which mod_ssl requires and + provides). Shibboleth can coexist with + mod_auth, which may be compiled or loaded + into the server for use elsewhere, but Shibboleth + does not need or use it. The most recent Red Hat + RPM (1.3.23-14 as of this writing) is sufficient. +
+
+ +
+
On Linux, Shibboleth requires that Apache and + Apache-SSL be built with libpthread, or loading the + mod_shibrm or mod_shire modules will + cause Apache to stop. While RedHat's Apache is + compatible, Debian's Apache must be rebuilt with + libpthread:
+
+ $ export LDFLAGS=-lpthread'
+ $ apt-build --rebuild --reinstall install apache-common apache \ apache-ssl +
+
+
+ +
+ Shibboleth v1.0 Target for RedHat
+ +
openssl-0.9.6, + revision i or newer
+ +
+ libstdc++3-3.0.4-1.i386.rpm and + libgcc-3.0.4-1.i386.rpm + +
+
Shibboleth binaries are currently built with GCC + 3.04, and require these specific library + versions. They are available as RPMs and are + available in the RedHat 7.2 updates directory on + any + RedHat mirror. They can be installed alongside + earlier and later GCC libraries.
+
+
+ +
Portions of the libphp4 Apache plugin are written + in C++, as is Shibboleth. There is a known conflict between + the PHP extensions libpspell.so and libsablot.so which will manifest + itself as segmentation faults when starting Apache. If a + site wants to use libphp4.so + and Shibboleth at once, then one of the following may be + done: +
+
+ Remove the options --with-pspell and --with-xslt-sablot from PHP's configuration. +
+
+ Rebuild these two modules using + the same version of GCC that was used to compile Shibboleth. +
+
+
+
+
+
+
+ Solaris 2.8: + +
+
+ openssl-0.9.7a + +
+
The shared library version of OpenSSL is required + by Shibboleth. The static libraries may be installed as + well if necessary for other applications, but cannot be + used within mod_ssl or any other Apache modules.
+
+
+ +
+ Apache 1.3.27 + +
+
Apache must be compiled with mod_so for DSO + module support, and must include SSL + support (preferably using mod_ssl) and EAPI + support (which mod_ssl requires and + provides). Shibboleth can coexist with + mod_auth, which may be compiled or loaded + into the server for use elsewhere, but Shibboleth + does not need or use it.
+ +
mod_ssl's + loadable module, libssl.so, must be + compiled against OpenSSL + 0.9.7a's shared libraries. Other versions or + a statically linked build of libssl.so will cause + failures such as bus errors when used with + Shibboleth.
+ +
To check how OpenSSL was built, run the ldd command against libssl.so in the Apache + /libexec/ folder and + check the output for references to libssl.so.0.9.7a. If you + see an earlier version mentioned, or no mention of + it at all, then OpenSSL + 0.9.7a must be rebuilt with shared libraries + from source.
+
+
+ +
+ libgcc v3.2.2+ and libstdc++ v3.2.2+
+ +
+ Shibboleth v1.0 Target for Solaris
+ +
Portions of the libphp4 Apache plugin are written + in C++, as is Shibboleth. There is a known conflict with + the PHP extensions libpspell.so and libsablot.so which will manifest + itself as segmentation faults when starting Apache. If a + site wants to use libphp4.so + and Shibboleth at once, then one of the following may be + done: +
+
+ Remove the options --with-pspell and --with-xslt-sablot from PHP's configuration. +
+
+ Rebuild these two modules using the same version of GCC + that was used to compile Shibboleth. +
+
+
+
+
+
+
+ RedHat 8: +
+
RedHat 8 ships with Apache 2, which is not supported by + Shibboleth. To run Shibboleth under this OS, Apache 1.3.27 + must be installed.
+
+
+
Apache must be compiled with mod_so for DSO + module support, and must include SSL + support (preferably using mod_ssl), and + EAPI support (which mod_ssl requires and + provides). Shibboleth can coexist with + mod_auth, which may be compiled or loaded + into the server for use elsewhere, but Shibboleth + does not need or use it. The most recent Red Hat + RPM (1.3.23-14 as of this writing) is sufficient. +
+
+ +
+
On Linux, Shibboleth requires that Apache and + Apache-SSL be built with libpthread, or loading the + mod_shibrm or mod_shire modules will + cause Apache to stop. While RedHat's Apache is + compatible, Debian's Apache must be rebuilt with + libpthread:
+
+ $ export LDFLAGS=-lpthread'
+ $ apt-build --rebuild --reinstall install apache-common apache \ apache-ssl +
+
+ +
+ +
+ Shibboleth 1.0 Target for RedHat
+ +
openssl-0.9.6, + revision i or newer
+ +
+ libstdc++3-3.0.4-1.i386.rpm and + libgcc-3.0.4-1.i386.rpm + +
+
Shibboleth binaries are currently built with GCC + 3.04, and require these specific library + versions. They are available as RPMs and are + available in the RedHat 7.2 updates directory on + any + RedHat mirror. They can be installed alongside + earlier and later GCC libraries.
+
+
+ +
Portions of the libphp4 Apache plugin are written + in C++, as is Shibboleth. There is a known conflict with + the PHP extensions libpspell.so and libsablot.so which will manifest + itself as segmentation faults when starting Apache. If a + site wants to use libphp4.so + and Shibboleth at once, then one of the following may be + done: +
+
+ Remove the options --with-pspell and --with-xslt-sablot from PHP's configuration. +
+
+ Rebuild these two modules using + the same version of GCC that was used to compile Shibboleth. +
+
+
+
+
+
+

+ +

3.b. Deploy the Shibboleth Package

+ +

+
For the sake of clarity, this deployment guide assumes + that standard directories are used for all installations. + These directories may be changed for local implementations, + but must be done so consistently.
+ +
+
+
Ensure that you have obtained the proper + tarball for your operating system.
+
+ +
+
The tarballs expand into /opt/shibboleth, + and should be expanded as root from /. + You should see the following directory structure:
+ +
+ $ ls -al
+ drwxr-xr-x 10 root root 4096 Oct 24 03:54 .
+ drwxr-xr-x 3 root root 4096 Oct 24 00:37 ..
+ drwxr-xr-x 2 root root 4096 Oct 24 03:54 bin
+ drwxr-xr-x 2 root root 4096 Oct 24 03:54 doc
+ drwxr-xr-x 4 root root 4096 Oct 24 03:54 etc
+ drwxr-xr-x 13 root root 4096 Oct 24 03:54 include
+ drwxr-xr-x 4 root root 4096 Oct 24 03:55 lib
+ drwxr-xr-x 2 root root 4096 Oct 24 03:55 libexec
+ drwxr-xr-x 4 root root 4096 Oct 24 02:02 share
+ +
+
+
+

+ +

3.c. Configure Apache

+ +

+
+
+
Shibboleth includes configuration directives in the + file /opt/shibboleth/etc/shibboleth/apache.config + which must be added to the httpd.conf file used locally. + It is recommended that these directives simply be added + to the end of the existing httpd.conf file + rather than trying to merge it in-line; + step 2 describes the necessary + modifications to the Apache startup script. The default + configuration will often work, but if customization is + necessary, these options may be modified:
+ +
+ +
+ LoadModule <module> + <pathname> +
+ +
+
Specifies the title and location of the + shibrm_module resource manager and + shire_module SHIRE modules. These are + installed by default at + /opt/shibboleth/libexec/mod_shibrm.so + and + /opt/shibboleth/libexec/mod_shire.so
+
+ +
+ SHIREConfig <pathname> +
+ +
+
Specifies the pathname of the SHIRE's + configuration file. Defaults to + /opt/shibboleth/etc/shibboleth/shibboleth.ini.
+
+ +
SHIREURL <url>
+ <Location <url>>
+ SetHandler <method>
+ </Location>
+ +
+
Specifies the URL and the + method the target uses to handle + requests for Shibboleth-protected resources. + Currently, shib-shire-post is the only + available handler method. + SHIREURL is used by Shibboleth when + re-directing the user to the WAYF and + <Location> by Apache; for this + reason, both URL specifications must + match. Note that the configuration file itself + contains <>'s, and Location should + not be replaced.
+ +
The referenced URL can be either a + partial path or an absolute URL. The partial path + allows each virtual server to use its own + hostname and port in the SHIRE for session cookie + purposes, while the absolute URL forces HTTP + virtual servers to use HTTPS for the SHIRE. Use + of a full https:// URL is advised.
+
+ +
+ ShibMapAttribute <attribute-uri> + <HTTP-header> [alias] +
+ +
+
Registers attributes to be recognized and maps + them to an authorization alias for use + in .htaccess files or Location Blocks + with require directives. + REMOTE_USER is a special case, suggested + for use with eduPersonPrincipalName, and + is automatically checked by a require + user rule.
+
+
+ +
+ +
+ + +
These modifications must be made to the Apache startup + script:
+ +
Add the following environment variables:
+ +
+ + SHIBCONFIG=/opt/shibboleth/etc/shibboleth/shibboleth.ini; + export SHIBCONFIG +
+ +
If the OpenSSL libraries are not in the system's search + path, they should be added to LD_LIBRARY_PATH as + well.
+ +
If the SHIBCONFIG environment variable is not + specified, Shibboleth will use + /opt/shibboleth/etc/shibboleth/shibboleth.ini by + default.
+
+ +
+
The SHAR must be started before Apache. Among other + methods, this can be done either by creating a separate + SHAR startup script or by modifying Apache's RC script to + start/stop the SHAR before + httpd. It is suggested that Apache's script be + modified by adding:
+ +
+ /opt/shibboleth/bin/shar & +
+ +
Sample init.d scripts may be included with + future releases. Ensure that the environment variables + referenced in 3.c.2 are in + place.
+ +
+ +
+
The options in shibboleth.ini must be + configured as documented in 4.a. + Apache content will then need to be modified for + Shibboleth authentication. This is discussed in 4.d. It is recommended that the target then + be tested as detailed in section 5.a.
+
+
+

+
+

+
+ + +

4. Getting Running

+ +

4.a. Configuring + shibboleth.ini

+ +

+
Most of the configuration for the SHAR, SHIRE, and RM is stored + in the file shibboleth.ini. This + file is split into several pre-defined sections. The first + sections, general, shire, and shar, define the operational parameters + for the SHIRE and SHAR. The general section holds global tags, used + by all pieces. The shire and shar sections can override the general tags with SHIRE- or + SHAR-specific configuration. For example, if the SHAR is looking + for a tag, it will look first in the shar section; if it does not find the + tag there, it will proceed to look in the general section. The following + sections, metadata_shire, metadata_shar, attributes, and policies, define the trust framework + within the SHIRE and SHAR operate. Example configuration files + are bundled with the Shibboleth distribution.
+ +
There is also information that must be configured in + /usr/local/apache/conf/httpd.conf; for more + information, refer to 3.c.
+ +
Information in the logger files referenced by + shibboleth.ini may require additional configuration. + It is recommended that after initial installation is + completed, the log level in both files be changed to either + INFO or WARN.
+ +
Fields that are purple are optional; grey fields are + mandatory.
+ +
[general]:
+ +
+
+ logger = <pathname> +
+ +
+
Specifies the location of the log4cpp + configuration file for most Shibboleth events. This + element may also be optionally specified for each of + the components individually. Default logging settings + should suffice. The syslog daemon must + accept UDP:514 messages, and on Linux, + SYSLOGD_OPTIONS must include -r to + enable logging from remote machines. The + logging levels are defined in the logger + configuration. The configuration format is similar to + that of the Log4j package's format.
+
+ +
+ schemadir = <pathname> +
+ +
+
Specifies the directory in which the XML schema + files are located; defaults to + /opt/shibboleth/etc/shibboleth/. Note that + the pathname must have a trailing + /.
+
+ +
+ sharsocket = <pathname> +
+ +
+
Specifies the location of the socket the SHAR uses to + form connections.
+
+
+ +
The next segment of the [general] configuration + section defines server-specific tags in sections defined by + the server name for use by the SHIRE and RM. For example, if + you have a web server at www.example.edu, you can define a + section [www.example.edu] and override global tags + with tags for that server only.
+ +
The following table lists the server-specific tags. It is + broken into mandatory tags, and optional tags. Tags in the [general] section correspond to all + servers; to override specific tags on a per-server basis, use + [<FQDN>] as the header for a + section.
+ + [<general>]: + +
+ +
+ normalizeRequest = <true/false> +
+ +
+
If true, all redirects generated by + mod_shire will be created using the virtual + server name assigned to the server containing this + command. If false, the browser's supplied + URL is used to compute the redirect back.
+
+ +
+ checkIPAddress = <true/false> +
+ +
+
If true, Shibboleth will check client + addresses for impersonation protection. In most + circumstances, this should be enabled to prevent + certain attacks concerning stolen cookies. Defaults + to false.
+
+ +
+ supportContact = <e-mail> +
+ +
+
Specifies the e-mail address used in the + generation of error pages.
+
+ +
+ logoLocation = <pathname> +
+ +
+
Specifies the location of the logo used in the + generation of error pages. This logo can be in any + format that the web browser will understand.
+
+ +
+ wayfURL = <url> +
+ +
+
Specifies the URL of the WAYF service the user is + redirected to. Federations will generally provide this URL + or provide information on how to locally host WAYF's with + a distributed hosts file. Defaults to https://wayf.internet2.edu/InQueue/WAYF.
+
+ +
+ cookieName = <string> +
+ +
+
Defines the name to be used for session cookies.
+
+ +
+ shireSSLOnly = <true/false> +
+ +
+
If true, the SHIRE will reject HTTP + connections that are not SSL-protected. This guards the initial session + sign-on from the browser, but does not preclude non-SSL content. Use of + SSL is strongly recommended; see section 2.c for more information.
+
+ +
+ shireError = <pathname> +
+ +
+
Specifies the location of the template for the + error page generated when there is an error + re-directing the user to the WAYF or processing a + SHIRE POST.
+
+ +
+ rmError = <pathname> +
+ +
+
Specifies the location of the template for the + error page generated if internal errors occur in the + RM.
+
+ +
+ accessError = <pathname> +
+ +
+
Specifies the location of the template for the + page displayed to users when access to a protected + resource is denied by the RM.
+
+
+ + [shire]: + +
+
+ logger = <pathname> +
+ +
+
Specifies the location of a log4cpp which + overrides the [general] log parameters for + SHIRE events. Default logging settings should + suffice. The syslog daemon must accept + UDP:514 messages, and on Linux, + SYSLOGD_OPTIONS must include -r to + enable logging from remote machines. The + logging levels are defined in the logger + configuration. The configuration format is similar to + that of the Log4j package's format.
+
+ +
+ aap-uri = <uri> +
+ +
+
Specifies the URI of an attribute acceptance policy XML + file. Attributes must be listed in the aap-uri file if they are to be + visible. For more information, refer to section 4.e.
+
+ +
+ metadata = <tag> +
+ +
+
Specifies the tag that defines the section of shibboleth.ini the SHIRE should + use to acquire its metadata. The SHIRE does not need trust + metadata, and so generally it will only need sites data to + enforce attribute policies like scope limitations(e.g. MIT + not asserting @brown.edu attributes.)
+
+
+ + [shar]: +
+ +
+ logger = <pathname> +
+ +
+
Specifies the location of a log4cpp which + overrides the [general] log parameters for + SHAR events. Default logging settings should suffice. + The syslog daemon must accept + UDP:514 messages, and on Linux, + SYSLOGD_OPTIONS must include -r to + enable logging from remote machines. The + logging levels are defined in the logger + configuration. The configuration format is similar to + that of the Log4j package's format.
+
+ +
+ metadata = <tag> +
+ +
+
Specifies the tag that defines the section of shibboleth.ini the SHAR should + use to acquire its metadata.
+
+ +
+ certFile = <pathname> +
+ +
+
Specifies the location of the PEM-format + certificate used by the SHAR to communicate with + AA's.
+
+ +
+ keyFile = <pathname> +
+ +
+
Specifies the location of the PEM-format private + key used by the SHAR to communicate with AA's.
+
+ +
+ keyPass = <password> +
+ +
+
Specifies the password used to access the + keyfile.
+
+ +
+ calist = <pathname> +
+ +
+
Specifies a single file of PEM-format + certificates containing the certificates of root CA's + the SHAR will consider valid signers of AA + certificates.
+
+ +
+ AATimeout = <seconds> +
+ +
+
Specifies the number of seconds that the SHAR will wait + for attributes to be sent from an AA. Defaults to 60.
+
+ +
+ AAConnectTimeout = <seconds> +
+ +
+
Specifies the number of seconds that the SHAR will wait + for a connection to be established with a remote AA. + Defaults to 30.
+
+ +
+ cacheType = <method> +
+ +
+
Specifies the method used by the SHAR to cache received + attributes. The default is memory, which indicates that + Shibboleth should store received attributes in memory. + Another option is mysql, which will use the MySQL + Credential Cache. The steps to using this are described + in the MySQL Credential Cache guide.
+
+ +
+ cacheClean = <seconds> +
+ +
+
Specifies the duration in seconds between cleanups of + the SHAR's cached attributes. Defaults to 300, or 5 minutes.
+
+ +
+ cacheTimeout = <seconds> +
+ +
+
Specifies the duration in seconds that must elapse + between user accesses before that user's session is + destroyed, including the associated handle and all + cached attributes. Defaults to 28800 seconds, or 8 hours.
+
+
+ +
[metadata] sections must be + created and named in accordance with the value of the metadata parameter in the [shire] and [shar] sections. Metadata sections may + be shared or defined for each component. Two providers are + supported by Shibboleth, but additional providers may be + specified with name/value pairs consisting of <DEFANGED_metadata provider + type>=<source>.
+ +
[<metadata>]:
+ +
+
+ edu.internet2.middleware.shibboleth.metadata.XML = <pathname> +
+ +
+
Specifies the location of the file to load site + metadata from. This will often be a sites.xml file stored locally, + and may be used by both the SHIRE and SHAR.
+ +
Shibboleth provides a simple utility called siterefresh for updating the + metadata file as described in section 4.g.
+
+ +
+ edu.internet2.middleware.shibboleth.trust.XML = <pathname> +
+ +
+
Specifies the location of the trust database of + certificates and/or CA roots used by the SHAR during + session initiation. The SHIRE does not need trust + data.
+
+
+ +
In order for an attribute to be used by Shibboleth, it must be + recognized as valid by the SHAR and implemented with any specific + rules for how to understand and express its value based on the XML + from the AA. Additional string-valued attributes may be added to + the SHAR using the [attributes] + section.
+ +
[attributes]:
+ +
+
+ <attribute_URI>=<type> +
+ +
+
Attribute names are URI's that are assigned by the + parties standardizing the attribute. Frequently, a + federation or standard object class may define these URI's. + The attribute type may be either scoped or simple, which defines how + the attribute is processed as described in section 4.e.
+
+
+ +
The [policies] section contains the policy URI + values that control acceptance of assertions from origin + sites. This may eventually have multiple elements associated + it for targets that are members of multiple federations.
+ +
[policies]:
+ +
+
+ <federation> = <URI> +
+ +
+
The name of the federation and its + associated policy URI. + These URI's will be provided by federations.
+ +
This set of URI values is matched against the SAML + Audience fields of + assertions received from HS's and AA's. One of the + URI's specified by the origin in edu.internet2.middleware.shibboleth.audiences + must match one of these URIs or the + assertion will not be accepted by design.
+
+
+ +
Additional sections for individual servers may be defined with + either parameters overriding those found in [general], or the following additional + parameters:
+ +
[<FQDN>]:
+ +
+
+ requestAttributes = <attr1> <attr2> + <attr3>... +
+ +
+
Specifies a space-delimited list of attributes named by + URI that the SHAR will request of an AA. If the parameter + does not exist or is null, then the SHAR will receive all + attributes the AA is willing to release to it.
+
+
+ +

+ +

4.b. Dynamic Error Page Generation

+ +

+
Shibboleth supports the dynamic generation of information + in error pages referenced by shibboleth.ini. The + Shib Target employs a special Markup Language Processor to + insert special tags into the generated HTML. The parser will + read the error file looking for any tag that looks like:
+ +
+ <shibmlp tag-name /> +
+ +
Shibboleth will replace tag-name with the + appropriate markup tag from the table below:
+ +
+
supportContact
+ +
The value of the supportContact for this + server.
+ +
logoLocation
+ +
The value of the logoLocation for this server. This + is used to fill in the template error page only; if a custom + error page is created, then the image may be linked to + statically by the page itself.
+ +
requestURL
+ +
The user's requested URL.
+ +
errorType
+ +
The type of error.
+ +
errorText
+ +
The actual error message.
+ +
errorDesc
+ +
A textual description of the error intended for human + consumption.
+
+ +
This configuration is only for Apache servers, and is only + used by resources protected by Shibboleth. See section 4.d.
+ +
A sample error template is included in the Shibboleth + distribution, and can be triggered by anything that will cause + Shibboleth to be unable to make an authorization decision, + including a bad sites file, certificate chain, or skewed + clock.
+ +

+ +

4.c. Key Generation and Certificate + Installation

+ +

+
The only target component that must have a private key and + certificate is the SHAR. While the target server itself should support + SSL in most cases, it is mandatory for the SHAR to + authenticate when contacting an AA, and it must therefore be + given a key and an SSL client certificate. It is permissible + for the SHAR to use the same keypair and certificate used by + the target server itself, provided the certificate is signed + by a CA accepted by the community of sites.
+ +
The certificate and key should be placed based on whether + they will also be used for Apache's server cert. If they will + be used as a server certificate as well, they should probably + be in the Apache tree in the usual mod_ssl spot, and + the SHAR can read them from there. If the SHAR is not running + as root, permissions might need to be changed to + allow this access. If the certificate and key will only be + used for the SHAR, they can be put in the same folder with the + shibboleth.ini file.
+ +
The SHAR is assigned a key and a certificate using + shibboleth.ini's certfile, keyfile and + keypass, described in 4.a. These + files must currently be in PEM format. OpenSSL commands to + generate a new keypair and a certificate request are shown + here, assuming RSA keys are to be used:
+ +
+ $ openssl genrsa -des3 -out ssl.key 2048 $ openssl req + -new -key ssl.key -out ssl.csr +
+ +
The signed certificate file returned by the CA should be + usable directly, or can be converted to PEM format using the + openssl x509 command.
+ +
The key and certificate files can be placed anywhere, + though in or beneath /usr/local/apache/conf + directory is a good choice. The Apache child processes, + often running as nobody, must be able to read them + while the server is running, which may require permission + changes.
+ +
This particularly applies when sharing the key and + certificate used by mod_ssl, which are only readable by root + by default. The password, if any, must be placed in the conf + file, since the module cannot prompt for it as the initial + startup of mod_ssl can. The issues surrounding how to + securely obtain a key while running as nobody will + be addressed in a later release. Since the password will be + stored in clear text in a frequently examined file, it is + suggested to not reuse a password used elsewhere, or to place + the keypass directive in a separate file that is + Included in the main configuration file, so that its + permissions can be further restricted.
+ +
Finally, the calist command provides the SHAR + with a set of CA roots to trust when validating AA server + certificates. In all cases, the SHAR verifies that the + certificate's CN equals the AA's hostname, but the CA root + bundle restricts the accepdl signers to those permitted by + the SHAR. The parameter can be omitted to skip such signer + validation.
+

+ +

4.d. Protecting Webpages

+ +

+
Protection of webpages is primarily achieved through + "mapping" attributes provided by an AA to a localized + vocabulary for authorization rules. Each attribute can be + mapped using the ShibMapAttribute command to an HTTP + header name where it can subsequently be accessed by + applications, and optionally to an alias that can be + used in a Require command to search for a matching + value. This mapping command must be in httpd.conf, + while the rest of the commands described here appear in + content-specific configuration or .htaccess + files.
+ +
Any of the typical ways of protecting content may be used + (.htaccess, Directory, Location, Files, etc.). There are two + ways to trigger Shibboleth authentication: specifying an + AuthType of shibboleth to use Shibboleth + directly, or specifying ShibBasicHijack On to + process existing .htaccess files using Shibboleth instead. + Support for authorization consists of mod_auth-style require + directives, as well as support for mod_auth group files.
+ +
A complete list of the directives and their values is + below:
+ +
+
+ AuthType <string> +
+ +
+
Use shibboleth for direct invocation, or + Basic plus the ShibBasicHijack On + option described below.
+
+ +
+ ShibSSLOnly<on/off> +
+ +
+
Controls whether Shibboleth will reject non-SSL + requests from clients. Defaults to off.
+
+ +
+ ShibBasicHijack <on/off> +
+ +
+
Controls whether Shibboleth should or should not + ignore requests for AuthType Basic. Defaults + to off.
+
+ +
+ ShibAuthTimeout <seconds> +
+ +
+
Sets the maximum number of seconds without any + user activity that a session will remain alive. After + seconds seconds without activity, the + session is considered dead. Omission or 0 + results in an arbitrary session timeout.
+
+ +
+ ShibExportAssertion <on/off> +
+ +
+
Controls whether the SAML attribute assertion + provided by the AA is exported in a base64-encoded + HTTP header, Shib-Attributes. Defaults to + off.
+
+ +
+ ShibAuthLifetime <seconds> +
+ +
+
Sets the maximum lifetime in seconds that a user + session can survive. Omission or zero results in + arbitrary session lifetime.
+
+ +
+ AuthGroupFile <pathname> +
+ +
+
Same as mod_auth; collects EPPN's into a named + group for access control. Note that mod_auth will not + support group files when mod_shibrm is loaded, since + they share the same command.
+ + +
+
This + is implemented by placing a .htaccess + file that references an AuthGroupFile stored + at /path:
+ +
+ authgroupfile /path
+ require group workgroup +
+ +
Note that an + AuthGroupFile used by Shibboleth would resemble + workgroup: joe@example.edu, jane@demo.edu, + jim@sample.edu.
+
+
+ +
+ Require <string> +
+ +
+
Enforce authorization using one of the following methods. + Please note that valid-user is not a valid access + rule because there it is not clear what valid-user would signify in the + context of Shibboleth.
+ +
+
+ +
+ valid-user + +
+
Any Shibboleth user from a trusted origin site + is accepted.
+
+
+ + user + +
+
A space-delimited list of EPPN values, + provided that the + urn:mace:eduPerson:1.0:eduPersonPrincipalName + attribute has been mapped to the + REMOTE_USER header (as per the earlier + example configuration commands).
+
+ + +
+ group + +
+
A space-delimited list of group names defined + within AuthGroupFile files, again + provided that the mapping to REMOTE_USER + exists.
+
+
+ +
+ <alias> + +
+
An arbitrary rule tag that matches an alias + defined in a ShibMapAttribute server + command. The rule value is a space- delimited + list of attribute values, whose format depends on + the attribute in question (e.g. an affiliation + rule might look like require affiliation + staff@osu.edu faculty@mit.edu).
+
+
+
+ +
Additionally, for user and + <alias>-based rules, if a tilde character + is placed immediately following user or + <alias>, the expressions that follow are + treated as regular expressions.
+ +
For example, the regular expression AAP require affiliation ~ + ^member@.+\.edu$ would evaluate to allowing + anyone with an eduPersonScopedAffiliation of + member from a .edu + domain.
+ +
+
+
+

+ +

4.e. Designing AAP's

+ +

+
Shibboleth allows a user and a site to release a varying + set of attributes to a destination site, and does not impose + restrictions on the kinds of attribute information provided + by an AA. Target implementations must also be prepared to + examine the attributes they receive and filter them based on + policies about what information to permit an origin site to + assert about its users.
+ +
Attribute acceptance is the process of filtering attribute + values before passing them on to a resource manager, such as + the mod_shibrm module. Data blocked by AAP filters + will not be passed to the CGI environment or used when + enforcing .htaccess rules. + Note that the attribute assertion exported to the + Shib-Attributes header is pre-filtered.
+ +
The Shibboleth distribution scoped and + simple filtering policies for different kinds of + attributes.
+ +
An essential part of the Shibboleth trust fabric is ensuring + that sites only assert attributes for domains for which they are + considered authoritative by the target. Typically, this means + that Brown University will be trusted to assert attributes only + scoped to *brown.edu. Unless + there are very specific circumstances requiring this restriction + be removed, it is strongly encouraged that it be included in any + and all AAP's.
+ +
Scoped:
+
+
Scoped attributes are a special kind of attribute whose + values are a combination of a value and a + scope, or context for the value. An + example is eduPersonScopedAffiliation, which adds a + scope to the defined set of eduPersonAffiliation + values, such as student, member, or + faculty. Scopes are expressed as DNS domains and + subdomains.
+ +
Any scoped attribute can be + scoped only to the origin site's permitted domains. These + domains are listed in the sites file that provides trust + information to the system. Domains can be explicit or + regular expressions, and can be changed by a target to meet + its needs if a local version of the file is created. Thus, + attribute acceptance processing for scoped + attributes is based on the sites file.
+
+ +
Simple:
+
+
Simple attributes are attributes whose value is expressed + in XML as a Text node; that is, the value is just a string. + Multiple values are permitted. + eduPersonEntitlement, in which the values are URIs, + is one example of a simple attribute.
+
In this release, simple attribute acceptance is + controlled with an external policy file written in XML. The + schema for the file is described by the + eduPerson.xsd schema, and an example file is + included, AAP.xml. If the aap-uri + parameter in the shibboleth.ini file is left out, + then no policy is applied, and no filtering is done. + Otherwise, the rules encoded in the file are used.
+
The policy is a default-deny algorithm that requires + permissible attributes and values be listed explicitly. That + is, an empty file permits nothing. Each attribute to be + permitted must be listed in the file by name in an + <AttributeRule>. Each such rule is a + collection of <SiteRule> elements along with + an optional <AnySite> default rule. In turn + each site rule is a set of <Value> rules that + specify matches to permit, either literal or regular + expressions.
+
+ +
A syntax summary follows:
+
+ +
<AttributeAcceptancePolicy
+
The top level element in the + file.
+ +
<AttributeRule Name="attribute + URI">
+
Specifies a rule for an attribute, named with + its URI.
+
<AnySite>
+
Specifies a rule that always applies to the + attribute, regardless of the asserting AA.
+ +
<SiteRule + Name="site.domain.name">
+
A rule that applies to the origin site AA + corresponding to the domain name.
+ +
<Value Type="type">
+
Specifies a value to permit, either directly + using type literal, or using a set of + matching expressions as type regexp. + literal is the default if Type is not + specified.
+ +
+ +
The regular expression syntax is a subset of the usual + Perl and Unix syntaxes that is described in the XML Schema + specification by the W3C. Most typical expressions should + work. Be sure to anchor them using ^ and $ + to avoid unintentional matches midstring.
+ +
Note that the AAP rules described in this section are not + part of the Shibboleth architecture and are simply one + possible set of approaches implemented in the + eduPerson attribute plugin. The OpenSAML API permits + attribute classes to derive from SAMLAttribute and + override the accept() method to implement + application-specific AAP requirements. The eduPerson source + files can be used as an example of how to build highly + customized rules.
+

+ +

4.f. Using Attributes in + Applications

+ +

+
Apart from the simple RM functionality provided, attribute + information may be made available directly to applications + via the standard practice of creating custom HTTP request + headers before passing control to the application. + Applications should make no assumption about the presence of + specific attributes for their use unless they have intimate + knowledge of the attribute release policies in place.
+ +
The ShibMapAttribute directive controls this + interface, and maps a Shibboleth attribute (identified by an + unambiguous URI) to a header name, such as + Shib-EP-Affiliation. Using that example, any values + of the mapped attribute will be placed in that header, + delimited by spaces. An application that uses a CGI-like + syntax to access the header will find the values in the + HTTP_SHIB_EP_AFFILIATION variable. Using the + command, any attribute can be placed in any header, to drive + legacy applications that expect information in a particular + header.
+ +
The REMOTE_USER variable is a special case that + is generally populated automatically by the web server based + on an internal piece of data that represents the user's + username. Unlike many authentication modules, + Shibboleth does not guarantee that REMOTE_USER will + have any value. If it does, it is set solely based on a + ShibMapAttribute command. For most purposes, the + urn:mace:eduPerson:1.0:eduPersonPrincipalName + attribute should be mapped to REMOTE_USER. Even so, + EPPN may not be provided by the AA, and REMOTE_USER + might still be empty.
+ +
Finally, the ShibExportAssertion flag instructs + the module to place the entire XML message containing the + SAML attribute information from the AA into a base64-encoded + header called Shib-Attributes. This is a raw + interface that provides an application with the entire AA + response, and is not a filtered view based on any attribute + acceptance rules or even based on what attributes are + recognized by the target. What was sent is what you see.
+

+ +

4.g. siterefresh

+ +

+
Shibboleth provides a simple tool called siterefresh in the /opt/shibboleth/bin folder of the + distribution to maintain metadata files referenced by shibboleth.ini. It will return 0 on + success and a negative number on failure and log errors to stderr. If the data in the new metadata + file is bad or the signature is invalid, the existing copy is + kept. The SHAR and SHIRE stat the file each time the data is + used, allowing them to detect and utilize updates in real-time + operation.
+ +
siterefresh takes the following + command-line parameters:
+ +
+
+ --url <URL> +
+ +
+
Specifies the URL of the + remote metadata file to update the local file.
+
+ +
+ --out <pathname> +
+ +
+
Specifies the local file to write the new metadata to.
+
+ +
+ --cert <pathname> +
+ +
+
Specifies the location of a certificate stored in PEM format used to validate the + signature of the metadata file. Since much of Shibboleth's + trust flows from this metadata file, this option is highly + recommended.
+
+ +
+ --schema <pathname> +
+ +
+
Optionally defines a base path for schemas. Defaults to + /opt/shibboleth/etc/shibboleth/.
+
+
+ +
A complete command issued to siterefresh would take the form:
+ +
+ /opt/shibboleth/bin/siterefresh --url + http://wayf.internet2.edu/InQueue/sites.xml --out sites.xml + --cert internet2.pem +
+ +
It is recommended that a similar command be added to a crontab to keep the file refreshed.
+

+ + +
+

+
+ +

5. Troubleshooting

+ +

This section provides basic information about testing + Shibboleth targets. This information is not intended to be + comprehensive, but instead rudimentary guidelines for basic + configuration tests and problems. For more detailed information + or answers to specific problems not addressed in this section, + please mail mace-shib-users@internet2.edu + with a thorough description of errors and configurations + used.

+ +

5.a. Basic Testing

+ +

+
The target may be tested by generating a folder with very + basic access controls on it, and accessing it using a web + browser. Place a simple webpage such as index.html + in /secure/. Then, add the following lines to + httpd.conf, which should be removed when testing is + over:
+ +
+ # Configure a test directory
+ <Location /secure>
+   AuthType shibboleth
+   require valid-user
+
+   # Per-directory SHIRE Configuration
+   #ShibBasicHijack On
+   #ShibSSLOnly On
+   #ShibAuthLifetime 60
+   #ShibAuthTimeout 600
+
+   # RM Configuration
+   #AuthGroupFile /foo
+   #ShibExportAssertion On
+ </Location>
+ +
+ +
For information regarding specific error messages that + may be generated if the target does not work successfully, + please refer to section 4.b, or write mace-shib-users@internet2.edu.
+

+ +

5.b. Common Problems

+ +

+
A knowledge base is being developed in the Shibboleth Deployer's FAQ. Please mail mace-shib-users@ + internet2.edu with any additional questions or problems + encountered that are not answered by this basic guide.
+

+ +

urn:oasis:names:tc:SAML:1.0:am:password	The authentication was performed using a password.
urn:ietf:rfc:1510	The authentication was performed using Kerberos.
urn:oasis:names:tc:SAML:1.0:am:X509-PKI	The authentication was performed using a + certificate and key issued to the end user. More + specific forms of PKI authentication such as SPKI and + XKMS are also assigned URN's in the SAML specs.