Update description of AUTH_*_LIFETIME options

2022-07-04 13:03:06 +02:00
parent 46e8f4d283
commit f7f18af5f4
2 changed files with 57 additions and 49 deletions
@@ -33,7 +33,7 @@

 ###############################################################################
 # Allow insecure (invalid, expired TLS/SSL certificates) connections.
-# 
+#
 # [IMPORTANT]
 # ====
 # We strongly recommend keeping this value set to false except for local development or demos.
@@ -191,7 +191,7 @@

 ###############################################################################
 # Password for the web console endpoint. When running in dev environment, password is not required.
-# 
+#
 # Corteza intentionally sets default password to random chars to prevent security incidents.
 # Type:    string
 # Default: <no value>
@@ -278,7 +278,7 @@
 # Email sending
 #
 # Configure your local SMTP server or use one of the available providers.
-# 
+#
 # These values are copied to settings when the server starts and can be managed from the administration console.
 # We recommend you remove these values after they are copied to settings.
 # If server detects difference between these options and settings, it shows a warning in the log on server start.
@@ -348,13 +348,13 @@

 ###############################################################################
 # 	Enables actionlog for compose record create, update, and delete. which is disabled by default.
-# 
+#
 # 	[IMPORTANT]
 # 	====
 # 	This is temp fix for now, it will be removed completely in future release.
 # 	Once new env var will be introduced for actionlog policy, which will enable more control over action log policies.
 # 	====
-# 
+#
 # Type:    bool
 # Default: <no value>
 # ACTIONLOG_COMPOSE_RECORD_ENABLED=<no value>
@@ -431,7 +431,7 @@

 ###############################################################################
 # Password security allows you to disable constraints to which passwords must conform to.
-# 
+#
 # [CAUTION]
 # ====
 # Disabling password security can be useful for development environments as it removes the need for complex passwords.
@@ -443,7 +443,7 @@

 ###############################################################################
 # Secret used for signing JWT tokens.
-# 
+#
 # [IMPORTANT]
 # ====
 # If secret is not set, system auto-generates one from DB_DSN and HOSTNAME environment variables.
@@ -454,20 +454,22 @@
 # AUTH_JWT_SECRET=<no value>

 ###############################################################################
-# Access token lifetime
+# Lifetime of the access token. Should be shorter than lifetime of the refresh token.
 # Type:    time.Duration
 # Default: 2h
 # AUTH_OAUTH2_ACCESS_TOKEN_LIFETIME=2h

 ###############################################################################
-# Refresh token lifetime
+# Lifetime of the refresh token. Should be much longer than lifetime of the access token.
+#
+# Refresh tokens are used to exchange expired access tokens with new ones.
 # Type:    time.Duration
 # Default: 72h
 # AUTH_OAUTH2_REFRESH_TOKEN_LIFETIME=72h

 ###############################################################################
 # Redirect URL to be sent with OAuth2 authentication request to provider
-# 
+#
 # `provider` placeholder is replaced with the actual value when used.
 # Type:    string
 # Default: <no value>
@@ -475,7 +477,7 @@

 ###############################################################################
 # Secret used for securing cookies
-# 
+#
 # [IMPORTANT]
 # ====
 # If secret is not set, system auto-generates one from DB_DSN and HOSTNAME environment variables.
@@ -518,21 +520,21 @@

 ###############################################################################
 # Maximum time user is allowed to stay idle when logged in without "remember-me" option and before session is expired.
-# 
+#
 # Recomended value is between an hour and a day.
-# 
+#
 # [IMPORTANT]
 # ====
 # This affects only profile (/auth) pages. Using applications (admin, compose, ...) does not prolong the session.
 # ====
-# 
+#
 # Type:    time.Duration
 # Default: 24h
 # AUTH_SESSION_LIFETIME=24h

 ###############################################################################
 # Duration of the session in /auth lasts when user logs-in with "remember-me" option.
-# 
+#
 # If set to 0, "remember-me" option is removed.
 # Type:    time.Duration
 # Default: 8640h
@@ -559,7 +561,7 @@

 ###############################################################################
 # Secret used for securing CSRF protection
-# 
+#
 # [IMPORTANT]
 # ====
 # If secret is not set, system auto-generates one from DB_DSN and HOSTNAME environment variables.
@@ -589,19 +591,19 @@

 ###############################################################################
 # Handle for OAuth2 client used for automatic redirect from /auth/oauth2/go endpoint.
-# 
+#
 # This simplifies configuration for OAuth2 flow for Corteza Web applications as it removes
 # the need to suply redirection URL and client ID (oauth2/go endpoint does that internally)
-# 
+#
 # Type:    string
 # Default: corteza-webapp
 # AUTH_DEFAULT_CLIENT=corteza-webapp

 ###############################################################################
 # Path to js, css, images and template source files
-# 
+#
 # When corteza starts, if path exists it tries to load template files from it.
-# 
+#
 # When empty path is set (default value), embedded files are used.
 # Type:    string
 # Default: <no value>
@@ -610,7 +612,7 @@
 ###############################################################################
 # When enabled, corteza reloads template before every execution.
 # Enable this for debugging or when developing auth templates.
