authenticationService

The authenticationService provides several endpoints to manage user identity and authentication. These are:

  • POST /login: logs the user in. The body of the request is a JSON object with two properties:
    • email: the user's email
    • password: the password to log in with.
  • GET /user: If a user is logged in, returns their user record as a JSON object. Otherwise returns a 401 Unauthorized.
  • POST /impersonate/myemail@myhost.com/with-roles: allows the current user to change their identity to that of another user (whose email is supplied) with equal or lesser roles, given that the user has a role listed in the impersonateRoles configuration property. If the url includes the final path segment with-roles, the impersonated user has that user's roles, otherwise they keep the roles of the original user.

The GET /user request returns a special field, expiry, which is when the current login token will expire as the number of milliseconds since the Unix epoch, i.e. the output of the Javascript getTime() function. This can be used on the front end to sign out and show a login page just after this time in order to avoid calls to Restspace APIs failing.

The authenticationService has these special configuration properties:

  • userUrlPattern: This is a url pattern which can only have the substitution code ${email} within it. It determines the url where the authenticationService can read the JSON for a user record. Normally this will be in the paths space of a userService.
  • impersonateRoles: described above. A role list in the same format as the standard readRoles and writeRoles.
  • loginPage: define the page containing a login form as described below.

The authentication service supports standard HTML login form POST authentication by responding with a redirect back to the url of the form with an added query string argument result=succeed or result=fail as appropriate (so as to allow an appropriate message to be displayed). It also supports the scenario where protected pages redirect to the login page with a query string argument like redirect=/original-page. In this case, a successful login is responded to with a redirect to /original-page, returning the user to the page they originally requested but were blocked from accessing. These behaviours are turned on by supplying the special configuration property loginPage set to the path of the page containing the login form. 

Currently authentication only works by setting a cookie (rs-auth) on the client's browser which contains a JWT. The JWT expires in 8 hours.