Authentication
Each client needs to authenticate in order to interact with the server[^ping] using root's user
password. Agama relies on PAM to perform the
authentication.
On successful authentication, the server generates a [JSON Web Token (RFC 7519)][jwt] that the client will include in the subsequent requests. The web client stores the token in an HTTP-only cookie[^http-only] and the CLI uses a file with restricted permissions.
JSON Web Tokens
Agama's JSON Web Token carries just a single claim: the expiration date. The token's lifetime is
currently set to just one day[^lifetime]. To generate the token, Agama requires a secret key that
can be specified using the jwt_secret configuration option in /etc/agama.d/server.yml. If no key
is specified, Agama will generate a random 30 characters string as key[^rand].
generated tokens become invalid. So if you are doing some development work, you might be interested on setting a key. :::
Skipping the authentication
When using Agama locally (e.g., in the installation medium), it would be unpleasant to ask for a
password. For that reason, Agama creates and stores a token on the file system (/run/agama/token)
that any client can use for authentication. Obviously, the file is protected and it is readable only
for the root user.
Therefore, the command-line interface, when ran as root, can use that token to authenticate each
request.
However, the web interface does not have access to the token, so it needs some magic to inject the
token into the browser. Agama's HTTP server implements an end-point that allows to authenticate
using a valid token1. So Agama's
startup script
injects the URL, including the token, as browser.startup.homepage in
Firefox's preferences.