From: Scott Cantor Shibboleth Origin Deployment GuideShibboleth Origin Deployment Guide
-
+Shibboleth Origin Deployment Guide
+
Shibboleth Version 1.1
July 28, 2003
+This version of the deploy guide is for Shibboleth v1.1. For documentation
related to prior versions of Shibboleth, please consult the appropriate branch
in the Shibboleth CVS.
@@ -190,6 +189,8 @@ configuration, but some older commands have been deprecated or replaced.
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.
-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 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.
+++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.
+
++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.
+
++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.
+
++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.
+
+
+
+
+
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.
+++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.
+
++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.
+
++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.
+
++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.b.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.
+
++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.
+
++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.
+
++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.
+
++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.
+
+
+
+
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 JDK v1.4.1_01 and above +
+++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 pre-defined attributes.
+
++
- Ensure you have already obtained the proper + .tarball.
+- The archive will expand into a + shibboleth-origin-1.0/ directory(/opt/ + recommended).
+- Run the following command to move the Java files into Tomcat's tree:
+++cp /opt/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 + /opt/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.
++<Location /shibboleth/AA> + SSLVerifyClient optional SSLOptions +StdEnvVars +ExportCertData + </Location>
+
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.
- -
+
+
++This section of the deploy guide specifies only the essential changes + that need to be made to the configuration defaults for the origin to + function successfully in a federated environment. More complex configuration + will likely be required for many applications and federations; for a full + description of every field in origin.properties, + please refer to section 5.a.
+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/.
++
+- + edu.internet2.middleware.shibboleth.hs.HandleServlet.issuer = <domain + name> +
+++This will be, in most cases, the DNS name of the machine on which + the HS runs. It must match the CN of the certificate used below.
+- + edu.internet2.middleware.shibboleth.hs.HandleServlet.siteName = <URI> +
+++The value of this must entered as assigned by the federation used + for testing or initial operation.
+- + edu.internet2.middleware.shibboleth.hs.HandleServlet.AAUrl = <url> +
+++This will be the URL assigned the AA servlet in step + 3.b. Note that this must be an + https:// URL in order for the AA to + know which SHAR is requesting attributes.
+- +
+
+- + edu.internet2.middleware.shibboleth.hs.HandleServlet.keyStorePath = + <pathname>
+- + edu.internet2.middleware.shibboleth.hs.HandleServlet.keyStorePassword + = <password>
+- + edu.internet2.middleware.shibboleth.hs.HandleServlet.keyStoreKeyAlias + = <alias>
+- + edu.internet2.middleware.shibboleth.hs.HandleServlet.keyStoreKeyPassword + = <password>
+- + edu.internet2.middleware.shibboleth.hs.HandleServlet.certAlias = + <alias>
+++Respectively, the location and password of the Java keystore + containing the x.509 certificate and matching private key to be used + by the HS, the alias and password of the private key, and the + optional certificate alias, if it differs from the key's alias.
+- + 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.audiences = <URI> +
+++This section must contain the URI of the federation under which + the origin will operate or test initially. This will be provided by + the federation.
+
+
++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.d.
+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 ( <!-- and --> ).
+
+
++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:
-- -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.
+$ 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
+1.b. Target
- +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:
-- -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.
+$ keytool -certreq -keystore keystore.jks + -alias hs -file <csr-file>
+1.c. Where are you from? (WAYF)
- +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:
-- -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.
+$ keytool -import -keystore keystore.jks + -alias hs -file <cert-file>
1.d. Federations
- +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.c..
+
++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:
--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.
+<Location /shibboleth/HS>
+ AuthType Basic
+ AuthName "Internet2 Handle Service"
+ AuthUserFile /usr/local/apache/conf/user.db
+ require valid-user
+ </Location>
+
-
-
-
-
- - -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
- +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.
+
+-- -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.
+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.
2.c. Security Considerations
- +
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.b.i.
+
+
+
++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. Note that this must + be an https:// URL in order for the AA + to know which SHAR is requesting attributes.
+- + 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)
-- -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.
-+
- + 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.
+2.d. Server Certs
- +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.
-- -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.
++
- + 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.
+2.e. Attribute Release Policies
- +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.
+
++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.
+
+-- -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.b.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.
+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.
+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.
+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:dir:attribute-def:eduPersonScopedAffiliation">
+ + <AnyValue release= "permit"/>
+ + </Attribute >
+ </Rule >
+ </AttributeReleasePolicy>
+2.g. Browser Requirements
- +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:
-- -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.
+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.
+2.h. Clocks
- +The Attribute element:
-- -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.
+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:dir:attribute-def:eduPersonPrincipalName">
+
+ <AnyValue release="Permit">
+ </Attribute>
+
+Permits the release of + eduPersonPrincipalName with any value.
++<Attribute name="urn:mace:dir:attribute-def: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.
+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 JDK v1.4.1_01 and above - -
- ---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 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(/opt/ recommended).
-- -
- -Run the following command to move the Java files into - Tomcat's tree:
- -- cp /opt/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 /opt/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.
-- -
-It is strongly recommended that the AA be SSL-protected to protect attributes in transit. To do so, add an appropriate location block to httpd.conf:
-- <Location /shibboleth/AA> - SSLVerifyClient optional - SSLOptions +StdEnvVars +ExportCertData - </Location> --
-
-
- - -4. Getting Running
- -4.a. Basic Configuration
- ---This section of the deploy guide specifies only the - essential changes that need to be made to the configuration - defaults for the origin to function successfully in a - federated environment. More complex configuration will likely - be required for many applications and federations; for a full - description of every field in origin.properties, please refer to - section 5.a.
- -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/.
- --
-- edu.internet2.middleware.shibboleth.hs.HandleServlet.issuer - = <domain name> -
-This will be, in most cases, the DNS name of the machine on which the HS runs. It must match the CN of the certificate used below.-- edu.internet2.middleware.shibboleth.hs.HandleServlet.siteName - = <URI> -
-The value of this must entered as assigned by the - federation used for testing or initial operation.-- edu.internet2.middleware.shibboleth.hs.HandleServlet.AAUrl - = <url> -
-This will be the URL assigned the AA servlet in - step 3.b. Note that this must be - an https:// URL in order for - the AA to know which SHAR is requesting - attributes.-- -
--
- -- edu.internet2.middleware.shibboleth.hs.HandleServlet.keyStorePath - = <pathname>
-- edu.internet2.middleware.shibboleth.hs.HandleServlet.keyStorePassword - = <password>
-- edu.internet2.middleware.shibboleth.hs.HandleServlet.keyStoreKeyAlias - = <alias>
-- edu.internet2.middleware.shibboleth.hs.HandleServlet.keyStoreKeyPassword - = <password>
-- edu.internet2.middleware.shibboleth.hs.HandleServlet.certAlias - = <alias>
Respectively, the location and password of - the Java keystore containing the x.509 certificate and - matching private key to be used by the HS, the alias - and password of the private key, and the optional - certificate alias, if it differs from the key's - alias.-- 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.audiences - = <URI> - -
-This section must contain the URI of the - federation under which the origin will operate or test - initially. This will be provided by the - federation.
- -4.a.i 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.d.
- -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 ( <!-- and --> ).
- -
- -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.c..
-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.b.i.
-
-
-
- -5. Advanced Configuration
- -origin.properties
- ---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. - Note that this must be an https:// URL in order for - the AA to know which SHAR is requesting - attributes.
-- - 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. -
- -5.b. 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.b.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.b.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:dir:attribute-def: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:dir:attribute-def:eduPersonPrincipalName">- -
- <AnyValue release="Permit">
- </Attribute>
-
-Permits the release of eduPersonPrincipalName - with any value.
-- - <Attribute name="urn:mace:dir:attribute-def: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.c. 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:
- +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
+- 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
+- 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
+- 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
+- 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
+- The following command will export the corresponding certificate.
- -+-$ keytool -export -keystore + yourstore -alias youralias -rfc -file yourcert
- -
+Set the mod_ssl +
- 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. -
+ 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:
- +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
+- 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
+- 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.
- -+- - 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. -$ cat mycert ca.cert > cert.bundle
- -
+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
+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
+- 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.
-- 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:
- +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
+- 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 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.
-- 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.d. 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.
-- - <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:attribute-def:eduPersonPrincipalName" smartScope="shibdev.edu" sourceName="universityPerson">- -
- <DataConnectorDependency requires="dataConnector"/>
- <AttributeDependency requires="urn:mace:dir:attribute-def:eduPersonScopedAffiliation"/>
- <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:attribute-def: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.
-
-5.d.i resolvertest
- +
+
++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:
- -- -Shibboleth comes bundled with the command line utility resolvertest for testing Attribute Resolver configurations. This program takes as input resolver.xml, the name of a user, and optionally the name of a requesting SHAR. It outputs the resulting SAML <Attribute /> elements. This allows administrators to view the results of tweaking the resolver configuration without having to continually reload the origin web application. Initially, the following two steps must be performed:
- --
- -- Set the shell variable SHIB_HOME to the directory path where the Shibboleth tarball was exploded (typically /opt/shibboleth-origin-1.0/).
-- Move to $SHIB_HOME/bin
-resolvertest may then be used by executing the shell script, passing the name of a user and a URL to the Attribute Resolver configuration file as parameters. For example:
- -$ ./resolvertest --user=wassa --file=file:///$SHIB_HOME/src/conf/resolver.xml- -NOTE: This program does not filter the resulting attributes through the applicable ARP's. Although it does show the attributes generated by the resolver for a particular user or URL, it does not necessarily reflect what will be released by the AA to a requesting SHAR.
+<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>
-5.e. Local Error Page
+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.
+- <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:
-- -Origin sites are encouraged to provide federations with the - URL of a local Shibboleth error page. If a browser user from the - origin site encounters a problem at a shibbolized target, the target - is likely to display an error page that includes a link back to this - origin provided page.
- -The page should provide information on how to obtain local support - for using Shibbolized resources. It might also include suggestions on - what information should be recorded before beginning the problem - resolution process.
+<SimpleAttributeDefinition id="urn:mace:dir:attribute-def:eduPersonPrincipalName" + smartScope="shibdev.edu" sourceName="universityPerson">
+ <DataConnectorDependency requires="dataConnector"/>
+ <AttributeDependency requires="urn:mace:dir:attribute-def:eduPersonScopedAffiliation"/>
+ <cacheTime="600"/><br>
+ <lifeTime="3600"/><br>
+ </SimpleAttributeDefinition>
-
-
-
- - -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
- +A properly formed resolver.xml file to + automatically generate a simple response for EPPN may take the form:
-- -Internet2 provides a basic target that can be used to test - origin setup functionality. After your origin is recognized - by InQueue, simply use any browser to access https://wayf.internet2.edu/InQueue/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.
+<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:attribute-def:eduPersonPrincipalName" + smartScope="shibdev.edu">
+ <DataConnectorDependency requires="echo"/>
+ </SimpleAttributeDefinition>
+
+ <CustomDataConnector id="echo" + class="edu.internet2.middleware.shibboleth.aa.attrresolv.provider.SampleConnector" + />
+ </AttributeResolver>6.b. Logging
- +There are additional examples of resolver.xml + files provided in the + + Shibboleth CVS.
+
+
++Shibboleth comes bundled with the command line utility + resolvertest for testing Attribute Resolver + configurations. This program takes as input + resolver.xml, the name of a user, and optionally the name of a + requesting SHAR. It outputs the resulting SAML <Attribute /> elements. This + allows administrators to view the results of tweaking the resolver + configuration without having to continually reload the origin web + application. Initially, the following two steps must be performed:
++
+- Set the shell variable SHIB_HOME to + the directory path where the Shibboleth tarball was exploded (typically + /opt/shibboleth-origin-1.0/).
+- Move to $SHIB_HOME/bin
+resolvertest may then be used by + executing the shell script, passing the name of a user and a URL to the + Attribute Resolver configuration file as parameters. For example:
-+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.
+$ ./resolvertest --user=wassa + --file=file:///$SHIB_HOME/src/conf/resolver.xml
NOTE: This program does not filter the resulting attributes through the + applicable ARP's. Although it does show the attributes generated by the + resolver for a particular user or URL, it does not necessarily reflect what + will be released by the AA to a requesting SHAR.
+
+
++Origin sites are encouraged to provide federations with the URL of a + local Shibboleth error page. If a browser user from the origin site + encounters a problem at a shibbolized target, the target is likely to + display an error page that includes a link back to this origin provided + page.
+The page should provide information on how to obtain local support for + using Shibbolized resources. It might also include suggestions on what + information should be recorded before beginning the problem resolution + process.
+
+
+
+
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.
+++Internet2 provides a basic target that can be used to test origin setup + functionality. After your origin is recognized by InQueue, simply use any + browser to access + https://wayf.internet2.edu/InQueue/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.
+
++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.
+
++ + -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.
+
--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.
-