Authentication
==============

Inside Movens, users are authenticated by means of JWT, exchanged as a compressed
string between the server and the client.

Issued JWTs are time-limited, with a configurable timeout but usually lasting a couple
of days. The expiration date is indicated inside the JWT itself.

Implementations using Movens-issued JWT should update their token by calling the
appropriate API endpoint, depending on the API that was used to get the token in
the first place.

Once a JWT has been used to ask the server for an update, that JWT cannot be reused
for the same purpose, and will naturally expire in the configured time.

The JWT is signed by the server, using a secret key derived from a configuration
parameter. Inside the JWT is a list containing the roles for the authenticated
user, as slug strings, that can be used to hide certain UI features to enhance
the UX. Proper user authorization is checked, server-side, on the JWT itself.

Responses may have an additional ``Authorization`` header, with a ``Bearer`` value
followed by a new token. User Agents accessing the APIs can store that value and use
it for subsequent requests, because the old one is nearing expiration. After the token
expires, User Agents will receive an HTTP error of 401.

Getting a JWT
-------------

This is usually accomplished by calling the appropriate API endpoint with the
required parameters (typically, username and password).

Using a JWT
-----------

In most cases of API usage, the JWT must be passed as an ``Authorization: Bearer``
type HTTP header.

JWT Contents
------------
::

  {
    "mv-lcid": "127",
    "mv-name": "Administrator",
    "mv-uid": "1",
    "mv-guid": "8de10b8d-0ad5-452e-94a8-ae7470894472",
    "mv-renew": "RIPJOXVQNPGXPEWLLZQFQFFXUCRDHKKX",
    "mv-comm": "2e94fb9a-83bb-4f8a-badb-a5edd5cbe919",
    "mv-role": "Admin",
    "exp": 1565335251,
    "iss": "Movens",
    "aud": "Movens Users"
  }

Some of the JWT fields are standard token metadata, like ``aud`` for Audience,
``exp`` for validity expiration, ``iss`` for issuer.

Other fields are relevant to the Movens platform:

========= ========
Name      Meaning
========= ========
mv-name   User Name
mv-uid    User Id - numeric. Try not to use this in the UI. It helps speed up some server-side operations.
mv-guid   User Id - Guid. This can be safely used to identify the user in the UI.
mv-lcid   LCID of the preferred culture of the user.
mv-role   String, or array of strings, with roles (as slugs) enabled for this user.
mv-comm   String, or array of strings, with community GUIDs that are linked to this user.
          Users with an ``Admin`` role can be linked to communities, but can always manage all communities
          in the system regardless of linking.
mv-renew  String with a random value, to chain JWT renew operations and avoid reusing of an old JWT.
========= ========