From d72913b53a2d33210c50eea9ea3854400a4490a4 Mon Sep 17 00:00:00 2001 From: Misagh Moayyed Date: Sat, 23 May 2015 22:01:48 +0400 Subject: [PATCH] Update README.md --- README.md | 143 ++++++++++++++++++++++++++++++++++++++++++++++++++++-- 1 file changed, 139 insertions(+), 4 deletions(-) diff --git a/README.md b/README.md index 9eccc72..6018115 100644 --- a/README.md +++ b/README.md @@ -543,7 +543,7 @@ A general JAAS authentication module, `CasLoginModule`, is available with the sp ### Configure CasLoginModule It is expected that for JEE applications both authentication and authorization services will be required for CAS integration. The following JAAS module configuration file excerpt demonstrates how to leverage SAML 1.1 attribute release in CAS to provide authorization data in addition to authentication: -```json +``` cas { org.jasig.cas.client.jaas.CasLoginModule required ticketValidatorClass="org.jasig.cas.client.validation.Saml11TicketValidator" @@ -644,9 +644,144 @@ If you have any trouble, you can enable the log of cas in `jboss-logging.xml` by ``` -## Tomcat 6 Integration +## Tomcat 6/7 Integration +The client supports container-based CAS authentication and authorization support for the Tomcat servlet container. -## Tomcat 7 Integration +Suppose a single Tomcat container hosts multiple Web applications with similar authentication and authorization needs. Prior to Tomcat container support, each application would require a similar configuration of CAS servlet filters and authorization configuration in the `web.xml` servlet descriptor. Using the new container-based authentication/authorization feature, a single CAS configuration can be applied to the container and leveraged by all Web applications hosted by the container. + +CAS authentication support for Tomcat is based on the Tomcat-specific Realm component. The Realm component has a fairly broad surface area and RealmBase is provided as a convenient superclass for custom implementations; the CAS realm implementations derive from `RealmBase`. Unfortunately RealmBase and related components have proven to change over both major and minor number releases, which requires version-specific CAS components for integration. We have provided two packages with similar components with the hope of supporting all 6.x and 7.x versions. **No support for 5.x is provided.** + +### Component Overview +In the following discussion of components, only the Tomcat 6.x components are mentioned. The Tomcat 7.0.x components have exactly the same name, but **are in the tomcat.v7 package**, e.g. `org.jasig.cas.client.tomcat.v7.Cas20CasAuthenticator`. + +#### Authenticators +Authenticators are responsible for performing CAS authentication using a particular protocol. All protocols supported by the Jasig Java CAS client are supported: CAS 1.0, CAS 2.0, and SAML 1.1. The following components provide protocol-specific support: + +``` +org.jasig.cas.client.tomcat.v6.Cas10CasAuthenticator +org.jasig.cas.client.tomcat.v6.Cas20CasAuthenticator +org.jasig.cas.client.tomcat.v6.Cas20ProxyCasAuthenticator +org.jasig.cas.client.tomcat.v6.Saml11Authenticator +``` + +#### Realms +In terms of CAS configuration, Tomcat realms serve as containers for users and role definitions. The roles defined in a Tomcat realm may be referenced in the web.xml servlet descriptor to define authorization constraints on Web applications hosted by the container. Two sources of user/role data are supported: + +``` +org.jasig.cas.client.tomcat.v6.PropertiesCasRealm +org.jasig.cas.client.tomcat.v6.AssertionCasRealm +``` + +`PropertiesCasRealm` uses a Java properties file as a source of static user/role information. This component is conceptually similar to the `MemoryRealm` component that ships with Tomcat and defines user/role data via XML configuration. The PropertiesCasRealm is different in that it explicitly lacks support for passwords, which have no use with CAS. + +`AssertionCasRealm` is designed to be used in conjunction with the SAML 1.1. protocol to take advantage of CAS attribute release to provide for dynamic user/role data driven by the CAS server. With this component the deployer may define a role attribute, e.g. memberOf, which could be backed by LDAP group membership information. In that case the user would be added to all roles defined in the SAML attribute assertion for values of the the `memberOf` attribute. + +#### Valves +A number of Tomcat valves are provided to handle functionality outside Realms and Authenticators. + +##### Logout Valves +Logout valves provide a way of destroying the CAS authentication state bound to the container for a particular user/session; the destruction of authenticated state is synonymous with logout for the container and its hosted applications. (Note this does not destroy the CAS SSO session.) The implementations provide various strategies to map a URI onto the state-destroying logout function. + +``` +org.jasig.cas.client.tomcat.v6.StaticUriLogoutValve +org.jasig.cas.client.tomcat.v6.RegexUriLogoutValve +``` + +##### SingleSignOutValve +The `org.jasig.cas.client.tomcat.v6.SingleSignOutValve` allows the container to participate in CAS single sign-out. In particular this valve handles the SAML LogoutRequest message sent from the CAS server that is delivered when the CAS SSO session ends. + +##### ProxyCallbackValve +The `org.jasig.cas.client.tomcat.v6.ProxyCallbackValve` provides a handler for watching request URIs for requests that contain a proxy callback request in support of the CAS 2.0 protocol proxy feature. + +### Container Setup +The version-specific CAS libraries must be placed on the container classpath, `$CATALINA_HOME/lib`. + +### Context Configuration +The Realm, Authenticator, and Valve components are wired together inside a Tomcat Context configuration element. The location and scope of the Context determines the scope of the applied configuration. To apply a CAS configuration to every Web application hosted in the container, configure the default Context at `$CATALINA_HOME/conf/context.xml`. Note that individual Web applications/servlets can override the default context; see the Context Container reference for more information. + +Alternatively, CAS configuration can be applied to individual Web applications through a Context configuration element located in a `$CONTEXT_NAME.xml` file placed in `$CATALINA_HOME/conf/$ENGINE/$HOST`, where `$ENGINE` is typically Catalina and `$HOST` is `localhost`, `$CATALINA_HOME/conf/Catalina/localhost`. For example, to configure the Tomcat manager servlet, a `manager.xml` file contains Context configuration elements. + +```xml + + + + + + + + + + + + +``` + +The following example shows how to configure a Context for dynamic role data provided by the CAS attribute release feature. + +```xml + + + + + + + + + +``` ## Atlassian Integration The clien includes Atlassian Confluence and JIRA support. Support is enabled by a custom CAS authenticator that extends the default authenticators. @@ -947,4 +1082,4 @@ mvn clean package Please note that to be deployed in Maven Central, we mark a number of JARs as provided (related to JBoss and Memcache Clients). In order to build the clients, you must enable the commented out repositories in the appropriate `pom.xml` -files in the modules (cas-client-integration-jboss and cas-client-support-distributed-memcached) or follow the instructions on how to install the file manually. +files in the modules (`cas-client-integration-jboss` and `cas-client-support-distributed-memcached`) or follow the instructions on how to install the file manually.