StaticDeploy can authenticate users using JWTs. In order to
enable this authentication strategy, it's sufficient to pass a
JWT_SECRET_OR_PUBLIC_KEY environment variable when starting the
service. The variable has to contain the base64-encoded secret (for symmetric
signatures) or public key (for asymmetric signatures) that is used to sign JWTs.
JWTs MUST contain the
sub claims, used by StaticDeploy to find
the user object corresponding to the token. (The user object is used to enforce
authorization, see the docs on
authentication and authorization
Once the user got ahold of an authentication token, they can either use it with
the StaticDeploy Management Console, setting it into the Login with JWT mask,
or with the StaticDeploy CLI, passing it as the
This strategy is mainly intended to allow a StaticDeploy administrator to play
the role of an identity provider: the admin starts StaticDeploy with a given
JWT_SECRET_OR_PUBLIC_KEY, which they then also use to manually generate JWTs
for themselves and other users.
Issuing JWTs in such a way is useful in a few cases, described below.
On first deploy, issue a JWT for the
When we start StaticDeploy with an empty database, StaticDeploy creates a first
root user, that can do everything. This user has
idp = $MANAGEMENT_HOSTNAME
(the configuration env variable), and
idpId = root. By manually generating a
iss = $MANAGEMENT_HOSTNAME and
sub = root, we can then login as the
root user (and do things, like creating other users or adding users to groups).
Issue JWTs for "machine" users
When using StaticDeploy, we'll probably want to do certain operations (e.g. creating bundles) from automated environments, like CI servers. StaticDeploy doesn't support API keys to log in from such environments, but it instead supports using "machine users".
We can create a machine user from the Management Console, assigning it an
idpId (preferably randomly generated), and a
name to identify it. We can
then manually generate a JWT for that user, that we can use in our automated
environments. If we want to revoke that JWT, we just delete and re-create the
machine user, using the same
name, but a different
idpId, so that the JWT
won't work anymore.