{"type":"doc","content":[{"type":"paragraph","content":[{"text":"The Shibboleth SP is presently only implemented in C++ as a module for Apache, IIS, and so forth. However, it's straightforward to use it to provide authentication and authorization for Java servlets in servlet containers by tunneling or proxying requests through a supported web server.","type":"text"}]},{"type":"paragraph","content":[{"text":"Requests from the browser are intercepted first by Apache. After a Shibboleth SP session is established, the SP or Apache can enforce access control rules, or it can just pass attributes along to an application. The request is then forwarded to the servlet through the use of the AJP binary protocol, or alternatively via HTTP reverse proxying. Subsequent requests can leverage the Shibboleth session or a session maintained by the application or servlet container to persist the login.","type":"text"}]},{"type":"paragraph","content":[{"text":"Note that it's certainly possible to do all this with IIS, but it is not recommended and is beyond the scope of this example.","type":"text"}]},{"type":"heading","attrs":{"level":4},"content":[{"text":"1. Setup Apache with Shibboleth","type":"text"}]},{"type":"paragraph","content":[{"text":"Install Apache first. All supported versions include ","type":"text"},{"text":"mod_proxy_ajp","type":"text","marks":[{"type":"code"}]},{"text":" in the main distribution.","type":"text"}]},{"type":"paragraph","content":[{"text":"Next, install Shibboleth itself. This is a platform-dependent decision, so go back to the ","type":"text"},{"text":"main installation page","type":"text","marks":[{"type":"link","attrs":{"href":"/wiki/spaces/SP3/pages/2065335537"}}]},{"text":" and select the one that applies. After you complete the installation process, please return here and continue.","type":"text"}]},{"type":"heading","attrs":{"level":4},"content":[{"text":"2. (Optional) Setup AJP13 support in your servlet container","type":"text"}]},{"type":"paragraph","content":[{"text":"While HTTP proxying is a possible approach, if AJP is supported that is a recommended choice because it is allows applications to operate somewhat more securely (though in practice, the real issue is the same: you MUST secure the connection between Apache and the servlet container). The main difference is that with HTTP proxying, it's easier to make a mistake and accidentally expose the back-end container to direct access by a browser, and once that's done, all security is lost due to the ease of smuggling headers into the application. It also makes establishing the REMOTE_USER variable more complex since it would depend on a Java filter establishing it from a header.","type":"text"}]},{"type":"paragraph","content":[{"text":"Assuming AJP, This step depends on your servlet container, but Tomcat and its derivatives have an AJP connector commented out by default.","type":"text"}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Setting the ","type":"text"},{"text":"tomcatAuthentication=\"false\"","type":"text","marks":[{"type":"code"}]},{"text":" attribute on the AJP ","type":"text"},{"text":"","type":"text","marks":[{"type":"code"}]},{"text":" element allows ","type":"text"},{"text":"REMOTE_USER","type":"text","marks":[{"type":"code"}]},{"text":" to be automatically set based on what Apache has set. See Tomcat's ","type":"text"},{"text":"AJP Connector documentation","type":"text","marks":[{"type":"link","attrs":{"href":"http://tomcat.apache.org/"}}]},{"text":" for more details.","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Recent Tomcat versions also limit the acceptance of ","type":"text"},{"text":"any","type":"text","marks":[{"type":"em"}]},{"text":" attributes, and the ","type":"text"},{"text":"allowedRequestAttributesPattern","type":"text","marks":[{"type":"code"}]},{"text":" setting must be added to approve the attribute names to accept (or wildcarded).","type":"text"}]}]}]},{"type":"paragraph","content":[{"text":"Be careful that there is no direct HTTP listener opened by the servlet container.","type":"text","marks":[{"type":"strong"}]}]},{"type":"paragraph","content":[{"text":"If, for example, there's an HTTP connector listening on port 8080 and no interceding firewall, users would be able to directly access the servlet on port 8080, which bypasses Apache. This also means they would bypass Shibboleth authentication and authorization.","type":"text"}]},{"type":"heading","attrs":{"level":5},"content":[{"text":"AJP packet size","type":"text"}]},{"type":"paragraph","content":[{"text":"Service Providers that leverage many attributes or receive many attribute values can expect to exceed the default maximum AJP packet size (8kb). In order to prevent this, raise the maximum AJP packet size to 65kb (maximum allowed by the AJP protocol) or whatever value in between makes sense.This value should be specified ","type":"text"},{"text":"both","type":"text","marks":[{"type":"strong"}]},{"text":" in Apache and your servlet container configuration.","type":"text"}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Tomcat","type":"text","marks":[{"type":"strong"}]},{"text":": Add a ","type":"text"},{"text":"packetSize=\"65536\"","type":"text","marks":[{"type":"code"}]},{"text":" to the AJP ","type":"text"},{"text":"","type":"text","marks":[{"type":"code"}]},{"text":" element.","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Apache with mod_jk","type":"text","marks":[{"type":"strong"}]},{"text":": Add a ","type":"text"},{"text":"worker..max_packet_size","type":"text","marks":[{"type":"link","attrs":{"href":"http://tomcat.apache.org/connectors-doc/reference/workers.html"}}]},{"text":" directive to the worker definition.","type":"text"}]},{"type":"codeBlock","content":[{"text":"worker..max_packet_size=65536","type":"text"}]},{"type":"paragraph","content":[{"type":"hardBreak"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Apache with mod_proxy_ajp","type":"text","marks":[{"type":"strong"}]},{"text":": Add a ","type":"text"},{"text":"ProxyIOBufferSize","type":"text","marks":[{"type":"link","attrs":{"href":"http://httpd.apache.org/docs/2.2/en/mod/mod_proxy.html#proxyiobuffersize"}}]},{"text":" directive to Apache's configuration.","type":"text"}]},{"type":"codeBlock","content":[{"text":"ProxyIOBufferSize 65536","type":"text"}]},{"type":"paragraph","content":[{"type":"hardBreak"}]}]}]},{"type":"heading","attrs":{"level":4},"content":[{"text":"3. Configure Apache to route requests to your servlet","type":"text"}]},{"type":"paragraph","content":[{"text":"Add a line to your Apache configuration, often in a ","type":"text"},{"text":"","type":"text","marks":[{"type":"code"}]},{"text":" definition, to proxy requests to your application through AJP:","type":"text"}]},{"type":"codeBlock","content":[{"text":"ProxyPass /my-application ajp://localhost:8009/my-application\n","type":"text"}]},{"type":"paragraph","content":[{"text":"Note that you probably don't want to proxy the root of the server, but if you did want to \"relocate\" a servlet application to the Apache root that way, you'll need to exclude the SP's handler URLs from this proxying:","type":"text"}]},{"type":"codeBlock","content":[{"text":"ProxyPass /Shibboleth.sso/* !","type":"text"}]},{"type":"heading","attrs":{"level":4},"content":[{"text":"4. Add Shibboleth protection for your servlet","type":"text"}]},{"type":"paragraph","content":[{"text":"This is dependent on the way you want to ","type":"text"},{"text":"integrate","type":"text","marks":[{"type":"link","attrs":{"href":"/wiki/spaces/SP3/pages/2065335333"}}]},{"text":" your application with the SP, but you could for example add a line to your Apache configuration on the proper virtual host to trigger Shibboleth session initiation and authentication for your application:","type":"text"}]},{"type":"codeBlock","content":[{"text":"\n AuthType shibboleth\n ShibRequestSetting requireSession 1\n require valid-user\n\n","type":"text"}]},{"type":"paragraph","content":[{"text":"Since environment variables are not passed by ","type":"text"},{"text":"mod_proxy_ajp","type":"text","marks":[{"type":"code"}]},{"text":" unless they have ","type":"text"},{"text":"AJP_","type":"text","marks":[{"type":"code"}]},{"text":" prefixes, you'll also need to add ","type":"text"},{"text":"attributePrefix=\"AJP_\"","type":"text","marks":[{"type":"code"}]},{"text":" to the ","type":"text"},{"text":"","type":"text","marks":[{"type":"link","attrs":{"href":"/wiki/spaces/SP3/pages/2063695997"}}]},{"text":" (or in rare cases an appropriate ","type":"text"},{"text":"","type":"text","marks":[{"type":"link","attrs":{"href":"/wiki/spaces/SP3/pages/2063696335"}}]},{"text":") element in your configuration:","type":"text"}]},{"type":"codeBlock","content":[{"text":"\n","type":"text"}]},{"type":"paragraph","content":[{"text":"In a Java web application, environment variables can be accessed by calling the ","type":"text"},{"text":"HttpServletRequest.getAttribute","type":"text","marks":[{"type":"code"}]},{"text":" method. Note that Tomcat's implementation of the ","type":"text"},{"text":"getAttributeNames","type":"text","marks":[{"type":"code"}]},{"text":" method is broken, as described in the following ","type":"text"},{"text":"thread","type":"text","marks":[{"type":"link","attrs":{"href":"http://shibboleth.1660669.n2.nabble.com/Unable-to-find-environment-attributes-in-tomcat-application-td7640442.html"}}]},{"text":" in the Shibboleth users mailing list.","type":"text"}]},{"type":"panel","attrs":{"panelType":"error"},"content":[{"type":"heading","attrs":{"level":3},"content":[{"text":"Struts 2 Issue","type":"text"}]},{"type":"paragraph","content":[{"text":"When deploying an application written using the Struts 2 framework, see the Java example section on the ","type":"text"},{"text":"attribute access","type":"text","marks":[{"type":"link","attrs":{"href":"/wiki/spaces/SP3/pages/2065335257"}}]},{"text":" page for an issue with retrieving attribute values with certain problematic names.","type":"text"}]}]},{"type":"paragraph","content":[{"type":"hardBreak"}]}],"version":1}