Jan, I think that part of the issue is that there are different types of documentation, and while the CAS project has good coverage for some types, it doesn't have spectacular coverage with other types. One of the most interesting talks I heard on the subject of documentation was from the PyCon 2017 series:
https://www.youtube.com/watch?v=azf6yzuJt54 In summary, the speaker identifies 4 types of documentation: * Tutorials * HOWTOs * Reference * Discussion I think the CAS project is pretty strong on Reference material, it is OK on HOWTOs, but it is somewhat lackluster with regards to tutorials and discussion. A great tutorial would be a real asset to getting newcomers over the initial CAS hurdle. The project is more or less volunteer and sponsorship based. That means if no one volunteers to write documentation or pays someone else to write it, it isn't going to get done. The good news is that the CAS project is very open to pull requests, so if you can write up a HOWTO or tutorial, you can probably get it included in the project documentation. Thanks, Carl Waldbieser ITS Identity Management Lafayette College ----- Original Message ----- From: "Jan" <jan.zankow...@gmail.com> To: "cas-user" <cas-user@apereo.org> Sent: Monday, October 30, 2017 9:50:42 AM Subject: [cas-user] CAS documentation for a new user is terrible 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: 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. To view this discussion on the web visit https://groups.google.com/a/apereo.org/d/msgid/cas-user/0d6365c9-ce06-496a-b53d-6702ec1f0551%40apereo.org. -- - 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/1735563809.28966525.1509380451172.JavaMail.zimbra%40lafayette.edu.
