While it is true that CAS is not a turnkey solution, and it is also true that the documentation has vastly improved since the early days of CAS, I think it is fair to say there is room for improvement in the CAS documentation.
The criticism that the documentation is somewhat lacking in terms of reliable tutorials seems to be fairly accurate. The documentation is mainly organized as reference material, with a bit of HOWTO documentation mixed in. Daniele Procida (of the Django project) gave a really great discussion on what makes documentation successful[1], and why people won't use your project if you don't have good documentation. Based on his categorizations, I'd conclude that CAS documentation would benefit most from improvements to its tutorial and discussion documentation, followed by beefing up its HOWTO documentation. While I think the subject "CAS documentation for a new user is terrible" may be somewhat provocative, I believe the message that CAS documentation could be improved to help new users come to grips with it more easily is a valid criticism. I can think of another open source project in the web SSO space that has essentially rejected this kind of criticism entirely much to the detriment of its community. I believe the CAS community can do better in this area. Thanks, Carl Waldbieser ITS Identity Management Lafayette College [1] https://www.google.com/url?sa=t&rct=j&q=&esrc=s&source=web&cd=1&cad=rja&uact=8&ved=0ahUKEwi4tryv7v_YAhVB21MKHarEB14QtwIIJzAA&url=https%3A%2F%2Fwww.youtube.com%2Fwatch%3Fv%3Dazf6yzuJt54&usg=AOvVaw2GPsIKe4Ur91Zx9ASL2rsu ----- Original Message ----- From: "Michael O Holstein" <michael.holst...@csuohio.edu> To: "cas-user" <cas-user@apereo.org> Sent: Monday, January 29, 2018 4:18:32 PM Subject: Re: [cas-user] Re: CAS documentation for a new user is terrible CAS is an open-source project. It is not plug-and-play. If you want a turnkey implementation, I'd recommend contacting Unicon (the principal architects) who offer it as a hosted solution, various support contracts, and implementation consulting. ________________________________ From: cas-user@apereo.org <cas-user@apereo.org> on behalf of David Curry <david.cu...@newschool.edu> Sent: Monday, January 29, 2018 2:52:29 PM To: cas-user@apereo.org Subject: Re: [cas-user] Re: CAS documentation for a new user is terrible For those of you who are new to CAS and looking for some help, in addition to Carl's task list (for lack of a better word), I have been making this available for anyone who wants it: https://dacurry-tns.github.io/deploying-apereo-cas/introduction_overview.html It's NOT official, and it's not the only way to do things, but it's pretty verbose and step-by-step. I just updated it the other day with my initial work on doing some high availability stuff with MongoDb, so it's up-to-date with CAS 5.2.2-SNAPSHOT. --Dave -- DAVID A. CURRY, CISSP DIRECTOR OF INFORMATION SECURITY INFORMATION TECHNOLOGY 71 FIFTH AVE., 9TH FL., NEW YORK, NY 10003 +1 212 229-5300 x4728 • david.cu...@newschool.edu<mailto:david.cu...@newschool.edu> [The New School] On Mon, Jan 29, 2018 at 2:08 PM, Matthew Uribe <matthew.ur...@aims.edu<mailto:matthew.ur...@aims.edu>> wrote: Jan, I have to say, as another new arrival to the CAS world, that I agree with your statements, and wish I would have encountered your post several weeks ago. I appreciate the link to guide, and hope that others will find it earlier in their journey than I did. Also, I want to thank all who have contributed directly to the project, as well as here in the group. On Monday, October 30, 2017 at 7:50:43 AM UTC-6, Jan wrote: Hello, As a new user of CAS, I'd like to voice my opinion that the official documentation of how one can get started with CAS is just awful. By this I mean not the lack of it, but rather how indirect, not step-by-step it is. Clarity could often be improved too. In the end I managed to do what I hoped for, ie investigate CAS locally as an SSO solution, for which I needed to (1) run CAS server locally, (2) connect and authenticate using a simple CAS client locally, (3) run the service management app. However, the difficulty I had at most steps of getting it all to work make me really want to use something else even if I have to implement parts of it from scratch.. Only now, when wanting to post this message, did I find this helpful guide: https://dacurry-tns.github.io/deploying-apereo-cas/ Could the CAS team incorporate some step-by-step tutorial like this into the official documentation? These threads seem to voice a similar concern: https://groups.google.com/a/apereo.org/forum/#!searchin/cas-user/documentation/cas-user/z3BLJ0IQwZ0/wRybEK1LAQAJ https://groups.google.com/a/apereo.org/forum/#!searchin/cas-user/documentation/cas-user/qaAINooFi1s/D3k7Pr-7BQAJ I'm also posting the notes I made for myself during the process. I wouldn't have written them if there was something like this available in official docs, or I had found the unofficial guide earlier. I'm adding **** to points that took me particularly long to figure out. Building - Described here: https://apereo.github.io/cas/developer/Build-Process.html - git clone --depth=1 --single-branch --branch=master g...@github.com:apereo/cas.git cas-server - cd cas-server - git checkout master - ./gradlew build install --parallel -x test -x javadoc -x check Config - Default config dir is /etc/cas/config (may need to be created, given permissions) If you create application.properties in there, CAS seems to pick them up. **** - You can override in there any properties listed on https://apereo.github.io/cas/development/installation/Configuration-Properties.html Keys - keytool -genkey -alias cas -keyalg RSA -validity 999 -keystore /etc/cas/thekeystore -ext san=dns:cas-sso.local - Add 127.0.0.1 cas-sso.local to /etc/hosts - keytool -export -file /etc/cas/config/cas.crt -keystore /etc/cas/thekeystore -alias cas - sudo keytool -import -file /etc/cas/config/cas.crt -alias cas -keystore $JAVA_HOME/jre/lib/security/cacerts (default password to cacerts is changeit) - Add the following lines to application.properties in CAS config dir (with whatever password you set up for /etc/cas/thekeystore) **** server.ssl.keyStorePassword=qwer1234 server.ssl.keyPassword=qwer1234 Adding JSON service registry (to get a sample client registered) - Add line >>compile "org.apereo.cas:cas-server-support-json-service-registry:5.2.0-SNAPSHOT"<< to the file cas-server/webapp/cas-server-webapp-tomcat/build.gradle, replacing 5.2.0-SNAPSHOT with whatever version of CAS you have. The version can be figured out after starting CAS (is displayed). **** - Recompile the whole thing as above. - Add the following lines to application.properties in CAS config dir: **** cas.serviceRegistry.watcherEnabled=true cas.serviceRegistry.repeatInterval=10 cas.serviceRegistry.startDelay=1 cas.serviceRegistry.initFromJson=true - Add json file with service defs in directory cas-server/webapp/resources/services (the server seems to display which directory it watches after start). { "@class" : "org.apereo.cas.services.RegexRegisteredService", "serviceId" : "http://localhost/.*";, **** "name" : "testId", "id" : 1, "accessStrategy" : { "@class" : "org.apereo.cas.services.DefaultRegisteredServiceAccessStrategy", "enabled" : true, "ssoEnabled" : true } } Getting access to /status/dashboard endpoint **** - Add the following lines to application.properties in CAS config dir: cas.adminPagesSecurity.ip=127\.0\.0\.1 cas.monitor.endpoints.enabled=true cas.monitor.endpoints.sensitive=false Running - cd webapp/cas-server-webapp-tomcat - ../../gradlew build bootRun --parallel Simple client - git clone g...@github.com:apereo/phpCAS.git - cd phpCAS - Copy docs/examples/config.example.php to docs/examples/config.php and edit: // Full Hostname of your CAS Server $cas_host = 'cas-sso.local'; // Context of the CAS Server $cas_context = '/cas'; // Port of your CAS server. Normally for a https server it's 443 $cas_port = 8443; - Make the file docs/examples/example_simple.php accessible by www. - Navigate to http://localhost/phpCAS/docs/examples/example_simple.php Service management app - Based on https://github.com/apereo/cas-services-management-overlay - git clone g...@github.com:apereo/cas-services-management-overlay.git - cd cas-services-management-overlay - ./build.sh package - This creates target/cas-management.war, which should be deployed to Tomcat. Make sure Tomcat uses the same Java as CAS server. Otherwise, it won't find the SSL keys in the Java truststore. **** - On first run, it copies various files from cas/config into /etc/cas/config. You may want to update management.properties as follows, in particular: # CAS server that management app will authenticate with # This server will authenticate for any app (service) and you can login as casuser/Mellon cas.server.name<http://cas.server.name>: https://cas-sso.local:8443/ cas.server.prefix: https://cas-sso.local:8443/cas cas.mgmt.adminRoles[0]=ROLE_ADMIN cas.mgmt.userPropertiesFile=file:/etc/cas/config/users.properties # Update this URL to point at server running this management app cas.mgmt.serverName=http://localhost:8080 server.context-path=/cas-management server.port=8080 logging.config=file:/etc/cas/config/log4j2-management.xml - http://localhost:8080/cas-management Conclusions - Really painful to set up. - CAS documentation is very unclear, tons of linked documents, not sure where to find information. - Wonder if better to do OAuth2 even if redirecting to Google / FB needs to be implemented from scratch. --- With all that, thank you for writing and maintaining this software. It does seem like a good choice for SSO solutions - but the initial learning curve shouldn't be quite so sharp. Jan -- - Website: https://apereo.github.io/cas - Gitter Chatroom: https://gitter.im/apereo/cas - List Guidelines: https://goo.gl/1VRrw7 - Contributions: https://goo.gl/mh7qDG --- You received this message because you are subscribed to the Google Groups "CAS Community" group. To unsubscribe from this group and stop receiving emails from it, send an email to cas-user+unsubscr...@apereo.org<mailto:cas-user+unsubscr...@apereo.org>. To view this discussion on the web visit https://groups.google.com/a/apereo.org/d/msgid/cas-user/f9d02240-df8e-4b39-80a6-3580cd380b36%40apereo.org<https://groups.google.com/a/apereo.org/d/msgid/cas-user/f9d02240-df8e-4b39-80a6-3580cd380b36%40apereo.org?utm_medium=email&utm_source=footer>. -- - Website: https://apereo.github.io/cas - Gitter Chatroom: https://gitter.im/apereo/cas - List Guidelines: https://goo.gl/1VRrw7 - Contributions: https://goo.gl/mh7qDG --- You received this message because you are subscribed to the Google Groups "CAS Community" group. To unsubscribe from this group and stop receiving emails from it, send an email to cas-user+unsubscr...@apereo.org<mailto:cas-user+unsubscr...@apereo.org>. To view this discussion on the web visit https://groups.google.com/a/apereo.org/d/msgid/cas-user/CA%2Bd9XAMVOWv9QacdbOYDBb9QA9Q4wA7AqDJN%3DLDr0dfvGHGxDQ%40mail.gmail.com<https://groups.google.com/a/apereo.org/d/msgid/cas-user/CA%2Bd9XAMVOWv9QacdbOYDBb9QA9Q4wA7AqDJN%3DLDr0dfvGHGxDQ%40mail.gmail.com?utm_medium=email&utm_source=footer>. -- - Website: https://apereo.github.io/cas - Gitter Chatroom: https://gitter.im/apereo/cas - List Guidelines: https://goo.gl/1VRrw7 - Contributions: https://goo.gl/mh7qDG --- You received this message because you are subscribed to the Google Groups "CAS Community" group. To unsubscribe from this group and stop receiving emails from it, send an email to cas-user+unsubscr...@apereo.org. To view this discussion on the web visit https://groups.google.com/a/apereo.org/d/msgid/cas-user/CO2PR0801MB6474E5AEDD311854873107383E50%40CO2PR0801MB647.namprd08.prod.outlook.com. -- - Website: https://apereo.github.io/cas - Gitter Chatroom: https://gitter.im/apereo/cas - List Guidelines: https://goo.gl/1VRrw7 - Contributions: https://goo.gl/mh7qDG --- You received this message because you are subscribed to the Google Groups "CAS Community" group. To unsubscribe from this group and stop receiving emails from it, send an email to cas-user+unsubscr...@apereo.org. To view this discussion on the web visit https://groups.google.com/a/apereo.org/d/msgid/cas-user/1193444352.408511648.1517321903321.JavaMail.zimbra%40lafayette.edu.
