docs/8.0/ayanova/docs/ops-config-environment-variables.md

@@ -25,6 +25,7 @@ These values can all be specified as an environment variable or as a command lin
 
 ## API
 
+- [AYANOVA_JWT_SECRET](ops-config-jwt-secret.md)
 - [AYANOVA_USE_URLS](ops-config-use-urls.md)
 - [AYANOVA_FOLDER_USER_FILES](ops-config-folder-user-files.md)
 - [AYANOVA_FOLDER_BACKUP_FILES](ops-config-folder-backup-files.md)

docs/8.0/ayanova/docs/ops-config-jwt-secret.md

@@ -0,0 +1,44 @@
+# JWT secret setting
+
+AyaNova uses JSON Web Tokens (JWT) for authentication.
+
+These time limited tokens are signed by the server using a secret key and issued to users when they log in to the AyaNova server.
+Every time the user makes a request to the server the JWT is sent along as well and verified to be valid.
+
+Tokens have a built in expiry mechanism to force users to re-login at periodic intervals in the range of days to weeks.
+
+Users can be prevented from logging in even if they have a valid token by setting them to inactive.
+
+## Default
+
+If no secret key is specified the server will generate a new, random one each time it starts and this means that remote users who previously authenticated will need to login freshly if the server is restarted.
+
+If you would like to ensure that a server reboot does not affect remote users credentials then you can specify a value for the secret key so that the same key will always be used by the server even if it reboots.
+
+## Overriding
+
+AyaNova expects the JWT secret to be provided by an environment variable or command line parameter named
+
+`AYANOVA_JWT_SECRET`
+
+The value specified should be a string of up to 32 characters, for example:
+`02847This_is_my_secret_key456576`
+If fewer than 32 characters are provided they secret will be padded out to 32 characters.  If more than 32 characters are specified it will only use the first 32.
+
+You should use the same precautions as for choosing any other password and ensure the secret is not well known or easily looked up in a dictionary.  32 random characters would be sufficient.
+
+Example command line parameter
+
+`dotnet run --AYANOVA_JWT_SECRET="02847This_is_my_secret_key456576"`
+
+Example environment variable
+
+Windows
+
+`set "AYANOVA_JWT_SECRET=02847This_is_my_secret_key456576"`
+
+Linux / MAC
+
+`export AYANOVA_JWT_SECRET="02847This_is_my_secret_key456576"`
+
+If both a command line parameter and an environment variable are set the command line parameter takes precedence.