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.