From 80d0943d9d1c0fb20ceb5236dad7ee672b6dc522 Mon Sep 17 00:00:00 2001 From: Marcus Efraimsson Date: Tue, 5 Feb 2019 21:10:56 +0100 Subject: [PATCH] document login, short-lived tokens and secure cookie configurations --- docs/sources/auth/overview.md | 32 ++++++++++++++++++++++ docs/sources/installation/configuration.md | 8 ++++++ 2 files changed, 40 insertions(+) diff --git a/docs/sources/auth/overview.md b/docs/sources/auth/overview.md index 0480ee88adc..e3d4c08ca5d 100644 --- a/docs/sources/auth/overview.md +++ b/docs/sources/auth/overview.md @@ -36,6 +36,38 @@ Grafana of course has a built in user authentication system with password authen disable authentication by enabling anonymous access. You can also hide login form and only allow login through an auth provider (listed above). There is also options for allowing self sign up. +### Login and short-lived tokens + +> The followung applies when using Grafana's built in user authentication, LDAP (without Auth proxy) or OAuth integration. + +Grafana are using short-lived tokens as a mechanism for verifying authenticated users. +These short-lived tokens are rotated each `token_rotation_interval_minutes` for an active authenticated user. + +An active authenticated user that gets it token rotated will extend the `login_maximum_inactive_lifetime_days` time from "now" that Grafana will remember the user. +This means that a user can close its browser and come back before `now + login_maximum_inactive_lifetime_days` and still being authenticated. + This is true as long as the time since user login is less than `login_maximum_lifetime_days`. + +Example: + +```bash +[auth] + +# Login cookie name +login_cookie_name = grafana_session + +# The lifetime (days) an authenticated user can be inactive before being required to login at next visit. Default is 7 days. +login_maximum_inactive_lifetime_days = 7 + +# The maximum lifetime (days) an autenticated user can be logged in since login time before being required to login. Default is 30 days. +login_maximum_lifetime_days = 30 + +# How often should auth tokens be rotated for authenticated users when being active. The default is each 10 minutes. +token_rotation_interval_minutes = 10 + +# How often should expired auth tokens be deleted from the database. The default is 7 days. +expired_tokens_cleanup_interval_days = 7 +``` + ### Anonymous authentication You can make Grafana accessible without any login required by enabling anonymous access in the configuration file. diff --git a/docs/sources/installation/configuration.md b/docs/sources/installation/configuration.md index 46bab83654e..b4b53d7557b 100644 --- a/docs/sources/installation/configuration.md +++ b/docs/sources/installation/configuration.md @@ -287,6 +287,14 @@ Default is `false`. Define a white list of allowed ips/domains to use in data sources. Format: `ip_or_domain:port` separated by spaces +### cookie_secure + +Set to `true` if you host Grafana behind HTTPS. Default is `false`. + +### cookie_samesite + +Sets the `SameSite` cookie attribute and prevents the browser from sending this cookie along with cross-site requests. The main goal is mitigate the risk of cross-origin information leakage. It also provides some protection against cross-site request forgery attacks (CSRF), [read more here](https://www.owasp.org/index.php/SameSite). Valid values are `lax`, `strict` and `none`. Default is `lax`. +
## [users]