-# 
+#
 # Should be disabled in production where templates do not change between server restarts.
 # Type:    bool
 # Default: <no value>
@@ -788,9 +790,9 @@
 ###############################################################################
 # List of compa delimited languages (language tags) to enable.
 # In case when an enabled language can not be loaded, error is logged.
-# 
+#
 # When loading language configurations (config.xml) from the configured path(s).
-# 
+#
 # Type:    string
 # Default: en
 # LOCALE_LANGUAGES=en
@@ -805,7 +807,7 @@
 # Name of the query string parameter used to pass the language tag (it overrides Accept-Language header).
 # Set it to empty string to disable detection from the query string.
 # This parameter is ignored if only one language is enabled
-# 
+#
 # Type:    string
 # Default: lng
 # LOCALE_QUERY_STRING_PARAM=lng
@@ -836,9 +838,9 @@

 ###############################################################################
 # Disables JSON format for logging and enables more human-readable output with colors.
-# 
+#
 # Disable for production.
-# 
+#
 # Type:    bool
 # Default: <no value>
 # LOG_DEBUG=<no value>
@@ -846,11 +848,11 @@
 ###############################################################################
 # Minimum logging level. If set to "warn",
 # Levels warn, error, dpanic panic and fatal will be logged.
-# 
+#
 # Recommended value for production: warn
-# 
+#
 # Possible values: debug, info, warn, error, dpanic, panic, fatal
-# 
+#
 # Type:    string
 # Default: warn
 # LOG_LEVEL=warn
@@ -858,25 +860,25 @@
 ###############################################################################
 # Log filtering rules by level and name (log-level:log-namespace).
 # Please note that level (LOG_LEVEL) is applied before filter and it affects the final output!
-# 
+#
 # Leave unset for production.
-# 
+#
 # Example:
 # `warn+:* *:auth,workflow.*`
 # Log warnings, errors, panic, fatals. Everything from auth and workflow is logged.
-# 
-# 
+#
+#
 # See more examples and documentation here: https://github.com/moul/zapfilter
-# 
+#
 # Type:    string
 # Default: <no value>
 # LOG_FILTER=<no value>

 ###############################################################################
 # Set to true to see where the logging was called from.
-# 
+#
 # Disable for production.
-# 
+#
 # Type:    bool
 # Default: <no value>
 # LOG_INCLUDE_CALLER=<no value>
@@ -884,9 +886,9 @@
 ###############################################################################
 # Include stack-trace when logging at a specified level or below.
 # Disable for production.
-# 
+#
 # Possible values: debug, info, warn, error, dpanic, panic, fatal
-# 
+#
 # Type:    string
 # Default: dpanic
 # LOG_STACKTRACE_LEVEL=dpanic
@@ -998,11 +1000,11 @@
 #
 # Provisioning allows you to configure a {PRODUCT_NAME} instance when deployed.
 # It occurs automatically after the {PRODUCT_NAME} server starts.
-# 
+#
 # [IMPORTANT]
 # ====
 # We recommend you to keep provisioning enabled as it simplifies version updates by updating the database and updating settings.
-# 
+#
 # If you're doing local development or some debugging, you can disable this.
 # ====
 #
@@ -1039,7 +1041,7 @@
 # ====
 # These parameters help in the development and testing process.
 # When you are deploying to production, these should be disabled to improve performance and reduce storage usage.
-# 
+#
 # You should configure external services such as Sentry or ELK to keep track of logs and error reports.
 # ====
 #
@@ -1139,7 +1141,7 @@
 # Delay system startup
 #
 # You can configure these options to defer API execution until another external (HTTP) service is up and running.
-# 
+#
 # [ TIP ]
 # ====
 # Delaying API execution can come in handy in complex setups where execution order is important.
@@ -1163,7 +1165,7 @@
 ###############################################################################
 # Space delimited list of hosts and/or URLs to probe.
 #     Host format: `host` or `host:443` (port will default to 80).
-# 
+#
 # [NOTE]
 # ====
 # Services are probed in parallel.
@@ -43,17 +43,23 @@ auth: schema.#optionsGroup & {
 			env: "AUTH_JWT_SECRET"
 		}
 		access_token_lifetime: {
-			type:        "time.Duration"
-			description: "Access token lifetime"
-			env:         "AUTH_OAUTH2_ACCESS_TOKEN_LIFETIME"
+			type: "time.Duration"
+			description: """
+				Lifetime of the access token. Should be shorter than lifetime of the refresh token.
+				"""
+			env: "AUTH_OAUTH2_ACCESS_TOKEN_LIFETIME"

 			defaultGoExpr: "time.Hour * 2"
 			defaultValue:  "2h"
 		}
 		refresh_token_lifetime: {
-			type:        "time.Duration"
-			description: "Refresh token lifetime"
-			env:         "AUTH_OAUTH2_REFRESH_TOKEN_LIFETIME"
+			type: "time.Duration"
+			description: """
+				Lifetime of the refresh token. Should be much longer than lifetime of the access token.
+
+				Refresh tokens are used to exchange expired access tokens with new ones.
+				"""
+			env: "AUTH_OAUTH2_REFRESH_TOKEN_LIFETIME"

 			defaultGoExpr: "time.Hour * 24 * 3"
 			defaultValue:  "72h"