Merge pull request #3 from adamdruppe/master

flow explanation

Author: sadleb

README.md

@@ -6,7 +6,17 @@ The file lib/casserver/views/layout.erb has the login layout html. This is based
 
 The public/ folder has image and css assets brought off the main site. These are simply downloaded from the production site and renamed - to do this, load the beyondz.org site in your browser, view source and find the link rel=styleshet near the top. Download that file and save it in here as public/beyondz.css. They do NOT need to be maintained separately at this time. Currently required are the logo, favicon, and stylesheet.
 
-The file lib/beyondz.rb holds our authenticator. It uses a cooperative check_credentials http api on the platform to check against the main database. It is configured via config.yml for server (string), port (integer), ssl (boolean), and allow_self_signed (boolean) to know where to connect. The default ssl options is production-ready - it will verify certificates and use SSL. For development purposes, you may turn these options off with ssl: false.
+The file lib/beyondz.rb holds our authenticator. It uses a cooperative check_credentials http api on the public site to check against the main database. It is configured via config.yml for server (string), port (integer), ssl (boolean), and allow_self_signed (boolean) to know where to connect. The default ssl options is production-ready - it will verify certificates and use SSL. For development purposes, you may turn these options off with ssl: false.
+
+## End user flow
+
+The end user should always go to the service they want to use (portal.beyondz.org for example). The service then redirects them to the single sign on server, with a service parameter telling it to redirect them back once login is complete.
+
+user goes to canvas -> canvas sends them to sso -> sso sends back to canvas
+
+On the backend, the SSO server talks to the public site server and the service (canvas) server talks to the SSO server to validate login tickets. This should be SSL secured in production so the sso and canvas servers both need working client certificates, and the sso and public site servers need to be running https.
+
+The user master record is stored on the public site. User records also need to exist on the service - so a bz.org and canvas user need to exist with the same email address for the login to succeed end to end.
 
 ## Copyright
 

config/config.example.yml

@@ -18,8 +18,9 @@
 # The following are example configurations for each of these three methods:
 #
 
-# This is the domain of the main platform website
-platform_domain: beyondz.org
+# This is the domain of the main public website
+# It is used by the view to generate links back to the rest of the site on the login form.
+public_site_domain: beyondz.org
 
 ###
 ### WEBrick example

lib/casserver/server.rb

@@ -278,7 +278,7 @@ def self.init_database!
       content_type :html, 'charset' => 'utf-8'
       @theme = settings.config[:theme]
       @organization = settings.config[:organization]
-      @domain = settings.config[:platform_domain]
+      @domain = settings.config[:public_site_domain]
       @uri_path = settings.config[:uri_path]
       @infoline = settings.config[:infoline]
       @custom_views = settings.config[:custom_views]