ipasso/docs/auth-flow.md

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).