Initial commit

docs/auth-flow.md

@@ -0,0 +1,58 @@
+# Authorization flow
+
+Current authorization state is passwd around via a signed cookie containing authorization details in JSON.
+
+Most pages do not have any form of authorization, and simply depend on the cookie.
+However, in order to log in, more complex flow is necessary.
+
+Login pages are all grouped under `/login`, which normally serves an HTML form with some additional javascript.
+This form includes a hidden field with the page to redirect to.
+The JS on `/login` begins by fetching `/login/status` via XHR GET.
+`/login/status` returns a JSON response indicating the login state, which is one of:
+* VALID: User is fully logged in. User details are attached
+* EXPLICIT_LOGOUT: Cookie is set to indicate logged-out state.
+* UNKNOWN: No cookie set
+* INVALID: Invalid signature on cookie, cookie content invalid, or cookie expired. This also clears the cookie.
+
+If the state is `UNKNOWN` or `INVALID`, automatic login is performed.
+If the state is `EXPLICIT_LOGOUT`, the process terminates here.
+Otherwise, a login form is displayed.
+
+If automatic login fails, the page simply displays a login form. 
+The user may log in using a username/password, at which point a cookie is set with their details.
+The user may also submit the form with blank username/password, in which case automatic login is performed.
+
+# Automatic login
+These steps are performed in sequence, each returning the same data as `/login/status`.
+The process completes when the state is `VALID` or `EXPLICIT_LOGOUT`.
+
+1. Fetch `/login/spnego` via XHR GET.
+2. Fetch `/login/x509` via XHR GET.
+
+ Upon successful login, a redirect is performed to the page in the hidden field.
+ 
+# API
+
+In addition to the `/login` endpoint, there exist several other useful endpoints:
+
+* `/logout`: Set cookie to indicate logged-out state
+* `/status`: Fetch a representation of user's info.
+   If `Accept` requests `application/json`, this is JSON. 
+   Otherwise, this is an HTML page
+* `/sigkey`: Fetch the current signing key. This is an Ed25519 key.
+* `/refresh`: Refresh the user data cookie given the refresh token. 
+
+# Two cookies
+
+In the above description, the login token was described as a single cookie.
+It is, in fact, two cookies:
+* A short-lived (~seconds) user data cookie
+* A longer-lived (~8 hour) refresh token, tied to an auth server
+
+If the user data cookie expires, the refresh token can be fed to `/refresh` to update the user data cookie.
+The purpose of the user data cookie is solely to reduce the load on the SSO server; the resources fetched by a page will
+  generally be fetched within a few seconds of the initial request.
+It is the reverse proxy's responsibility to refresh the user data cookie and translate it into headers or FCGI environment variables for the backend server.
+This task can be assisted by ipasso-rpxagentd (to be specified).
+
+