Difference between revisions of "CAS Administration"

(Add/update additional external documentation/code links.)
(Redirect user to Janus)
(One intermediate revision by one other user not shown)
Line 1: Line 1:
Documentation about administering our [[CAS]] server infrastructure. More information and documentation about CAS can be found on the [https://www.apereo.org/projects/cas Apero site], [https://github.com/Jasig/cas CAS code], and [http://jasig.github.io/cas/ additional CAS documentation].
Content has been moved to: https://janus.middlebury.edu/display/WTASDOC/CAS+authentication
= Application Deployment =
== Setting up a development environment ==
* General
** Install Apache Tomcat
** Install the [http://dev.mysql.com/downloads/connector/j/3.1.htmll MySQL connector] JDBC driver
** Install Maven 2
* [http://www.adamfranco.com/2009/06/19/setting-up-a-cas-development-on-os-x/ Setting up CAS development on OS X] - Adam's cheat-sheet for OS X.
== Accessing the source code ==
Our CAS source-code is maintained as a "[https://wiki.jasig.org/display/CASUM/Maintaining+local+customizations+using+Maven+2 Maven overlay]" that includes just our customized files. All other (non-customized) files are automatically downloaded as part of the Maven build process.
To get our CAS source code, clone from our central [http://git-scm.com/ Git] repository on chisel. (if you don't have access, send Adam Franco your ssh public key.)
For CAS 3.x:
<pre>git clone git@git.middlebury.edu:web/midd-cas.git</pre>
For CAS 4.x:
<pre>git clone git@git.middlebury.edu:web/midd-cas4.git</pre>
Once you have cloned the Git repository, you should have a directory called <code>midd-cas</code>.
This directory contains the following files:
* <code>README.txt</code>
* <code>pom.xml</code> - The Maven configuration file. This tells Maven which version of CAS and each library to use and where to find them.
* <code>src/</code> - contains our customized source-code and configuration files.
* <code>target/</code> - the directory where maven will put the compiled <code>war</code> package.
=== Building/Running CAS ===
<pre>cd midd-cas/</pre>
==== Update the configuration if needed ====
<pre>vim src/main/webapp/WEB-INF/deployerConfigContext.xml</pre>
The configuration file committed to the Git repository on chisel is almost identical to the one in production. If you commit and push changes to this file, then update production, these changes will come through.
The current development configuration (in the source repository) refers to a database on chisel that holds the ticket registry and the services configuration. It is fine to continue to use this database if you wish. If not, you can configure another database. Look for the following lines at the bottom of the <code>deployerConfigContext.xml</code>:
<pre>    <bean
p:username="username" />
==== Build the war package ====
<pre>mvn clean package</pre>
==== Deploy the package ====
Deploying the package involves stopping tomcat, then deleting the CAS files from its <code>webapps/</code> directory and putting the new <code>war</code> file in that directory. When tomcat is started, it will extract the various resources from the <code>war</code> file and run the application.
<pre>sudo tomcatctl stop
sudo rm -R  /opt/local/share/java/tomcat5/webapps/cas*
sudo cp target/cas.war /opt/local/share/java/tomcat5/webapps/cas.war
sudo tomcatctl start
== Deploying to a new production host ==
=== Tomcat, MySQL connector, Maven ===
Install Tomcat, the MySQL connector, and Maven as described above.
=== Apache ===
In production, CAS must be run under SSL. Since running Tomcat with SSL support is challenging, we let Tomcat run on its default port (8080) and then run Apache as a proxy with SSL support (listening on port 443).
ProxyRequests Off
ProxyVia On
ProxyPass              /cas    http://localhost:8080/cas
ProxyPassReverse        /cas    http://localhost:8080/cas
=== Certificates ===
The CAS application must be able to validate (via Java/Tomcat) the certificates of any client applications that use it. Import certificate authority certificates into the Java environment using <code>keytool</code>. See: [https://wiki.jasig.org/display/CAS/Solving+SSL+issues https://wiki.jasig.org/display/CAS/Solving+SSL+issues] for details.
=== CAS Source ===
The new server's ssh key needs to be granted access to the git repository on chisel:
cat /root/.ssh/id_rsa.pub</pre>
Send Adam Franco the public key contents.
Clone the git repository:
<pre>git clone git@chisel.middlebury.edu:midd-cas.git</pre>
=== Configure the CAS server ===
You can see what configuration has been done on existing CAS hosts by cd'ing to the midd-cas directory and running:
<pre>git diff origin/master</pre>
There should only be a few lines changed in:
* <code>src/main/webapp/WEB-INF/cas.properties</code> - The production URL and hostname need to be set
* <code>src/main/webapp/WEB-INF/deployerConfigContext.xml</code> - The mysql database location will be changed to the production db.
* <code>src/main/webapp/WEB-INF/spring-configuration/ticketRegistry.xml</code> - On all but one CAS host, the ticket-registry-cleaner needs to be commented out so that the clean-up operations don't collide:
<pre>diff --git a/src/main/webapp/WEB-INF/spring-configuration/ticketRegistry.xml b/src/main/webapp/WEB-INF/spring-configuration/ticketRegis
index 96d958e..057841b 100644
--- a/src/main/webapp/WEB-INF/spring-configuration/ticketRegistry.xml
+++ b/src/main/webapp/WEB-INF/spring-configuration/ticketRegistry.xml
@@ -15,6 +15,7 @@
<tx:annotation-driven transaction-manager="transactionManager"/>
<bean id="ticketRegistryCleaner"
@@ -41,5 +42,5 @@
'''Keep track of your config changes:'''
After you make changes to the CAS configuration, commit them to the local repository on the production host using git:
<pre>git status
git diff
git add file/that/was/changed
git status
git commit -m "Made such and such config change."</pre>
You can see a history of changes via <pre>git log</pre> or with git 1.5.6 and later <pre>git log --graph</pre>.
=== Deploy ===
Deployment is the same as listed above:
# <code>mvn package clean</code>
# <code>tomcatctl stop
# delete the files from tomcat's <code>webapps/</code> directory
# copy over the <code>war</code> file to tomcat's <code>webapps/</code> directory
# <code>tomcatctl start</code>
On our production hosts, this deploy process has been scripted as a <code>rebuild_cas</code> command:
<pre>[root@hostname ~]# cat /usr/local/bin/rebuild_cas
cd /usr/local/CAS/midd-cas
mvn clean package
if [ $? -ne 0 ]
exit $?
rm /usr/share/tomcat6/webapps/cas.war
rm -R /usr/share/tomcat6/webapps/cas
cp target/cas.war /usr/share/tomcat6/webapps/cas.war
service tomcat6 restart
{{Note|Note: Sometimes (but not always) Apache will not regain communication with Tomcat after tomcat is restarted. Check this by loading the [https://mercury.middlebury.edu/cas/login server-specific URL] and restarting apache if needed with <code>service httpd restart</code>}}
{{Note|Note: Currently cas will not build on hermes and must be built on mercury and copied to hermes. Do this in <code>workbench/midd-cas-hermes/</code>. }}
== Upgrading CAS to a new version ==
Upgrading CAS involves editing the pom.xml to refer to the new version, then updating any of our customized files that have changed.
After cloning the repository in a development environment, edit pom.xml and update the cas.version line:
to the new CAS version desired. The release versions available are listed in [https://oss.sonatype.org/content/repositories/releases/org/jasig/cas/cas-server-webapp/maven-metadata.xml cas-server-webapp/maven-metadata.xml]
=== Troubleshooting Upgrade Issues ===
Try deploying CAS, if it fails to start, look at <code>tomcat5/logs/catalina.out</code> for what broke.
When updating CAS some of the libraries it depends on may also need their versions bumped in the <code>pom.xml</code>. Look at the [https://source.jasig.org/cas3/tags/cas-server-3.4.8/pom.xml pom.xml] for the release in question to see what the default library versions are.
Similarly, new versions of CAS may expect to have additional beans configured by default. Look at the and [https://source.jasig.org/cas3/tags/cas-server-3.4.8/cas-server-webapp/src/main/webapp/WEB-INF/deployerConfigContext.xml deployerConfigContext.xml] for the new release to see what the defaults are and apply them to our <code>deployerConfigContext.xml</code>. Errors like <code>No bean named 'xxxxYyyyyZzzzz' is defined</code> indicate that a new bean needs to be configured.
=== Saving Your Updates ===
Once you have successfully updated CAS in your development/testing environment, commit your changes using Git, then push them to the central repository:
<pre>[afranco@Walnut midd-cas]$ git status
# On branch master
# Changes not staged for commit:
#  (use "git add <file>..." to update what will be committed)
#  (use "git checkout -- <file>..." to discard changes in working directory)
# modified:  pom.xml
# modified:  src/main/webapp/WEB-INF/deployerConfigContext.xml
no changes added to commit (use "git add" and/or "git commit -a")
[afranco@Walnut midd-cas]$ git diff
diff --git a/pom.xml b/pom.xml
index 262e5b4..1da061c 100644
--- a/pom.xml
+++ b/pom.xml
@@ -76,7 +76,7 @@
-              <cas.version></cas.version>
+              <cas.version>3.4.8</cas.version>
diff --git a/src/main/webapp/WEB-INF/deployerConfigContext.xml b/src/main/webapp/WEB-INF/deployerConfigContext.xml
index 9182ab6..613a21d 100644
--- a/src/main/webapp/WEB-INF/deployerConfigContext.xml
+++ b/src/main/webapp/WEB-INF/deployerConfigContext.xml
@@ -251,5 +251,6 @@
p:username="username" />
+      <bean id="auditTrailManager" class="com.github.inspektr.audit.support.Slf4jLoggingAuditTrailManager" />
[afranco@Walnut midd-cas]$ git add .
[afranco@Walnut midd-cas]$ git status
# On branch master
# Changes to be committed:
#  (use "git reset HEAD <file>..." to unstage)
# modified:  pom.xml
# modified:  src/main/webapp/WEB-INF/deployerConfigContext.xml
[afranco@Walnut midd-cas]$ git commit -m "Upgraded CAS to verion 3.4.8.
> This required adding an audit bean that is now enabled by default."
[master 3aec0ad] Upgraded CAS to verion 3.4.8.
2 files changed, 3 insertions(+), 2 deletions(-)
[afranco@Walnut midd-cas]$ git push
Counting objects: 15, done.
Delta compression using up to 4 threads.
Compressing objects: 100% (6/6), done.
Writing objects: 100% (8/8), 784 bytes, done.
Total 8 (delta 3), reused 0 (delta 0)
To git@chisel.middlebury.edu:midd-cas.git
af69dbe..3aec0ad  master -> master
=== Deploying Updates to Production ===
Updates to the CAS application on the production hosts are performed by fetching the new commits containing the updates from the central Git repository, then merging them with the production hosts's own config changes.
Generally this can be accomplished by:
<pre>[user@desktop ~]$ ssh root@hostname
[root@hostname ~]$ cd /usr/local/CAS/midd_cas/
[root@hostname midd-cas]$ git pull
remote: Counting objects: 15, done.
remote: Compressing objects: 100% (6/6), done.
remote: Total 8 (delta 3), reused 0 (delta 0)
Unpacking objects: 100% (8/8), done.
From chisel.middlebury.edu:midd-cas
af69dbe..3aec0ad  master    -> origin/master
Updating af69dbe..3aec0ad
pom.xml                                          |    2 +-
src/main/webapp/WEB-INF/deployerConfigContext.xml |    3 ++-
2 files changed, 3 insertions(+), 2 deletions(-)
[root@hostname midd-cas]$ rebuild_cas
If there are merge conflicts (such as if a line that was customized in production was also changed in the upgrade), then edit the file to resolve the merge and commit the changes:
<pre>[user@desktop ~]$ ssh root@hostname
[root@hostname ~]$ cd /usr/local/CAS/midd_cas/
[root@hostname midd_cas]$ git pull
remote: Counting objects: 15, done.
remote: Compressing objects: 100% (6/6), done.
remote: Total 8 (delta 3), reused 0 (delta 0)
Unpacking objects: 100% (8/8), done.
From chisel.middlebury.edu:midd-cas
af69dbe..3aec0ad  master    -> origin/master
Auto-merging src/main/webapp/WEB-INF/deployerConfigContext.xml
CONFLICT (content): Merge conflict in src/main/webapp/WEB-INF/deployerConfigContext.xml
Automatic merge failed; fix conflicts and then commit the result.
[root@hostname midd_cas]$ vim src/main/webapp/WEB-INF/deployerConfigContext.xml
[root@hostname midd_cas]$ git add src/main/webapp/WEB-INF/deployerConfigContext.xml
[root@hostname midd_cas]$ git commit
[root@hostname midd-cas]$ rebuild_cas
= Midd Customizations =
Beyond the standard config-file changes, we run two CAS customizations that dramatically lessen the work that our web-applications need to do when authorizing users: user-attributes in the CAS 2.0 protocol response and ancestor group searching. With these two customizations, client application do not need to do any additional work (other than looking at the CAS response) to get the name, email, and group-membership of the user who logged in. This lessens the complexity of client applications and reduces the number of places that infrastructure-specific customizations (such as ancestor group searching) and configuration need to be made.
== Attributes in the CAS 2.0 protocol response ==
The background and usage of this customization is documented in [[CAS#CAS_2.0_Protocol_Extension:_Attributes|CAS 2.0 Protocol Extension: Attributes]].
The implementation of the customization is the addition of the following line to <code>midd_cas/src/main/webapp/WEB-INF/view/jsp/protocol/2.0/casServiceValidationSuccess.jsp</code>
<pre><cas:attribute name="${fn:escapeXml(attr.key)}" value="${fn:escapeXml(attrVal)}"/></c:forEach></c:forEach></c:forEach></pre>
== Ancestor Group Searching ==
In our Active Directory, groups may have other groups as members. This presents problems for applications that wish to authorize users based on group membership since most applications simply look at users' MemberOf attribute list and don't check to see if those groups are in turn members of other groups.
To ease this pain, our CAS implementation solves this problem centrally by recursively searching for ancestor groups are returning the full list of direct and ancestor groups as the users' MemberOf attribute list.
These customizations are located in the PersonDir class-files in <code>midd_cas/src/main/java/org/jasig/services/persondir/support/ldap/</code>.
The custom <code>LdapPersonAttributeDao</code> works just like the normal one, but sets our custom <code>AttributeMapAttributesMapper</code> as the Attribute Mapper to use. In turn, our custom <code>AttributeMapAttributesMapper</code> works like the normal one, except that when it encounters a memberOf attribute, it recursively searches for ancestor groups (while avoiding cycles).
== Midd Theme ==
The middlebury theme files are located at <code>midd_cas/src/main/webapp/WEB-INF/view/jsp/midd2010/</code>.
= Run-time Administration =
== Allowed Services Configuration ==
Each application that authenticates with CAS needs to be added to the "Allowed Services" list. Currently this list is stored in a database table in the shared database that is also used as the ticket registry.
Services can be managed at: [https://login.middlebury.edu/cas/services/ https://login.middlebury.edu/cas/services/]
When new services are added, the CAS servers will pick them up within 5-10 minutes.
== Troubleshooting Errors ==
The CAS logs are stored at <code>/usr/share/tomcat5/logs/catalina.out</code>.
= To-Do list =
* [https://wiki.jasig.org/display/CASUM/Clustering+CAS Multicast Ticket Registry] or [https://wiki.jasig.org/display/CASUM/EhcacheTicketRegistry EhCache Ticket Registry] for high availability - Currently the ticket-registry database is a single point of failure. Updating to a ticket-registry implementation that allows each CAS server to validate its peers without a single intermediary will help ensure high availability.
[[Category:Web Application Development]]
[[Category:Web Application Development]]

Latest revision as of 12:10, 1 March 2018

Powered by MediaWiki