X-Git-Url: http://www.project-moonshot.org/gitweb/?a=blobdiff_plain;f=doc%2FDEPLOY-GUIDE-TARGET.html;h=c5d0bcc074c9c26d971a191d6599fb8414840a55;hb=1d30f9677d1820b8e250466e2a11bb56f82d29f4;hp=1594a771ec36af3c9c50b061ef43b4aa1d170457;hpb=b027046618f936f7aca689c16d5ce2d9ae344ea5;p=shibboleth%2Fsp.git diff --git a/doc/DEPLOY-GUIDE-TARGET.html b/doc/DEPLOY-GUIDE-TARGET.html index 1594a77..c5d0bcc 100644 --- a/doc/DEPLOY-GUIDE-TARGET.html +++ b/doc/DEPLOY-GUIDE-TARGET.html @@ -1,11 +1,13 @@ - - + -
-Shibboleth v1.0 is stable and secure enough to deploy in - production scenarios. While attempts have been made to include all - functionality that would represent a break of interoperability with - previous versions in v1.0, be aware that future versions of - Shibboleth are likely to be developed and may include further - implementation of the architectural document, functional - enhancements, and user interface improvements.
- -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 Target Deployment Guide
+Shibboleth Version 1.0.1
+July 15, 2003
+
Shibboleth v1.0.1 is stable and secure enough to deploy in production +scenarios. It is backward compatible with 1.0 in all respects, including +configuration, but some older commands have been deprecated or replaced.
+Features and changes specific to 1.0.1 are marked with +[1.0.1]
+This new release contains several improvements and enhancements, including: +
+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 is also supplied; the - directory is provided by the origin site. Shibboleth is able - to interface with a directory exporting an LDAP interface or a - SQL database containing user attributes, and is designed such - that programming interfaces to other repositories should be - readily implemented. Shibboleth relies on standard web server - mechanisms to trigger local authentication. A .htaccess file - can be easily used to trigger either the local WebISO system - or the web server's own Basic Auth mechanism, which will - likely utilize an enterprise authentication system, such as - Kerberos.
- -From the origin site's point of view, the first contact - will be the redirection of a user to the handle service, - which will then consult the SSO system to determine whether - the user has already been authenticated. If not, then the - browser user will be asked to authenticate, and then sent - back to the target URL with a handle bundled in an attribute - assertion. Next, a request from the Shibboleth Attribute - Requester (SHAR) will arrive at the AA which will include the - previously mentioned handle. The AA then consults the ARP's - for the directory entry corresponding to the handle, queries - the directory for these attributes, and releases to the SHAR - all attributes the SHAR is entitled to know about that - user.
-
-- -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 federation provides part of the underlying trust required for - function of the Shibboleth architecture. A federation in the - context of Shibboleth is a group of organizations(universities, - corporations, content providers, etc.) who agree to exchange - attributes using the SAML/Shibboleth protocols and abide by a - common set of policies and practices. In so doing, they must - implicitly or explicitly agree to a common set of guidelines. - Joining a federation is not explicitly necessary for operation of - Shibboleth, but it dramatically expands the number of targets and - origins that can interact without defining bilateral agreements - between all these parties.
- -A federation can be created in a variety of formats and trust - models, but to support Shibboleth, it must provide a certain set - of services to federation members. It needs to supply a registry - to process applications to the federation and distribute - membership information to the origin and target sites. This must - include distribution of the PKI components necessary for trust - between origins and targets. There also needs to be a set of - agreements and best practices defined by the federation governing - the exchange, use, and population of attributes before and after - transit, and there should be a way to find information on local - authentication and authorization practices for federation - members.
-
There are several essential elements that must be present in - the environment to ensure Shibboleth functions well, both - political and technical. Shibboleth currently runs on a - specific range of platforms and web server environments. The - SHAR and SHIRE are implemented entirely in C/C++. These are the - recommendations and requirements for a successful implementation - of a Shibboleth target.
- --- -Shibboleth currently only supports Linux and Solaris. At - present, Shibboleth consists of Apache plugins and a separate SHAR - process. The plugins use the ONC RPC mechanism to communicate with - the SHAR. The target's web servers must be running Apache 1.3.26+, but - not Apache 2. More precise technical details are discussed in 3.a.
-
-- -While it is not necessary for a target or origin to join a - federation, doing so greatly facilitates the implementation of - multilateral trust relationships. Each federation will have a - different application process.
- -For more information on federations, refer to 1.d or the Shibboleth v1.0 architectural - document.
-
-- -Shibboleth's protocols and software have been extensively - engineered to provide protection against many attacks. - However, the most secure protocol can be compromised if it is - placed in an insecure environment. To ensure Shibboleth is as - secure as possible, there are several recommended security - precautions which should be in place at local sites.
- --
-- -
- -SSL use is optional for target sites. Federation guidelines - should be considered when determining whether to - implement SSL, and, in general, SSL should be used for - interactions with client machines to provide the - necessary authentication and encryption to ensure - protection from man-in-the-middle attacks. It is strongly - suggested that all password traffic or similarly - sensitive data should be SSL-protected. Assessment of the - risk tradeoff against possible performance degradation - should be performed for all applications.
-- -
- -Many other attacks can be made on the several - redirection steps that Shibboleth takes to complete - attribute transfer. The best protection against this is - safeguarding the WAYF service and ensuring that rogue - targets and origins are not used, generally by - development of the trust model underneath Shibboleth. - Shibboleth also leverages DNS for security, which is not - uncommon, but attacks concerning bad domain information - should be considered.
-- -
- -Information regarding origin users is generally - provided by the authoritative enterprise directory, and - the acceptance of requests from target applications can - be carefully restricted to ensure that all requests the - SHAR performs are authorized and all information the - origin provides is accurate. Use of plaintext passwords - is strongly advised against.
-- -
-Server platforms should be properly secured, - commensurate with the level that would be expected for a - campus' other security services, and cookie stores on - client machines should be well protected.
-
-- -In the Shibboleth architecture, the SHAR, HS, and AA must - all have various client and/or server certificates for use in - signing assertions and creating SSL channels. These should be - issued by a commonly accepted CA, which may be stipulated by - your federation. After understanding the CA's acceptible to your - federations, consult chapter 4.c for - information on certificate and key generation.
-
-- -The Attribute Authority maintains a set of rules called - Attribute Release Policies (ARP's) that define which - attributes are released to which targets. When a browser user - tries to access a resource, the SHAR asks the origin site AA - to release all the attributes it is allowed to know. The SHAR - provides its own name and an optional URL on behalf of which - the attribute request is made which can further refine the - information the SHAR is allowed to know. The AA processes this - request using all applicable ARP's, determines which - attributes and values it will release, and then obtains the - values actually associated with the browser user. The AA sends - these attributes and values back to the SHAR.
- -Targets should work together with expected origin sites to - ensure that the sets of attributes that both sites expect to - correspond using are congruent.
-
-- -Since Shibboleth deals both with daily technical and - operational issues and also with contractual issues, a set of - contacts should be set up to support the user base and to - facilitate interactions with other Shibboleth sites and federation - members. It is recommended that at least technical and - administrative contacts be designated. Names, titles, e-mail - addresses, and phone numbers may all be useful information to - provide.
-
-- -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 Shibboleth project makes binary packages available for - Solaris and Linux that are precompiled against recent releases - of various required libraries such as OpenSSL. It is highly - advisable to build from source when using Shibboleth in a - production environment in order to permit patching or updating - of packages as security holes and bugs are fixed. Building from - source is necessary to give you complete control over your - deployment platform. The binary packages represent a snapshot in - time only. To build from source, see the INSTALL.txt - files in the root of the OpenSAML and Shibboleth source - distributions.
- -- Operating System: - --
- - RedHat 7.2-7.3: - -
-
- - Apache 1.3.27 - -
+-- -Apache must be compiled with mod_so for DSO - module support, and must include SSL - support (preferably using mod_ssl), and - EAPI support (which mod_ssl requires and - provides). Shibboleth can coexist with - mod_auth, which may be compiled or loaded - into the server for use elsewhere, but Shibboleth - does not need or use it. The most recent Red Hat - RPM (1.3.23-14 as of this writing) is sufficient. -
--On Linux, Shibboleth requires that Apache and - Apache-SSL be built with libpthread, or loading the - mod_shibrm or mod_shire modules will - cause Apache to stop. While RedHat's Apache is - compatible, Debian's Apache must be rebuilt with - libpthread:
+- +
+Planning
+ +- +
+Installation
+ +- +
+Getting Running
+ +- +
+Troubleshooting
++
+- Basic Testing
+- Common Problems
+
+
+
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 is also supplied; + the directory is provided by the origin site. Shibboleth is able to + interface with a directory exporting an LDAP interface or a SQL database + containing user attributes, and is designed such that programming interfaces + to other repositories should be readily implemented. Shibboleth relies on + standard web server mechanisms to trigger local authentication. A .htaccess + file can be easily used to trigger either the local WebISO system or the web + server's own Basic Auth mechanism, which will likely utilize an enterprise + authentication system, such as Kerberos.
+From the origin site's point of view, the first contact will be the + redirection of a user to the handle service, which will then consult the SSO + system to determine whether the user has already been authenticated. If not, + then the browser user will be asked to authenticate, and then sent back to + the target URL with a handle bundled in an attribute assertion. Next, a + request from the Shibboleth Attribute Requester (SHAR) will arrive at the AA + which will include the previously mentioned handle. The AA then consults the + ARP's for the directory entry corresponding to the handle, queries the + directory for these attributes, and releases to the SHAR all attributes the + SHAR is entitled to know about that user.
+
++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 federation provides part of the underlying trust required for function + of the Shibboleth architecture. A federation in the context of Shibboleth is + a group of organizations(universities, corporations, content providers, + etc.) who agree to exchange attributes using the SAML/Shibboleth protocols + and abide by a common set of policies and practices. In so doing, they must + implicitly or explicitly agree to a common set of guidelines. Joining a + federation is not explicitly necessary for operation of Shibboleth, but it + dramatically expands the number of targets and origins that can interact + without defining bilateral agreements between all these parties.
+A federation can be created in a variety of formats and trust models, but + to support Shibboleth, it must provide a certain set of services to + federation members. It needs to supply a registry to process applications to + the federation and distribute membership information to the origin and + target sites. This must include distribution of the PKI components necessary + for trust between origins and targets. There also needs to be a set of + agreements and best practices defined by the federation governing the + exchange, use, and population of attributes before and after transit, and + there should be a way to find information on local authentication and + authorization practices for federation members.
+
There are several essential elements that must be present in the environment +to ensure Shibboleth functions well, both political and technical. Shibboleth +currently runs on a specific range of platforms and web server environments. The +SHAR and SHIRE are implemented entirely in C/C++. These are the recommendations +and requirements for a successful implementation of a Shibboleth target.
+++Shibboleth currently supports Windows NT/2000/XP/2003, Linux, and + Solaris. At present, Shibboleth consists of Apache (or IIS) plugins and a + separate SHAR process. The plugins use the ONC RPC mechanism to communicate + with the SHAR over Unix domain or TCP sockets. The target's web servers must + be running Apache + 1.3.26+, or Microsoft IIS 4.0+, but not Apache 2. More precise technical + details are discussed in 3.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.
+For more information on federations, refer to 1.d or + the Shibboleth v1.0 architectural document.
+To use Shibboleth without a federation, manual configuration of target + and origin trust and site information will be needed to insure that sites + interoperate. Most identifiers, such as site names, should be URI-based, and + should be chosen in accordance with DNS domains under the control of the + parties involved, much as Java package naming is coordinated. In other + words, don't use a URI containing a DNS domain or hostname that you do not + control.
+
++Shibboleth's protocols and software have been extensively engineered to + provide protection against many attacks. However, the most secure protocol + can be compromised if it is placed in an insecure environment. To ensure + Shibboleth is as secure as possible, there are several recommended security + precautions which should be in place at local sites.
++
+- SSL use is optional for target sites, but should be used if at all + possible, at least in the processing of incoming sessions (called the + SHIRE URL or assertion consumer service). Federation guidelines should + be considered when determining whether to implement SSL, and, in + general, SSL should be used for interactions with client machines to + provide the necessary authentication and encryption to ensure protection + from man-in-the-middle attacks. It is strongly suggested that all + password traffic or similarly sensitive data should be SSL-protected. + Assessment of the risk tradeoff against possible performance degradation + should be performed for all applications.
+- Many other attacks can be made on the several redirection steps that + Shibboleth takes to complete attribute transfer. The best protection + against this is safeguarding the WAYF service and ensuring that rogue + targets and origins are not used, generally by development of the trust + model underneath Shibboleth. Shibboleth also leverages DNS for security, + which is not uncommon, but attacks concerning bad domain information + should be considered.
+- Information regarding origin users is generally provided by the + authoritative enterprise directory, and the acceptance of requests from + target applications can be carefully restricted to ensure that all + requests the SHAR performs are authorized and all information the origin + provides is accurate. Use of plaintext passwords is strongly advised + against.
+- Server platforms should be properly secured, commensurate with the + level that would be expected for an organization's other security + services, and cookie stores on client machines should be well protected.
+
++In the Shibboleth architecture, the SHAR, HS, and AA must all have + various client and/or server certificates for use in signing assertions and + creating SSL channels. These should be issued by a commonly accepted CA, + which may be stipulated by your federation. After understanding the CA's + acceptible to your federations, consult chapter 4.c for + information on certificate and key generation.
+
++The Attribute Authority maintains a set of rules called Attribute Release + Policies (ARP's) that define which attributes are released to which targets. + When a browser user tries to access a resource, the SHAR asks the origin + site AA to release all the attributes it is allowed to know, possibly + restricted to specifically desired subset. The SHAR provides its own name + and an optional URL on behalf of which the attribute request is made which + can further refine the information the SHAR is allowed to know. The AA + processes this request using all applicable ARP's, determines which + attributes and values it will release, and then obtains the values actually + associated with the browser user. The AA sends these attributes and values + back to the SHAR.
+Targets should work together with expected origin sites to ensure that + the sets of attributes that both sites expect to correspond using are + congruent.
+
++Since Shibboleth deals both with daily technical and operational issues + and also with contractual issues, a set of contacts should be set up to + support the user base and to facilitate interactions with other Shibboleth + sites and federation members. It is recommended that at least technical and + administrative contacts be designated. Names, titles, e-mail addresses, and + phone numbers may all be useful information to provide.
+
++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 Shibboleth project makes binary packages available for Solaris and Linux +that are precompiled against recent releases of various required libraries such +as OpenSSL. It is highly advisable to build from source when using Shibboleth in +a production environment in order to permit patching or updating of packages as +security holes and bugs are fixed. Building from source is necessary to give you +complete control over your deployment platform. The binary packages represent a +snapshot in time only. To build from source, see the +INSTALL.txt files in the doc folder of the OpenSAML and Shibboleth source +distributions.
+The software requirements listed correspond to the binary distributions. In +general, source builds should work against all recent versions of the operating +systems and software dependencies listed below. For specific questions, inquire +to the support mailing list, or give it a try. Note that OpenSSL releases +frequent security updates; the version listed may not be the most current, but +most minor "letter" updates should be usable.
++- -Operating System:
++
- RedHat 7.2-7.3:
+
- Apache 1.3.27
++Apache must be compiled with mod_so for DSO module support, + and must include SSL support (preferably using + mod_ssl), and EAPI support (which + mod_ssl requires and provides). + Shibboleth can coexist with mod_auth, + which may be compiled or loaded into the server for use + elsewhere, but Shibboleth does not need or use it. The most + recent Red Hat RPM (1.3.27-2 as of this writing) is sufficient.
+++On Linux, Shibboleth requires that Apache and Apache-SSL be + built with libpthread, or loading the + mod_shibrm or + mod_shire modules will cause Apache to stop. While + RedHat's Apache is compatible, Debian's Apache must be rebuilt + with libpthread:
- $ export LDFLAGS=-lpthread'-
- $ apt-build --rebuild --reinstall install apache-common apache \ apache-ssl +$ export LDFLAGS=-lpthread
+ $ apt-build --rebuild --reinstall install \
+ apache-common apache apache-ssl
-+ + Shibboleth v1.0.1 Target for RedHatShibboleth binaries are currently built with GCC - 3.04, and require these specific library - versions. They are available as RPMs and are - available in the RedHat 7.2 updates directory on - any - RedHat mirror. They can be installed alongside - earlier and later GCC libraries.
-
+Shibboleth binaries are currently built with + GCC 3.04, + and require these specific library versions. They are available + as RPMs and are available in the RedHat 7.2 updates directory on + any + + RedHat mirror. They can be installed alongside earlier and + later GCC libraries.
+
-+The shared library version of OpenSSL is required - by Shibboleth. The static libraries may be installed as - well if necessary for other applications, but cannot be - used within mod_ssl or any other Apache modules.
-
+
++The shared library version of OpenSSL is required by + Shibboleth. The static libraries may be installed as well if + necessary for other applications, but cannot be used within + mod_ssl or any other Apache modules.
+
+Apache must be compiled with mod_so for DSO module support, + and must include SSL support (preferably using + mod_ssl) and EAPI support (which + mod_ssl requires and provides). + Shibboleth can coexist with mod_auth, + which may be compiled or loaded into the server for use + elsewhere, but Shibboleth does not need or use it.
+mod_ssl's loadable module, + libssl.so, must be compiled against + OpenSSL 0.9.7b's shared libraries. + Other versions or a statically linked build of + libssl.so will cause failures such as + bus errors when used with Shibboleth.
+To check how OpenSSL was built, run the + ldd command against libssl.so + in the Apache /libexec/ folder and + check the output for references to + libssl.so.0.9.7b. If you see an earlier version + mentioned, or no mention of it at all, then + OpenSSL 0.9.7b must be built with shared libraries from + source, and the Apache module rebuilt with it.
+
-+ + libgcc v3.2.2+ and libstdc++ v3.2.2+Apache must be compiled with mod_so for DSO - module support, and must include SSL - support (preferably using mod_ssl) and EAPI - support (which mod_ssl requires and - provides). Shibboleth can coexist with - mod_auth, which may be compiled or loaded - into the server for use elsewhere, but Shibboleth - does not need or use it.
- -mod_ssl's - loadable module, libssl.so, must be - compiled against OpenSSL - 0.9.7a's shared libraries. Other versions or - a statically linked build of libssl.so will cause - failures such as bus errors when used with - Shibboleth.
- -To check how OpenSSL was built, run the ldd command against libssl.so in the Apache - /libexec/ folder and - check the output for references to libssl.so.0.9.7a. If you - see an earlier version mentioned, or no mention of - it at all, then OpenSSL - 0.9.7a must be rebuilt with shared libraries - from source.
-
+Shibboleth binaries are currently built with + GCC 3.2.2, + and require these specific library versions or newer. They are + available as Sun freeware packages and can be installed + alongside earlier and later GCC libraries.
+
--RedHat 8 ships with Apache 2, which is not supported by - Shibboleth. To run Shibboleth under this OS, Apache 1.3.27 - must be installed.
-
-- -Apache must be compiled with mod_so for DSO - module support, and must include SSL - support (preferably using mod_ssl), and - EAPI support (which mod_ssl requires and - provides). Shibboleth can coexist with - mod_auth, which may be compiled or loaded - into the server for use elsewhere, but Shibboleth - does not need or use it. The most recent Red Hat - RPM (1.3.23-14 as of this writing) is sufficient. -
-
-- -On Linux, Shibboleth requires that Apache and - Apache-SSL be built with libpthread, or loading the - mod_shibrm or mod_shire modules will - cause Apache to stop. While RedHat's Apache is - compatible, Debian's Apache must be rebuilt with - libpthread:
-- $ export LDFLAGS=-lpthread'-
- $ apt-build --rebuild --reinstall install apache-common apache \ apache-ssl -
++RedHat 8 and 9 ship with Apache 2, which is not yet supported by + Shibboleth. To run Shibboleth under this OS, + Apache 1.3.27 must + be installed.
+
++Apache must be compiled with mod_so for DSO module support, and + must include SSL support (preferably using + mod_ssl), and EAPI support (which mod_ssl + requires and provides). Shibboleth can coexist with + mod_auth, which may be compiled or loaded + into the server for use elsewhere, but Shibboleth does not need or + use it. The most recent Red Hat RPM (1.3.23-14 as of this writing) + is sufficient.
+
++On Linux, Shibboleth requires that Apache and Apache-SSL be built + with libpthread, or loading the + mod_shibrm or + mod_shire modules will cause Apache to stop. While RedHat's + Apache is compatible, Debian's Apache must be rebuilt with + libpthread:
+++$ export LDFLAGS=-lpthread
+
+ $ apt-build --rebuild --reinstall install apache-common \
+ apache apache-ssl
-+ + Shibboleth 1.0.1 Target for RedHatShibboleth binaries are currently built with GCC - 3.04, and require these specific library - versions. They are available as RPMs and are - available in the RedHat 7.2 updates directory on - any - RedHat mirror. They can be installed alongside - earlier and later GCC libraries.
-
+Shibboleth binaries are currently built with + GCC 3.04, + and require these specific library versions. They are available + as RPMs and are available in the RedHat 7.2 updates directory on + any + + RedHat mirror. They can be installed alongside earlier and + later GCC libraries.
+
-+For the sake of clarity, this deployment guide assumes - that standard directories are used for all installations. - These directories may be changed for local implementations, - but must be done so consistently.
- --
+- -
- -Ensure that you have obtained the proper - tarball for your operating system.
-- -
+The tarballs expand into /opt/shibboleth, - and should be expanded as root from /. - You should see the following directory structure:
- -- $ ls -al+
- drwxr-xr-x 10 root root 4096 Oct 24 03:54 .
- drwxr-xr-x 3 root root 4096 Oct 24 00:37 ..
+ +3.b. Deploy the Shibboleth Package
++- -For the sake of clarity, this deployment guide assumes that standard + directories are used for all installations. These directories may be changed + for local implementations, but must be done so consistently.
++
-- Ensure that you have obtained the proper + + tarball for your operating system.
+- On Unix, the tarballs expand into + /opt/shibboleth, and should be expanded as + root from /. If you use a different + layout or location, you will need to adjust your configuration files. + You should see the following directory structure (date and size details + notwithstanding):
-+-$ ls -l
drwxr-xr-x 2 root root 4096 Oct 24 03:54 bin
drwxr-xr-x 2 root root 4096 Oct 24 03:54 doc
drwxr-xr-x 4 root root 4096 Oct 24 03:54 etc
drwxr-xr-x 13 root root 4096 Oct 24 03:54 include
drwxr-xr-x 4 root root 4096 Oct 24 03:55 lib
drwxr-xr-x 2 root root 4096 Oct 24 03:55 libexec
- drwxr-xr-x 4 root root 4096 Oct 24 02:02 share
- -3.c. Configure Apache
- --+-
- -
- -Shibboleth includes configuration directives in the - file /opt/shibboleth/etc/shibboleth/apache.config - which must be added to the httpd.conf file used locally. - It is recommended that these directives simply be added - to the end of the existing httpd.conf file - rather than trying to merge it in-line; - step 2 describes the necessary - modifications to the Apache startup script. The default - configuration will often work, but if customization is - necessary, these options may be modified:
- -- -
- -- - LoadModule <module> - <pathname> -
- -- -
- -Specifies the title and location of the - shibrm_module resource manager and - shire_module SHIRE modules. These are - installed by default at - /opt/shibboleth/libexec/mod_shibrm.so - and - /opt/shibboleth/libexec/mod_shire.so
-- - SHIREConfig <pathname> -
- -- -
- -Specifies the pathname of the SHIRE's - configuration file. Defaults to - /opt/shibboleth/etc/shibboleth/shibboleth.ini.
-- SHIREURL <url>
- -
- <Location <url>>
- SetHandler <method>
- </Location>- -
- -Specifies the URL and the - method the target uses to handle - requests for Shibboleth-protected resources. - Currently, shib-shire-post is the only - available handler method. - SHIREURL is used by Shibboleth when - re-directing the user to the WAYF and - <Location> by Apache; for this - reason, both URL specifications must - match. Note that the configuration file itself - contains <>'s, and Location should - not be replaced.
- -The referenced URL can be either a - partial path or an absolute URL. The partial path - allows each virtual server to use its own - hostname and port in the SHIRE for session cookie - purposes, while the absolute URL forces HTTP - virtual servers to use HTTPS for the SHIRE. Use - of a full https:// URL is advised.
-- - ShibMapAttribute <attribute-uri> - <HTTP-header> [alias] -
- -- -
-Registers attributes to be recognized and maps - them to an authorization alias for use - in .htaccess files or Location Blocks - with require directives. - REMOTE_USER is a special case, suggested - for use with eduPersonPrincipalName, and - is automatically checked by a require - user rule.
-- - - -
- -These modifications must be made to the Apache startup - script:
- -Add the following environment variables:
- -- - SHIBCONFIG=/opt/shibboleth/etc/shibboleth/shibboleth.ini; - export SHIBCONFIG -- -If the OpenSSL libraries are not in the system's search - path, they should be added to LD_LIBRARY_PATH as - well.
- -If the SHIBCONFIG environment variable is not - specified, Shibboleth will use - /opt/shibboleth/etc/shibboleth/shibboleth.ini by - default.
-- -
The SHAR must be started before Apache. Among other - methods, this can be done either by creating a separate - SHAR startup script or by modifying Apache's RC script to - start/stop the SHAR before - httpd. It is suggested that Apache's script be - modified by adding:
- -- /opt/shibboleth/bin/shar -f & -- -Sample init.d scripts may be included with - future releases. Ensure that the environment variables - referenced in 3.c.2 are in - place.
- + drwxr-xr-x 4 root root 4096 Oct 24 02:02 share +On Windows, until a real installer is available, the zip file should + be unpacked beneath the root of the system drive, where it will create + an \opt\shibboleth tree that resembles the + Unix layout above. This will allow the standard configuration options to + work. The C:\opt\shibboleth\lib directory + MUST be added to the system path to enable proper operation.
+++
+- Shibboleth includes configuration directives in the file + /opt/shibboleth/etc/shibboleth/apache.config + which must be added to the httpd.conf file used locally. It is + recommended that these directives simply be added to the end of the + existing httpd.conf file rather than trying + to merge it in-line; step 2 describes the + necessary modifications to the Apache startup script. The default + configuration will often work, but if customization is necessary, these + options may be modified:
- -+
- LoadModule <module> + <pathname>
+- Specifies the title and location of the + shibrm_module resource manager and + shire_module SHIRE modules. These are + installed by default at /opt/shibboleth/libexec/mod_shibrm.so + and /opt/shibboleth/libexec/mod_shire.so
+- SHIREConfig <pathname> +
+- Specifies the pathname + of the SHIRE's configuration file. Defaults to + /opt/shibboleth/etc/shibboleth/shibboleth.ini.
+- SHIREURL <url>
+
+ <Location <url>>
+ SetHandler <method>
+ </Location>- Specifies the URL and + the method the target uses to handle + requests for Shibboleth-protected resources. Currently, + shib-shire-post is the only available + handler method. + SHIREURL is used by Shibboleth when re-directing the user to + the WAYF and <Location> by Apache; for + this reason, both URL specifications must + match. Note that the configuration file itself contains <>'s, and + Location should not be replaced.
+The + referenced URL can be either a partial + path or an absolute URL. The partial path allows each virtual server + to use its own hostname and port in the SHIRE for session cookie + purposes, while the absolute URL forces HTTP virtual servers to use + HTTPS for the SHIRE. Use of a full https:// + URL is advised.
- ShibMapAttribute + <attribute-uri> <HTTP-header> [alias]
+- This command has been deprecated in favor of + the configuration support available in the Attribute Acceptance + Policy file. See section 4.e. It may be removed + in a future release.
+- -
The options in shibboleth.ini must be - configured as documented in 4.a. - Apache content will then need to be modified for - Shibboleth authentication. This is discussed in 4.d. It is recommended that the target then - be tested as detailed in section 5.a.
+- These modifications must be made to the Apache + startup script:
+Add the following environment variable:
+++SHIBCONFIG=/opt/shibboleth/etc/shibboleth/shibboleth.ini
+
+ export SHIBCONFIGIf the OpenSSL libraries are not in the system's search path, they + should be added to LD_LIBRARY_PATH. Generally + libtool's linker options will insure that the modules can locate the + Shibboleth libraries, but if not, you may need to add + /opt/shibboleth/lib to + LD_LIBRARY_PATH as well.
+If the SHIBCONFIG environment variable is not specified, Shibboleth + will use /opt/shibboleth/etc/shibboleth/shibboleth.ini + by default.
- The SHAR must be started along with Apache. Among other methods on + Unix, this can be done either by creating a separate SHAR startup script + or by modifying Apache's RC script to start/stop the + SHAR before httpd. It is + suggested that Apache's script be modified by adding:
+++/opt/shibboleth/bin/shar -f &
+Sample init.d scripts may be included with + future releases. Ensure that the environment variable referenced in + 3.c.2 are in place.
- By default, the Shibboleth modules are configured to log information + on behalf of Apache to the file + /opt/shibboleth/etc/shibboleth/shire.log, though this can be + changed. For this log to be created, Apache must have permission to + write to this file, which may require that the file be manually created + and permissions assigned to whatever user Apache is configured to run + under. If the file does not appear when Apache runs with the modules + loaded, check for permission problems.
+- The options in shibboleth.ini must be + configured as documented in 4.a. Apache content will + then need to be modified for Shibboleth authentication. This is + discussed in 4.d. It is recommended that the target + then be tested as detailed in section 5.a.
+
+-+
-- The package includes an ISAPI filter and bundled extension for SHIRE + POST processing in a single library, libexec\isapi_shib.dll. + This filter is configured using commands in + C:\opt\shibboleth\etc\shibboleth\shibboleth.ini. Make sure you've + added the library directory to the path as directed in + section 3.b.
-Installing the extension into IIS is a two step + process:
+
- First, add the filter using the Internet Services + Manager MMC console. Right click on the machine icon on the left, + and edit the WWW Service master properties. On the "ISAPI Filters" + tab, add a new filter called Shibboleth and specify the DLL named + above. The priority should be High, and once the filter is loaded, + make sure it appears in the list below the "sspifilt" entry. + Restart IIS and make sure the filter shows up with a green arrow. + Check the Windows event log if it fails to load. The default + configuration options are sparse, but they should allow the filter + to at least initialize.
+- Secondly, map a special file extension, such as + .shire, to the ISAPI library so that + virtual URLs can be specified to invoke the SHIRE handler for each + web site. Right click on the machine icon on the left, and edit the + WWW Service master properties. On the "Home Directory" tab, add a + script mapping using the "Configuration" button. The "Executable" + box should point to the filter/extension library, and the + "Extension" can be set to anything unlike to conflict, but + .shire is assumed (and the dot must be + included). You should select the option to limit verbs to POST, and + you must uncheck the "Check that file exists" box.
+
-- -Most of the configuration for the SHAR, SHIRE, and RM is stored - in the file shibboleth.ini. This - file is split into several pre-defined sections. The first - sections, general, shire, and shar, define the operational parameters - for the SHIRE and SHAR. The general section holds global tags, used - by all pieces. The shire and shar sections can override the general tags with SHIRE- or - SHAR-specific configuration. For example, if the SHAR is looking - for a tag, it will look first in the shar section; if it does not find the - tag there, it will proceed to look in the general section. The following - sections, metadata_shire, metadata_shar, attributes, and policies, define the trust framework - within the SHIRE and SHAR operate. Example configuration files - are bundled with the Shibboleth distribution.
- -There is also information that must be configured in - /usr/local/apache/conf/httpd.conf; for more - information, refer to 3.c.
- -Information in the logger files referenced by - shibboleth.ini may require additional configuration. - It is recommended that after initial installation is - completed, the log level in both files be changed to either - INFO or WARN.
- -Fields that are purple are optional; grey fields are - mandatory.
- -[general]:
- --
- -- - logger = <pathname> -
- -- -
- -Specifies the location of the log4cpp - configuration file for most Shibboleth events. This - element may also be optionally specified for each of - the components individually. Default logging settings (using local log files) - should suffice. If using a remote syslogd instead, the syslog - daemon must accept UDP:514 messages, and on Linux, - SYSLOGD_OPTIONS must include -r - to enable logging from remote machines. The - logging level is also defined in the logger configuration. - The configuration format and log levels are similar to that of the - Log4j package's - property format.
-- - schemadir = <pathname> -
- -- -
- -Specifies the directory in which the XML schema - files are located; defaults to - /opt/shibboleth/etc/shibboleth/.
-- - sharsocket = <pathname> -
- -- -
-Specifies the location of the socket the SHAR uses to - form connections. Note that if you change this, the SHAR and Apache - should both be restarted immediately, since new Apache child processes will - use the changed value as soon as they start up.
-The next segment of the [general] configuration - section defines server-specific tags in sections defined by - the server name for use by the SHIRE and RM. For example, if - you have a web server at www.example.edu, you can define a - section [www.example.edu] and override global tags - with tags for that server only.
- -The following table lists the server-specific tags. It is - broken into mandatory tags, and optional tags. Tags in the [general] section correspond to all - servers; to override specific tags on a per-server basis, use - [<FQDN>] as the header for a - section.
- - [<general>]: - -- -
- - [shire]: - -- - normalizeRequest = <true/false> -
- -- -
- -If true, all redirects generated by - mod_shire will be created using the virtual - server name assigned to the server containing this - command. If false, the browser's supplied - URL is used to compute the redirect back.
-- - checkIPAddress = <true/false> -
- -- -
- -If true, Shibboleth will check client - addresses for impersonation protection. In most - circumstances, this should be enabled to prevent - certain attacks concerning stolen cookies. Defaults - to false.
-- - supportContact = <e-mail> -
- -- -
- -Specifies the e-mail address used in the - generation of error pages.
-- - logoLocation = <pathname> -
- -- -
- -Specifies the location of the logo used in the - generation of error pages. This logo can be in any - format that the web browser will understand.
-- - wayfURL = <url> -
- -- -
- -Specifies the URL of the WAYF service the user is - redirected to. Federations will generally provide this URL - or provide information on how to locally host WAYF's with - a distributed hosts file.
-- - cookieName = <string> -
- -- -
- -Defines the name to be used for session cookies.
-- - shireSSLOnly = <true/false> -
- -- -
- -If true, the SHIRE will reject HTTP - connections that are not SSL-protected. This guards the initial session - sign-on from the browser, but does not preclude non-SSL content. Use of - SSL is strongly recommended; see section 2.c for more information.
-- - shireError = <pathname> -
- -- -
- -Specifies the location of the template for the - error page generated when there is an error - re-directing the user to the WAYF or processing a - SHIRE POST.
-- - rmError = <pathname> -
- -- -
- -Specifies the location of the template for the - error page generated if internal errors occur in the - RM.
-- - accessError = <pathname> -
- -- -
-Specifies the location of the template for the - page displayed to users when access to a protected - resource is denied by the RM.
--
- - [shar]: -- - logger = <pathname> -
- -- -
- -Specifies the location of the log4cpp - configuration file for most Shibboleth events. This - element may also be optionally specified for each of - the components individually. Default logging settings (using local log files) - should suffice. If using a remote syslogd instead, the syslog - daemon must accept UDP:514 messages, and on Linux, - SYSLOGD_OPTIONS must include -r - to enable logging from remote machines. The - logging level is also defined in the logger configuration. - The configuration format and log levels are similar to that of the - Log4j package's - property format.
-- - aap-uri = <uri> -
- -- -
- -Specifies the URI of an attribute acceptance policy XML - file. Attributes must be listed in the aap-uri file if they are to be - visible to the Apache server. Unlisted or rejected attributes are - filtered out and hidden from the web server (but also see the - ShibExportAssertion Apache command). - For more information, refer to section 4.e.
-- - metadata = <tag> -
- -- -
-Specifies the tag that defines the section of shibboleth.ini the SHIRE should - use to acquire its metadata. The SHIRE does not need trust - metadata, and so generally it will only need sites data to - enforce attribute policies like scope limitations(e.g. MIT - not asserting @brown.edu attributes.)
-- -
- -- - logger = <pathname> -
- -- -
- -Specifies the location of the log4cpp - configuration file for most Shibboleth events. This - element may also be optionally specified for each of - the components individually. Default logging settings (using local log files) - should suffice. If using a remote syslogd instead, the syslog - daemon must accept UDP:514 messages, and on Linux, - SYSLOGD_OPTIONS must include -r - to enable logging from remote machines. The - logging level is also defined in the logger configuration. - The configuration format and log levels are similar to that of the - Log4j package's - property format.
-- - metadata = <tag> -
- -- -
- -Specifies the tag that defines the section of shibboleth.ini the SHAR should - use to acquire its site and trust metadata.
-- - certFile = <pathname> -
- -- -
- -Specifies the location of the PEM-format certificate used by - the SHAR to communicate in authenticated fashion with - origin site Attribute Authorities.
-- - keyFile = <pathname> -
- -- -
- -Specifies the location of the PEM-format private key used by - the SHAR to communicate in authenticated fashion with - origin site Attribute Authorities.
-- - keyPass = <password> -
- -- -
- -Specifies the password used to access the - keyFile, if any.
-- - calist = <pathname> -
- -- -
- -Specifies a single file of PEM-format certificates containing - the root CAs the SHAR will consider to be valid signers of AA server - certificates. Currently applies globally to all communication with AAs.
-- - AATimeout = <seconds> -
- -- -
- -Specifies the number of seconds that the SHAR will wait - for attributes to be sent from an AA. Defaults to 60.
-- - AAConnectTimeout = <seconds> -
- -- -
- -Specifies the number of seconds that the SHAR will wait - for a connection to be established with an AA. - Defaults to 30.
-- - cacheType = <method> -
- -- -
- -Specifies the method used by the SHAR to cache received - attributes. The default is memory, which indicates that - the SHAR should store received attributes in its memory. - Another option is mysql, - which will use the MySQL Credential Cache. The steps to using this are described - in the MySQL Credential Cache guide.
-- - cacheClean = <seconds> -
- -- -
- -Specifies the duration in seconds between cleanups of - the SHAR's cached but expired attributes. Defaults to 300, or 5 minutes.
-- - cacheTimeout = <seconds> -
- -- -
-Specifies the duration in seconds that must elapse - between user accesses before that user's session is - destroyed, including the associated handle and all - cached attributes. Defaults to 28800 seconds, or 8 hours.
-[metadata] sections must be - created and named in accordance with the value of the metadata parameter in the [shire] and [shar] sections. Metadata sections may - be shared or defined for each component. Two providers are - supported by Shibboleth, but additional providers may be - specified with name/value pairs consisting of <metadata provider type>=<source>.
- -[<metadata>]:
- --
- -- - edu.internet2.middleware.shibboleth.metadata.XML = <pathname> -
- -- -
- -Specifies the location of the file to load site - metadata from. This will often be a sites.xml file stored locally, - and may be used by both the SHIRE and SHAR.
- -Shibboleth provides a simple utility called siterefresh for updating the - metadata file as described in section 4.g.
-- - edu.internet2.middleware.shibboleth.trust.XML = <pathname> -
- -- -
-Specifies the location of the trust database of - certificates and/or CA roots used by the SHAR during - session initiation. The SHIRE module generally does not need trust - data.
-In order for an attribute to be used by Shibboleth, it must be - recognized as valid by the SHAR and implemented with any specific - rules for how to understand and express its value based on the XML - from the AA. Additional string-valued attributes may be added to - the SHAR using the [attributes] - section.
- -[attributes]:
- --
- -- - <attribute_URI>=<type> -
- -- -
-Attribute names are URI's that are assigned by the - parties standardizing the attribute. Frequently, a - federation or standard object class may define these URI's. - The attribute type may be either scoped or simple, which defines how - the attribute is processed as described in section 4.e.
-The [policies] section contains the policy URI - values that control acceptance of assertions from origin - sites. This may eventually have multiple elements associated - it for targets that are members of multiple federations.
- -[policies]:
- --
- -- - <federation> = <URI> -
- -- -
-The name of the federation and its - associated policy URI. - These URI's will be provided by federations.
- -This set of URI values is matched against the SAML - Audience fields of - assertions received from HS's and AA's. One of the - URI's specified by the origin in edu.internet2.middleware.shibboleth.audiences - must match one of these URIs or the - assertion will not be accepted by design.
-Additional sections for individual servers may be defined with - either parameters overriding those found in [general], or the following additional - parameters:
- -[<FQDN>]:
- --
- -- - requestAttributes = <attr1> <attr2> - <attr3>... -
- -- -
-Specifies a space-delimited list of attributes named by - URI that the SHAR will request of an AA. If the parameter - does not exist or is null, then the SHAR will receive all - attributes the AA is willing to release to it.
-
++1=hostname.domain.com
+
+ 2=hostname2.domain.com
+ (etc...)
At least an empty configuration section named + hostname.domain.com should then be added to the end of the file. + Any options specific to that web site can be added as documented in + later sections.
++The SHAR is a console application that is primarily designed to be + installed as a Windows service. To run the process in console mode for + testing, the -console parameter is used. + Otherwise, parameters are used to install (or remove) the SHAR from the + service database and subsequent control is via the Service Control Manager + applet. The following command line parameters can be used:
++
+- -console
+- Allows the process to be started from a command + prompt. Since the console will exit if the desktop user logs out, this + is not suitable for production use, but may be useful for testing.
+- -config <pathname>
+- Specifies the pathname of the SHAR's configuration + file. Defaults to \opt\shibboleth\etc\shibboleth\shibboleth.ini + or the value of the SHIBCONFIG environment + variable, if it is set.
+- -install <servicename>
+- Installs the SHAR as a named service in the Windows + service database. A name should be provided if multiple instances of the + SHAR need to be run on different ports, and thus installed separately. + The -config option can be provided to include + a specific configuration file on the service's command line.
+- -remove <servicename>
+- Removes the named service instance of the SHAR from + the Windows service database.
++
+
++Most of the configuration for the SHAR, SHIRE, and RM is stored in the + file shibboleth.ini. This file is split into + several pre-defined sections. The first sections, + [general], [shire], and + [shar], define the operational parameters for the + SHIRE and SHAR. While + not precisely accurate, the [shire] section is + generally associated with the web server modules and libraries that + applications interface with, while the [shar] + section is associated with the separate SHAR process. The + [general] section holds global settings, used by + all components. The [shire] and + [shar] sections can override the + [general] tags with SHIRE- or SHAR-specific + configuration. For example, if the SHAR is looking for a tag, it will look + first in the shar section; if it does not find + the tag there, it will proceed to look in the general + section.
+The following sections, [metadata_shire], + [metadata_shar], and + [policies], define the trust framework within which the entire system + operates. Example configuration files are bundled with the Shibboleth + distribution, currently derived from the InQueue staging federation managed + by Internet2
+For Apache (but not IIS), there is also information that must be + configured in /usr/local/apache/conf/httpd.conf + (or equivalent); for more information, refer to 3.c.
+Information in the logging configuration files referenced by + shibboleth.ini may require additional changes to + meet local needs. The logging level can be raised to + INFO or DEBUG if additional detail is + needed for testing. It is recommended that after initial installation is + completed, the log level in both files be left at either + INFO or WARN.
+Fields that are purple are optional; grey fields are mandatory. If the + option only applies to a specific environment, such as IIS/ISAPI only, then + this is indicated.
+[general]:
++
+- logger = <pathname>
+- Specifies the location of the + log4cpp configuration file for most Shibboleth events. This + element may also be optionally specified for each of the components + individually (which is the default provided, so this setting is often + unused). Default logging settings (using local log files) should + suffice. If using a remote syslogd instead, the + syslog daemon must accept UDP:514 + messages, and on Linux, SYSLOGD_OPTIONS must + include -r to enable logging from remote + machines. The logging level is also defined in the logger configuration + file. The configuration format and log levels are similar to that of the + Log4j + package's property format.
+- schemadir = <pathname>
+- Specifies the directory in which the XML schema files + are located; defaults to + /opt/shibboleth/etc/shibboleth/. This should generally be left + alone, unless a non-default installation path is used.
+- sharsocket = <pathname> | [IP + interface:]port
+- Specifies the location of the socket the SHAR uses to + form connections. Note that if you change this, the SHAR and Apache + should both be restarted immediately, since new Apache child processes + will use the changed value as soon as they start up. +
+On Unix, this is usually set to a domain socket path, often something + in /tmp. On Windows, this must be either a + TCP port number, or a combination of an IP address and port, with a + colon in between. Using an address specifies an IP interface to bind to + on multi-homed servers. Using just a port number generally suffices. If + this syntax is used on Unix, then the process will use a TCP socket + instead of a domain socket.
+Security Note: Using TCP, which is mandatory on Windows, can + be insecure if used in certain non-default configurations. If you allow + access to the service from other hosts, be sure a firewall is in place + to prevent unauthorized access. The sharacl + setting, described later, provides some minimal filtering, but TCP is + still an insecure protocol.
The rest of the [general] configuration + section defines global settings that can be overridden by server-specific + tags in sections defined by the server name. This is especially applicable + for non-Apache configurations. For example, if you have a web server named + www.example.edu, you can define a section [www.example.edu] + and override global tags with tags for that server only.
+The following table lists the server-specific tags. It is broken into + mandatory tags, and optional tags. Tags in the [general] + section correspond to all servers; to override specific tags on a per-server + basis, use [<FQDN>] as the header for a section (FQDN + means fully-qualified domain name, and corresponds to the name you assign to + a virtual host using the Apache ServerName directive, or that you map IIS + instance IDs to using the [isapi] section.
+[<general>]:
++
+- wayfURL = <absolute url>
+- Specifies the URL of the WAYF service the user is + redirected to. Federations will often provide this URL in order to + control the way in which sites are presented to users, but a target may + provide this function, or it may be set directly to a specific site's + Handle Service, effectively rendering the system internal to a single + origin site.
+- shireURL = <absolute or + relative url> ISAPI
+- Specifies the URL of the SHIRE POST URL, or assertion + consumer service, at which new sessions are initiated. This can be an + absolute URL, or a relative path to be prefixed by the base URL of the + web site. Using an absolute URL allows a virtual server to funnel SHIRE + requests to a fixed location, such as in the case where a non-SSL site + wants to handle SHIRE requests over SSL (on a different port). +
+Note that this URL will result in a cookie being set, and this cookie + must be returned in subsequent requests, so the virtual server's domain + name and port must be consistent with the SHIRE's domain name and port + for some browsers to properly return the cookie. If default ports are + used (and thus left unspecified), browsers will generally return cookies + set via SSL to a non-SSL server. If non-default ports are used, it is + recommended that this be a relative URL so that each virtual host + handles its own cookie operations.
+For Shibboleth to function in IIS, the file extension at the end of + this URL must match the value configured into IIS and mapped to the + ISAPI extension. This causes the request to be serviced properly, even + though no file by that name actually exists.
- cookieName = <string>
+- Defines the name to be assigned to in-memory session + cookies.
+- shireError = <pathname>
+- Specifies the location of the template for the error + page generated when there is an error re-directing the user to the WAYF + or processing a new session sign-on.
+- rmError = <pathname>
+- Specifies the location of the template for the error + page generated if internal errors occur in the RM.
+- accessError = <pathname>
+- Specifies the location of the template for the page + displayed to users when access to a protected resource is denied by the + RM. This is distinct from when errors occur during the evaluation + process itself, and indicates a denial of authorization.
+- normalizeRequest = <true|false>
+- If true, all redirects and computed request URLs + generated by Shibboleth will be created using the virtual server name + assigned to the server. If false, the + browser's supplied URL is sometimes used to compute the information. + This sometimes has no effect, depending on the capabilities of the web + server, since the correct behavior is almost always to rely on the + server's API to report the hostname and ignore the browser.
+- checkIPAddress = <true|false>
+- If true, Shibboleth will + check client addresses for impersonation protection. In most + circumstances, this should be enabled to prevent certain attacks + concerning stolen cookies, but this can cause problems for users behind + proxies or NAT devices. Defaults to false.
+- shireSSLOnly = <true/false>
+- If true, the SHIRE will + reject HTTP connections for new session sign-on that are not SSL-protected. + This guards the initial session sign-on from the browser, but does not + preclude non-SSL content. Use of SSL is strongly recommended; see + section 2.c for more information.
+- mustContain = + <string1>;<string2> ISAPI
+- Controls what content in IIS to protect with + Shibboleth. Multiple values should be separated with a semicolon. Each + string is matched directly against the requested URL, and if the URL + contains the string, a match is made and Shibboleth applies. No regular + expressions are supported, only literal matches. Slashes are matched + like other characters, so path components can be surrounded with slashes + to match any requests with a particular component in the path. Defaults + to protecting everything on a server or site.
+- contentSSLOnly = <true|false> + ISAPI
+- If true, Shibboleth will + insist that any request for protected content is over an SSL connection. + Defaults to false.
+- authLifetime = <seconds> + ISAPI
+- If set, sessions are always terminated after the + specified number of seconds, resulting in a new redirect and request for + authentication, just as if a new request without a session is received. + Defaults to infinite.
+- authTimeout = <seconds> + ISAPI
+- If set, sessions are always terminated after the + specified number of seconds of inactivity (defined as no requests + received in that session), resulting in a new redirect and request for + authentication, just as if a new request without a session is received. + Defaults to infinite.
+- requestAttributes = <attr1> + <attr2> <attr3>...
+- Specifies a space-delimited list of attributes + (named by a designated URI) that the SHAR will request when querying for + attributes. By default, the SHAR will ask for and receive all attributes + the AA is willing to release to it.
+- exportAssertion = <true|false> + ISAPI
+- If set, the SAML attribute assertion received by + the SHAR is exported to a CGI request header called Shib-Attributes, + encoded in base64. Defaults to false. While + this does require parsing the raw XML, it also permits an application to + see attributes that may have been filtered by an AAP, or to forward the + SAML assertion to a third party.
+- supportContact = <e-mail>
+- Specifies the local site's support e-mail address, + and is used in the generation of error pages.
+- logoLocation = <pathname>
+- Specifies the location of the logo used in the + generation of error pages. This logo can be in any format that the web + browser will understand, and should be a URL (absolute or relative) that + will return a valid logo.
+[shire]:
++
+- metadata = <section tag>
+- Specifies the tag that defines the section of + shibboleth.ini the SHIRE should use to + acquire its metadata. The SHIRE does not need trust metadata, and so + generally it will only need site metadata and attribute acceptance + policy to define attributes and enforce policies like scope + limitations(e.g. MIT not asserting attributes @brown.edu.)
+- logger = <pathname>
+- Specifies the location of the + log4cpp configuration file for Shibboleth events produced by the + web server modules and libraries. Refer to the global setting for more + information.
+- aap-uri = <uri> + DEPRECATED
+- Specifies the URI of an attribute acceptance policy + XML file. This command has been replaced with a new metadata provider + type for attribute policy that should be provided to both the SHIRE and + SHAR components. To replace this command, add lines to both metadata + sections of this form: +
+++edu.internet2.middleware.shibboleth.target.AAP.XML=<uri>
+For more information, refer to section 4.e. This + command will be removed in future releases.
[shar]:
++
+- metadata = <tag>
+- Specifies the tag that defines the section of + shibboleth.ini the SHAR should use to acquire + its site, trust, and attribute metadata.
+- cacheType = <method>
+- Specifies the method used by the SHAR to cache + sessions and attributes. The default is memory, + which indicates that the SHAR should store received attributes in + memory. Another option is mysql, which will + use the MySQL Credential Cache, if it is available.
+- cacheClean = <seconds>
+- Specifies the duration in seconds between cleanups of + the SHAR's cached but expired sessions and attributes. Defaults to + 300, or 5 minutes.
+- cacheTimeout = <seconds>
+- Specifies the duration in seconds + that must elapse between user accesses before that user's session is + destroyed, including the associated handle and all cached attributes. + Defaults to 28800 seconds, or 8 hours. This + should be longer than the associated server's settings for session + lifetime and timeout.
+- logger = <pathname>
+- Specifies the location of the + log4cpp configuration file for Shibboleth events produced by the + SHAR service. Refer to the global setting for more information.
+- sharacl = <IP Address>
+- Specifies one or more space-delimited IP addresses + from which a TCP-based SHAR service will accept connections. Defaults to + 127.0.0.1 (localhost). Should only be changed if proper precautions have + been taken to protect connections from off-host.
+- certFile = <pathname> +
+- Specifies the location of the PEM-format + certificate used by the SHAR to communicate in authenticated fashion + with origin site Attribute Authorities.
+- keyFile = <pathname> +
+- Specifies the location of the PEM-format private + key used by the SHAR to communicate in authenticated fashion with origin + site Attribute Authorities.
+- keyPass = <password> +
+- Specifies the password + used to access the keyFile, if any.
+- calist = <pathname> +
+- Specifies a single file of PEM-format certificates + containing the root CAs the SHAR will consider to be valid signers of AA + server certificates. Currently applies globally to all communication + with AAs.
+- AATimeout = <seconds> +
+- Specifies the number of seconds that the SHAR will + wait for attributes to be sent from an AA. Defaults to + 60.
+- AAConnectTimeout = + <seconds>
+- Specifies the number of seconds that the SHAR will + wait for a connection to be established with an AA. Defaults to + 30.
+[metadata] sections must be created and named + in accordance with the value of the metadata + parameter in the [shire] and + [shar] sections. Metadata sections may be shared or defined for each + component. Three XML-based providers are supported by Shibboleth, but future + providers may be specified with name/value pairs consisting of + <metadata provider type>=<source>.
+Note that any number of files of the three types may be loaded into the + system, which supports aggregating policy from across federations.
+Shibboleth provides a simple utility called + siterefresh for updating metadata files from a central location and + verifying a digital signature over them, as described in section + 4.g.
+[<metadata>]:
++
+- + edu.internet2.middleware.shibboleth.metadata.XML = <pathname>
+- Specifies the location of the file to load site + metadata from. This information controls what origin sites are trusted + by the target and provides contact information. This should be a file + stored locally, and may be used by both the SHIRE and SHAR.
+- + edu.internet2.middleware.shibboleth.trust.XML = <pathname>
+- Specifies the location of the trust database of + certificates and/or CA roots used by the SHAR during session initiation + (but currently is not used during attribute exchange). The SHIRE + component generally does not need trust data.
+- + edu.internet2.middleware.shibboleth.target.AAP.XML = <pathname>
+- Specifies the location of the Attribute Acceptance + Policy file that defines what attributes will be visible to + applications, how to filter their values based on the source, and how to + make them available to applications and the RM. See + section 4.e. for detailed information on this file.
+This + provider has been added as of version 1.0.1, and supersedes the old + aap-uri and attributes + settings, as well as the Apache ShibMapAttribute + command.
The [policies] section contains the policy URI + values that control acceptance of assertions from origin sites. This may + eventually have multiple elements associated it for targets that are members + of multiple federations.
+[policies]:
++
+- <federation> = <URI> +
+- The name of the federation + and its associated policy URI. This + information should be provided by federations and is designed to support + future work in federation deployment. For the time being, it simply + insures that deployments not meant to interoperate will not do so.
++ This set of URI values is matched against the SAML + Audience fields of assertions received from HS's and AA's. One of + the URI's specified by the origin in the + edu.internet2.middleware.shibboleth.audiences property must match + one of these URIs or the assertion will not be accepted by design.
++Shibboleth supports the dynamic generation of information in error pages + referenced by shibboleth.ini. The Shib Target + employs a special Markup Language Processor to insert special tags into the + generated HTML. The parser will read the error file looking for any tag that + looks like:
-- -Shibboleth supports the dynamic generation of information - in error pages referenced by shibboleth.ini. The - Shib Target employs a special Markup Language Processor to - insert special tags into the generated HTML. The parser will - read the error file looking for any tag that looks like:
- -- <shibmlp tag-name /> -- -Shibboleth will replace tag-name with the - appropriate markup tag from the table below:
- --
- -- supportContact
- -- The value of the supportContact for this - server.
- -- logoLocation
- -- The value of the logoLocation for this server. This - is used to fill in the template error page only; if a custom - error page is created, then the image may be linked to - statically by the page itself.
- -- requestURL
- -- The user's requested URL.
- -- errorType
- -- The type of error.
- -- errorText
- -- The actual error message.
- -- errorDesc
- -- A textual description of the error intended for human - consumption.
- -- originContactName
- -- The contact name for the origin site provided by that - site's metadata.
- -- originContactEmail
- -- The contact email address for the origin site provided by that - site's metadata.
- -- originErrorURL
- -- The URL of an error handling page for the origin site - provided by that site's metadata.
-This configuration is only for Apache servers, and is only - used by resources protected by Shibboleth. See section 4.d.
- -Sample error templates for different kinds of errors are - included in the Shibboleth distribution, and can be triggered - by anything that will cause Shibboleth to be unable to make an - authorization decision, including a bad sites file, certificate chain, - or skewed clock.
- -You should edit these templates, provide or remove style sheets and - images, and otherwise customize these templates to suit the user experience - you want your users to have when errors occur.
- +<shibmlp tag-name />
4.c. Key Generation and Certificate - Installation
- +Shibboleth will replace tag-name with the + appropriate markup tag from the table below:
++
+- supportContact
+- The value of the supportContact + for this web site.
+- logoLocation
+- The value of the logoLocation + for this web site. This is used to fill in the template error page only; + if a custom error page is created, then the image may be linked to + statically by the page itself.
+- requestURL
+- The user's requested URL.
+- errorType
+- The type of error.
+- errorText
+- The actual error message.
+- errorDesc
+- A textual description of the error intended for human + consumption.
+- originContactName
+- The contact name for the origin site provided by that + site's metadata.
+- originContactEmail
+- The contact email address for the origin site provided + by that site's metadata.
+- originErrorURL
+- The URL of an error handling page for the origin site + provided by that site's metadata.
+This configuration is only for Apache servers, and is only used by + resources protected by Shibboleth. See section 4.d.
+Sample error templates for different kinds of errors are included in the + Shibboleth distribution, and can be triggered by anything that will cause + Shibboleth to be unable to make an authorization decision, including a bad + sites file, certificate verification failures, or a skewed clock between + sites.
+You should edit these templates, provide or remove style sheets and + images, and otherwise customize these templates to suit the user experience + you want your users to have when errors occur. The defaults are not likely + to meet the needs of any site.
+
++The only target component that must have a private key and certificate is + the SHAR. While the target server itself should support SSL in most cases + for users, it is mandatory for the SHAR to authenticate when contacting an + AA, and it must therefore be given a key and an SSL client certificate. It + is permissible for the SHAR to use the same keypair and certificate used by + the target server itself, provided the certificate is signed by a CA + accepted by the community of sites.
+The certificate and key file location should be based on whether they + will also be used for Apache. If they will be used as a server certificate + as well, they should probably be in the Apache tree in the usual + mod_ssl-defined locations inside the Apache + configuration folder., and the SHAR can read them from there. If the SHAR is + not running as root, permissions might need to be + changed to allow this access. If the certificate and key will only be used + for the SHAR, they can be put in the same folder with the + shibboleth.ini file and protected appropriately.
+Other web servers like IIS do not use the raw PEM format that Apache and + Shibboleth can share, and therefore the components must generally use + separate copies of the key and certificate if they are to be shared. Most + other servers can export and/or import keys to and from PEM format or other + formats that OpenSSL can convert.
+The SHAR is assigned a key and a certificate using shibboleth.ini's + certFile, keyFile and + keyPass settings, described in + section 4.a. These files must currently be in PEM format. OpenSSL + commands to generate a new keypair and a certificate request are shown here, + assuming 2048 bit RSA keys are to be used:
-- -The only target component that must have a private key and - certificate is the SHAR. While the target server itself should support - SSL in most cases, it is mandatory for the SHAR to - authenticate when contacting an AA, and it must therefore be - given a key and an SSL client certificate. It is permissible - for the SHAR to use the same keypair and certificate used by - the target server itself, provided the certificate is signed - by a CA accepted by the community of sites.
- -The certificate and key should be placed based on whether - they will also be used for Apache's server cert. If they will - be used as a server certificate as well, they should probably - be in the Apache tree in the usual mod_ssl spot, and - the SHAR can read them from there. If the SHAR is not running - as root, permissions might need to be changed to - allow this access. If the certificate and key will only be - used for the SHAR, they can be put in the same folder with the - shibboleth.ini file.
- -The SHAR is assigned a key and a certificate using - shibboleth.ini's certFile, - keyFile and - keyPass, described in 4.a. These - files must currently be in PEM format. OpenSSL commands to - generate a new keypair and a certificate request are shown - here, assuming RSA keys are to be used:
- -- $ openssl genrsa -des3 -out ssl.key 2048- -
- $ openssl req -new -key ssl.key -out ssl.csr -The signed certificate file returned by the CA should be - usable directly, or can be converted to PEM format using the - openssl x509 command.
- -The key and certificate files can be placed anywhere, - though in or beneath the /usr/local/apache/conf - directory is a good choice. The Apache child processes, - often running as nobody, must be able to read them - while the server is running, which may require permission - changes.
- -This particularly applies when sharing the key and - certificate used by mod_ssl, which are only readable by root - by default. The password, if any, must be placed in the conf - file, since the module cannot prompt for it as the initial - startup of mod_ssl can. The issues surrounding how to - securely obtain a key while running as nobody - may be addressed in a later release. Since the password will be - stored in clear text in a frequently examined file, it is - suggested to use a password not used elsewhere.
- -Finally, the calist command provides the SHAR - with a set of CA roots to trust when validating AA server - certificates. In all cases, the SHAR verifies that the - certificate's Subject CN equals the AA's hostname, but the CA root - bundle restricts the accepted signers to those permitted by - the SHAR. The parameter can be omitted to skip such validation.
+$ openssl genrsa -des3 -out ssl.key 2048
+ $ openssl req -new -key ssl.key -out ssl.csr4.d. Protecting Webpages
- --+Protection of webpages is primarily achieved through - "mapping" attributes provided by an AA to a localized - vocabulary for authorization rules. Each attribute can be - mapped using the ShibMapAttribute command to an HTTP - header name where it can subsequently be accessed by - applications, and optionally to an alias that can be - used in a Require command to search for a matching - value. This mapping command must be in httpd.conf, - while the rest of the commands described here appear in - content-specific configuration or .htaccess - files.
- -Any of the typical ways of protecting content may be used - (.htaccess, Directory, Location, Files, etc.). There are two - ways to trigger Shibboleth authentication: specifying an - AuthType of shibboleth to use Shibboleth - directly, or specifying ShibBasicHijack On to - process existing .htaccess files using Shibboleth instead. - Support for authorization consists of mod_auth-style require - directives, as well as support for mod_auth group files.
- -A complete list of the directives and their values is - below:
- --
- - AuthType <string> -
- -- -
- -Use shibboleth for direct invocation, or - Basic plus the ShibBasicHijack On - option described below.
-- - ShibSSLOnly<on/off> -
- -- -
- -Controls whether Shibboleth will reject non-SSL - requests from clients. Defaults to off.
-- - ShibBasicHijack <on/off> -
- -- -
- -Controls whether Shibboleth should or should not - ignore requests for AuthType Basic. Defaults - to off.
-- - ShibExportAssertion <on/off> -
- -- -
- -Controls whether the SAML attribute assertion - provided by the AA is exported in a base64-encoded - HTTP header, Shib-Attributes. Defaults to - off. While this does require parsing the - raw XML, it also permits an application to see attributes that may have - been filtered by an AAP, or to forward the SAML assertion to a third party.
-- - ShibAuthLifetime <seconds> -
- -- -
- -Sets the maximum lifetime in seconds that a user - session can survive. Omission or zero results in - arbitrary session lifetime.
-- - ShibAuthTimeout <seconds> -
- -- -
- -Sets the maximum number of seconds without any - user activity that a session will remain alive. After - seconds seconds without activity, the - session is considered dead. Omission or 0 - results in an arbitrary session timeout.
-- - AuthGroupFile <pathname> -
- -- -
Same as mod_auth; collects EPPN's into a named - group for access control. Note that mod_auth will not - support group files when mod_shibrm is loaded, since - they share the same command.
- - +The signed certificate file returned by the CA should be usable directly, + or can be converted to PEM format using the openssl x509 + command.
+If the key is to be shared with Apache, the web server's child processes, + often running as nobody, must be able to read + them while the server is running, which may require permission changes.
+This particularly applies when sharing the key and certificate used by + mod_ssl, which are only readable by root by default. The password, if any, + must be placed in the shibboleth.ini file, since + the Apache module cannot prompt for it during initial startup as mod_ssl + can. The issues surrounding how to securely obtain a key while running as + nobody may be addressed in a later release. Since + the password will be stored in clear text in a frequently examined file, it + is suggested to use a password not used elsewhere.
+Finally, the calist command provides the SHAR + with a set of CA roots to trust when validating AA server certificates. In + all cases, the SHAR verifies that the certificate's Subject CN equals the + AA's hostname, but the CA list restricts the accepted signers to those + permitted by the SHAR. The parameter can be omitted to skip such validation, + but this is not secure.
+4.d. Protecting Web Pages
++- -Protection of web pages is primarily achieved through "mapping" + attributes provided by an AA to a localized vocabulary for authorization + rules. This was formerly accomplished in Apache with the + ShibMapAttribute command, but this has been replaced with additional + features in the AAP syntax, described in section 4.e. + This applies to both Apache and IIS.
+IIS
+The IIS RM module supports the mapping of attributes via AAP files, but + it does not support rule-based policies and therefore cannot protect static + content at this time. In addition, all of the configuration settings are + managed globally or per-site and are pulled from the + shibboleth.ini file, so there are no additional commands to document + at this time.
+
+Apache
+The Apache RM module provided can interpret AAP settings to map + attributes to HTTP request headers and to Require + rules, permitting protecting of both static and dynamic content. The + commands described here can appear in content-specific configuration blocks + or .htaccess files. They determine what content + is to be protected, session policies, and static access control rules.
+Any of the typical ways of protecting content may be used (.htaccess, + Directory, Location, Files, etc.). There are two ways to trigger Shibboleth + authentication: specifying an AuthType of + shibboleth to use Shibboleth directly, or using + ShibBasicHijack to process existing .htaccess + files using Shibboleth instead. Support for authorization consists of + mod_auth-style require directives, as well as support for mod_auth group + files.
+A complete list of the directives and their values is below:
++
-- AuthType <string>
+- Use shibboleth for direct + invocation, or Basic plus the + ShibBasicHijack option described below.
+- ShibSSLOnly <on/off>
+- Controls whether Shibboleth will reject non-SSL + requests for resources from clients. Defaults to off.
+- ShibBasicHijack <on/off>
+- Controls whether Shibboleth should or should not + ignore requests with AuthType Basic. Defaults + to off.
+- ShibExportAssertion <on/off>
+- Controls whether the SAML attribute assertion provided + by the AA is exported in a base64-encoded HTTP header, + Shib-Attributes. Defaults to + off. While this does require parsing the raw + XML, it also permits an application to see attributes that may have been + filtered by an AAP, or to forward the SAML assertion to a third party.
+- ShibAuthLifetime <seconds>
+- If set, sessions are always terminated after the + specified number of seconds, resulting in a new redirect and request for + authentication, just as if a new request without a session is received. + Defaults to infinite.
+- ShibAuthTimeout <seconds>
+- If set, sessions are always terminated after the + specified number of seconds of inactivity (defined as no requests + received in that session), resulting in a new redirect and request for + authentication, just as if a new request without a session is received. + Defaults to infinite.
+- AuthGroupFile <pathname>
+- Same as mod_auth; collects values found in REMOTE_USER + into a named group for access control. An attribute must be mapped to + REMOTE_USER for this to work. Note that mod_auth will not support group + files when mod_shibrm is loaded, since they share the same command. +
+This is + implemented by placing a .htaccess file + that references a group file stored at /pathname:
+++AuthGroupFile /pathname
+
+ require group workgroupAn + + AuthGroupFile used by Shibboleth might resemble:
+ workgroup: joe@example.edu, jane@demo.edu, jim@sample.edu +- Require <string>
+- Enforce authorization using one of the following + methods.
- -+
- valid-user
+++Any Shibboleth user from a trusted origin site is accepted, + even if no actual attributes are received. This is a very + minimal kind of policy, but is useful for testing or for + deferring real policy to an application.
+user
--This - is implemented by placing a .htaccess - file that references an AuthGroupFile stored - at /path:
- -- authgroupfile /path- -
- require group workgroup -Note that an - AuthGroupFile used by Shibboleth would resemble - workgroup: joe@example.edu, jane@demo.edu, - jim@sample.edu.
+A space-delimited list of values, such as from the + + urn:mace:dir:attribute-def:eduPersonPrincipalName + attribute. Actually, any attribute can be mapped to REMOTE_USER, + even if this doesn't always make sense.
- - Require <string> -
- -- -
-Enforce authorization using one of the following methods.
- -- -
- -- - valid-user - -
- - user - ---Any Shibboleth user from a trusted origin site is accepted, - even if no actual attributes are received. This is a very minimal - kind of policy, but is useful for testing or for deferring real - policy to an application.
--- - -A space-delimited list of EPPN values, provided that the - urn:mace:dir:attribute-def:eduPersonPrincipalName - attribute has been mapped to the - REMOTE_USER header (as per the earlier - example configuration commands). Actually, any attribute can be mapped to - REMOTE_USER, even if this doesn't always make sense.
-- - group - -
- ---A space-delimited list of group names defined - within AuthGroupFile files, again - provided that a mapping to REMOTE_USER - exists.
-- - <alias> - -
---An arbitrary rule tag that matches an alias - defined in a ShibMapAttribute server - command. The rule value is a space-delimited - list of attribute values, whose format depends on - the attribute in question (e.g. an affiliation - rule might look like require affiliation - staff@osu.edu faculty@mit.edu).
-Additionally, for user and - <alias>-based rules, if a tilde character - is placed immediately following user or - <alias>, the expressions that follow are - treated as regular expressions.
- -For example, the regular expression AAP require affiliation ~ - ^member@.+\.edu$ would evaluate to allowing - anyone with an eduPersonScopedAffiliation of - member from a .edu - domain.
- -
-4.e. Designing AAP's
- + +group +++A space-delimited list of group names defined within + AuthGroupFile files, again provided + that a mapping to REMOTE_USER exists.
+<alias> + +++An arbitrary rule name that matches an Alias defined in an + AAP file. The rule value is a space-delimited list of attribute + values, whose format depends on the attribute in question (e.g. + an affiliation rule might look like:
+require affiliation staff@osu.edu + faculty@mit.edu
+Additionally, for user and + <alias>-based rules, if a tilde character is + placed immediately following user or + <alias>, the expressions that follow are + treated as regular expressions. The syntax supported is generally based + on the one defined by + XML Schema. This specification borders on unreadable, but the syntax + is generally Perl-like. Expressions should generally be "anchored" with + the ^ and $ symbols to insure mid-string matches don't cause false + positives.
+For example, the rule:
+ require affiliation ~ ^member@.+\.edu$
+ would evaluate to allowing anyone with an + affiliation of member from a .edu + domain. + +
++Shibboleth allows a user and a site to release a varying set of + attributes to a destination site, and does not impose restrictions on the + kinds of attribute information provided by an AA. Target implementations + must be prepared to examine the attributes they receive and filter them + based on policies about what information to permit an origin site to assert + about its users.
+Attribute acceptance is the process of defining acceptable attributes and + filtering attribute values before passing them on to a resource manager, + such as the mod_shibrm module. Data blocked by + AAP filters will not be passed to the CGI environment or used when enforcing + .htaccess rules. Note that the attribute + assertion exported to the Shib-Attributes header + is unfiltered.
+The Shibboleth implementation supports Scoped and Simple attributes and + filtering policies for different kinds of attributes, and is potentially + extensible to more complex attributes in the future. An attribute is + considered Scoped if the XML representation of its values contains a "Scope" + attribute. As of 1.0.1, this is detected at runtime and requires no + configuration work.
+An essential part of the Shibboleth trust fabric is ensuring that + sites only assert attributes for domains for which they are considered + authoritative by the target. Typically, this means that Brown University + will be trusted to assert attributes only scoped to + brown.edu. Unless there are very specific circumstances requiring + this restriction be removed, it is strongly encouraged that such policies be + in place.
+Scoped:
-- -Shibboleth allows a user and a site to release a varying - set of attributes to a destination site, and does not impose - restrictions on the kinds of attribute information provided - by an AA. Target implementations must also be prepared to - examine the attributes they receive and filter them based on - policies about what information to permit an origin site to - assert about its users.
- -Attribute acceptance is the process of filtering attribute - values before passing them on to a resource manager, such as - the mod_shibrm module. Data blocked by AAP filters - will not be passed to the CGI environment or used when - enforcing .htaccess rules. - Note that the attribute assertion exported to the - Shib-Attributes header is unfiltered.
- -The Shibboleth distribution supports scoped and - simple filtering policies for different kinds of - attributes.
- -An essential part of the Shibboleth trust fabric is ensuring - that sites only assert attributes for domains for which they are - considered authoritative by the target. Typically, this means - that Brown University will be trusted to assert attributes only - scoped to brown.edu. Unless - there are very specific circumstances requiring this restriction - be removed, it is strongly encouraged that such policies be in place.
- -Scoped:
--- -Scoped attributes are a special kind of attribute whose - values are a combination of a value and a - scope, or context for the value. An - example is eduPersonScopedAffiliation, which adds a - scope to the defined set of eduPersonAffiliation - values, such as student, member, or - faculty. Scopes are expressed as DNS domains and - subdomains.
- -Any scoped attribute can be - scoped only to the origin site's permitted domains. These - domains are listed in the sites file that provides trust - information to the system. Domains can be explicit or - regular expressions, and can be changed by a target to meet - its needs if a local version of the file is created. Thus, - attribute acceptance processing for scoped - attributes is based on the sites file, in addition to the mechanism described - below for simple attributes.
-Simple:
--- -Simple attributes are attributes whose value is expressed - in XML as a Text node; that is, the value is just a string. - Multiple values are permitted. - eduPersonEntitlement, in which the values are URIs, - is one example of a simple attribute.
-In this release, simple (and scoped) attribute acceptance is - controlled with an external policy file written in XML. The - schema for the file is described by the - shibboleth.xsd schema, and an example file is - included, AAP.xml. If the aap-uri - parameter in the shibboleth.ini file is left out, - then no policy is applied, and no filtering is done. - Otherwise, the rules encoded in the file are used.
-The policy is a default-deny algorithm that requires - permissible attributes and values be listed explicitly. That - is, an empty file permits nothing. Each attribute to be - permitted must be listed in the file by name in an - <AttributeRule>. Each such rule is a - collection of <SiteRule> elements along with - an optional <AnySite> default rule. In turn - each site rule is a set of <Value> rules that - specify matches to permit, either literal or regular - expressions.
-A syntax summary follows:
-- -- -<AttributeAcceptancePolicy
-The top level element in the - file.- -<AttributeRule Name="attribute - URI">
-Specifies a rule for an attribute, named with - its URI.- -<AnySite>
-Specifies a rule that always applies to the - attribute, regardless of the asserting AA.- -<SiteRule - Name="site.domain.name">
-A rule that applies to the origin site AA - corresponding to the domain name.- -<AnyValue>
-Specifies a rule that always applies to the - attribute and site, regardless of the value(s).- -<Value Type="type">
-Specifies a value to permit, either directly - using type literal, or using a set of - matching expressions as type regexp. - literal is the default if Type is not - specified.- -The regular expression syntax is a subset of the usual - Perl and Unix syntaxes that is described in the XML Schema - specification by the W3C. Most typical expressions should - work. Be sure to anchor them using ^ and $ - to avoid unintentional matches midstring.
- -Note that the AAP rules described in this section are not - part of the Shibboleth architecture and are simply one - possible set of approaches provided by this implementation.
+Scoped attributes are a special kind of attribute whose values are a + combination of a value and a + scope, or context + for the value. An example is + eduPersonScopedAffiliation, which adds a scope to the defined set + of eduPersonAffiliation values, such as + student, member, + or faculty. Scopes are expressed as DNS + domains and subdomains.
+Any scoped attribute can be scoped only to + the origin site's permitted domains. These domains are listed in the + site metadata that provides policy information to the system. Domains + can be explicit or regular expressions, and can be changed by a target + to meet its needs. Thus, attribute acceptance processing for + scoped attributes is based on site metadata, + in addition to the mechanism described below for + simple attributes.
4.f. Using Attributes in - Applications
- +Simple:
-- -Apart from the simple RM functionality provided, attribute - information may be made available directly to applications - via the standard practice of creating custom HTTP request - headers before passing control to the application. - Applications should make no assumption about the presence of - specific attributes for their use unless they have intimate - knowledge of the attribute release policies in place.
- -The ShibMapAttribute directive controls this - interface, and maps a Shibboleth attribute (identified by an - unambiguous URI) to a header name, such as - Shib-EP-Affiliation. Using that example, any values - of the mapped attribute will be placed in that header, - delimited by spaces. An application that uses a CGI-like - syntax to access the header will find the values in the - HTTP_SHIB_EP_AFFILIATION variable. Using the - command, any attribute can be placed in any header, to drive - legacy applications that expect information in a particular - header.
- -The REMOTE_USER variable is a special case that - is generally populated automatically by the web server based - on an internal piece of data that represents the user's - username. Unlike many authentication modules, - Shibboleth does not guarantee that REMOTE_USER will - have any value. If it does, it is set solely based on a - ShibMapAttribute command. For many purposes, the - urn:mace:dir:attribute-def:eduPersonPrincipalName - attribute should be mapped to REMOTE_USER. Even so, - EPPN may not be provided by the AA, and REMOTE_USER - might still be empty.
- -The Shib-Origin-Site variable will contain the - unique name/identifier of the origin site of the user. Some applications may use this - to lookup additional policy or application data. It normally takes the form of a URI - but could be any string.
- -Finally, the ShibExportAssertion flag instructs - the module to place the entire XML message containing the - SAML attribute information from the AA into a base64-encoded - header called Shib-Attributes. This is a raw - interface that provides an application with the entire AA - response, and is not a filtered view based on any attribute - acceptance rules or even based on what attributes are - recognized by the target. What was sent is what you see.
+Simple attributes are attributes whose value is expressed in XML as a + Text node; that is, the value is just a string. Multiple values are + permitted. eduPersonEntitlement, in which the + values are URIs, is one example of a simple attribute.
+Both Simple and Scoped attribute acceptance is controlled with an + external policy file written in XML. The schema for the file is + described by the shibboleth.xsd schema, and + an example file is included, AAP.xml. It is + mandatory to supply such a file, because attributes are recognized based + on their presence in this file, and not by separate configuration + processes. Only by listing an attribute in the file will it be accepted + and processed by the RM.
+The policy is a default-deny algorithm that requires permissible + attributes and values be listed explicitly. That is, an empty file + permits nothing. Each attribute to be supported must be listed in the + file by name in an <AttributeRule>. Each such + rule is a collection of <SiteRule> elements + along with an optional <AnySite> default + rule. In turn each site rule is a set of <Value> + rules that specify matches to permit, either literal or regular + expressions, or a wildcarded <AnyValue> + default rule, which is equivalent to a single regular expression rule + allowing anything.
4.g. siterefresh
- +A syntax summary follows:
-+Shibboleth provides a simple tool called siterefresh in the /opt/shibboleth/bin folder of the - distribution to maintain metadata files referenced by shibboleth.ini. It will return 0 on - success and a negative number on failure and log errors to stderr. If the data in the new metadata - file is bad or the signature is invalid, the existing copy is - kept. The SHAR and SHIRE stat the file each time the data is - used, allowing them to detect and utilize updates in real-time - operation.
- -siterefresh takes the following - command-line parameters:
- --
- - --url <URL> -
- -- -
- -Specifies the URL of the - remote metadata file to update the local file.
-- - --out <pathname> -
- -- -
- -Specifies the local file to write the new metadata to.
-- - --cert <pathname> -
- -- -
- -Specifies the location of a certificate stored in PEM format used to validate the - signature of the metadata file. Since much of Shibboleth's - trust flows from this metadata file, this option is highly - recommended.
-- - --schema <pathname> +
<AttributeAcceptancePolicy
+++The top level element in the file.
+<AttributeRule
+
+ Name="urn:mace:dir:attribute-def:eduPersonScopedAffiliation"
+ Header="Shib-EP-Affiliation" Alias="affiliation">++Specifies a rule for an attribute, named by its URI. The + following XML attributes can be supplied:
++
++ +Name +The name of the Shibboleth attribute, usually a URI. + This is the only required XML attribute. ++ +Namespace +If the attribute's name includes a SAML namespace, + supply it here. Normally this is unused. ++ +Header +The HTTP request header to map the attribute's values + to. ++ +Alias +A short name for the attribute, determines the name of + the Apache Requires rule. +<AnySite>
+++Specifies a rule that always applies to the attribute, regardless + of the asserting AA.
+<SiteRule Name="host.domain.com">
+++A rule that applies to the origin site AA corresponding to the + hostname.
+<AnyValue>
+++Specifies a rule that always applies to the attribute and site, + regardless of the value(s).
+<Value Type="type">
+++Specifies a value to permit, either directly using + type literal, + or using a set of matching expressions as type + regexp. literal + is the default if Type is not specified.
+The regular expression syntax is a subset of the usual Perl and Unix + syntaxes that is described in the XML Schema specification by the W3C. Most + typical expressions should work. Be sure to anchor them using + ^ and $ to avoid + unintentional matches midstring.
+
++Apart from the simple RM functionality provided, attribute information + may be made available directly to applications via the standard practice of + creating custom HTTP request headers before passing control to the + application. Applications should make no assumption about the presence of + specific attributes for their use unless they have intimate knowledge of the + attribute release policies in place.
+The AAP metadata controls this interface, and maps a Shibboleth attribute + to a header name, such as Shib-EP-Affiliation. + Using that example, any values of the mapped attribute will be placed in + that header, delimited by semicolons. An application that uses a CGI-like + syntax to access the header will find the values in the + HTTP_SHIB_EP_AFFILIATION variable. Any attribute can be placed in any + header, to drive legacy applications that expect information in a particular + location.
+The REMOTE_USER variable is a special case + that is generally populated automatically by the web server based on an + internal piece of data that represents the current + username. Unlike many authentication modules, Shibboleth does not + guarantee that REMOTE_USER will have any value, + because users may remain anonymous in many cases. If it does have a value, + it is set solely because of an AAP file that maps an attribute to that + header name. For many purposes, the + urn:mace:dir:attribute-def:eduPersonPrincipalName attribute should be + mapped to REMOTE_USER. Even so, EPPN may not be + provided by the AA, and REMOTE_USER might still + be empty.
+The Shib-Origin-Site variable will contain the + unique name/identifier of the origin site of the user. Some applications may + use this to lookup additional policy or application data. It normally takes + the form of a URI but could be any string in some deployments.
+Finally, configuration may instruct the web server to place the entire + XML message containing the SAML attribute information from the AA into a + base64-encoded header called Shib-Attributes. + This is a raw interface that provides an application with the entire AA + response, and is not a filtered view based on any attribute acceptance rules + or even based on what attributes are recognized by the target. What was sent + is what you see.
+
++Shibboleth provides a simple tool called siterefresh + in the /opt/shibboleth/bin folder of the + distribution to maintain metadata files referenced by + shibboleth.ini. It will return 0 on success and a negative number on + failure and log errors to stderr. If the data in + the new metadata file is bad or the signature is invalid, the existing copy + is kept. The SHAR and SHIRE stat all metadata files each time the data is + used, allowing them to detect and utilize updates in real-time operation.
+siterefresh takes the following command-line + parameters:
++
- -- --url <URL>
+- Specifies the URL of the + remote metadata file with which to update the local file.
+- --out <pathname>
+- Specifies the local file to which to write the new + metadata.
+- --cert <pathname>
- -- -
Optionally defines a base path for schemas. Defaults to - /opt/shibboleth/etc/shibboleth/.
+- Specifies the location of a certificate stored in + PEM format used to validate the signature of + the metadata file. Since much of Shibboleth's security flows from + metadata files, this option is highly recommended, and the certificate + used should be verified independently.
+- --schema <pathname>
-A complete command issued to siterefresh would take the form:
- -- /opt/shibboleth/bin/siterefresh --out sites.xml --cert internet2.pem \- -
- --url http://wayf.internet2.edu/InQueue/sites.xml -It is recommended that similar commands be added to a crontab to keep the sites and trust files refreshed.
+Optionally defines a base path for schemas to use + when validating the file. Defaults to + /opt/shibboleth/etc/shibboleth/. + +A complete command issued to siterefresh might + take the form:
++- - -/opt/shibboleth/bin/siterefresh --out sites.xml + --cert internet2.pem \
+ --url http://wayf.internet2.edu/InQueue/sites.xml
-
-
- -5. Troubleshooting
- -This section provides basic information about testing - Shibboleth targets. This information is not intended to be - comprehensive, but instead rudimentary guidelines for basic - configuration tests and problems. For more detailed information - or answers to specific problems not addressed in this section, - please mail mace-shib-users@internet2.edu - with a thorough description of errors and configurations - used.
- -5.a. Basic Testing
- +It is recommended that similar commands be added to a + crontab to keep the site and trust files refreshed. AAP files tend to + be site-specific, but could be maintained and distributed centrally. If the + command is invoked in a script that writes the file to a new location and + compares it with the old contents before overwriting the original, the + command could be run very often without impacting target operations, + providing a high degree of currency in case sites become compromised.
+
+
This section provides basic information about testing Shibboleth targets. +This information is not intended to be comprehensive, but instead rudimentary +guidelines for basic configuration tests and problems. For more detailed +information or answers to specific problems not addressed in this section, +please mail +mace-shib-users@internet2.edu with a thorough description of errors and +configurations used.
+++The target may be tested by generating a folder with very basic access + controls on it, and accessing it using a web browser. Place a simple webpage + such as index.html in + /secure/. Then, add the following lines to + httpd.conf, which should be removed when testing is over:
-+The target may be tested by generating a folder with very - basic access controls on it, and accessing it using a web - browser. Place a simple webpage such as index.html - in /secure/. Then, add the following lines to - httpd.conf, which should be removed when testing is - over:
- -- # Configure a test directory- -
+# Configure a test directory
<Location /secure>
AuthType shibboleth
require valid-user
@@ -2327,25 +1846,23 @@ font-color: #121212; #AuthGroupFile /foo
#ShibExportAssertion On
</Location>
- -For information regarding specific error messages that - may be generated if the target does not work successfully, - please refer to section 4.b, or write mace-shib-users@internet2.edu.
+For information regarding specific error messages that may be + generated if the target does not work successfully, please refer to section + 5.b., or write + mace-shib-users@internet2.edu.
+
++ + -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.
-