From f7f18af5f46686337446adea192a4dc1a21810cb Mon Sep 17 00:00:00 2001 From: Denis Arh Date: Thu, 19 May 2022 14:28:12 +0200 Subject: [PATCH] Update description of AUTH_*_LIFETIME options --- .env.example | 88 ++++++++++++++++++++++---------------------- app/options/auth.cue | 18 ++++++--- 2 files changed, 57 insertions(+), 49 deletions(-) diff --git a/.env.example b/.env.example index 570fdcf8b..7864b949e 100644 --- a/.env.example +++ b/.env.example @@ -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: @@ -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: # ACTIONLOG_COMPOSE_RECORD_ENABLED= @@ -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= ############################################################################### -# 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: @@ -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: @@ -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: @@ -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: # LOG_DEBUG= @@ -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: # LOG_FILTER= ############################################################################### # Set to true to see where the logging was called from. -# +# # Disable for production. -# +# # Type: bool # Default: # LOG_INCLUDE_CALLER= @@ -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. diff --git a/app/options/auth.cue b/app/options/auth.cue index adbcb3fd5..9567afc20 100644 --- a/app/options/auth.cue +++ b/app/options/auth.cue @@ -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"