From 04a63928e406f8593a1efe39268f1299fbb063fb Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Miroslav=20Bajto=C5=A1?= Date: Thu, 26 Jan 2017 13:27:33 +0100 Subject: [PATCH 1/4] Describe access-token invalidation --- _data/sidebars/lb2_sidebar.yml | 6 ++- pages/en/lb2/AccessToken-invalidation.md | 67 ++++++++++++++++++++++++ pages/en/lb2/Managing-users.md | 4 ++ pages/en/lb3/Managing-users.md | 15 ++++++ 4 files changed, 91 insertions(+), 1 deletion(-) create mode 100644 pages/en/lb2/AccessToken-invalidation.md diff --git a/_data/sidebars/lb2_sidebar.yml b/_data/sidebars/lb2_sidebar.yml index 8cfbe0afb..46117464e 100644 --- a/_data/sidebars/lb2_sidebar.yml +++ b/_data/sidebars/lb2_sidebar.yml @@ -208,6 +208,10 @@ children: url: /doc/en/lb2/User-management-example.html output: 'web, pdf' + - title: 'AccessToken invalidation' + url: /doc/en/lb2/AccessToken-invalidation.html + output: 'web, pdf' + - title: 'Authentication, authorization, and permissions' url: /doc/en/lb2/Authentication-authorization-and-permissions.html output: 'web, pdf' @@ -994,7 +998,7 @@ children: - title: 'Geopoint type' url: /doc/en/lb2/Geotype.html output: 'web, pdf' - + - title: 'Valid names in LoopBack' url: /doc/en/lb2/Valid-names-in-LoopBack.html output: 'web, pdf' diff --git a/pages/en/lb2/AccessToken-invalidation.md b/pages/en/lb2/AccessToken-invalidation.md new file mode 100644 index 000000000..13cc18a28 --- /dev/null +++ b/pages/en/lb2/AccessToken-invalidation.md @@ -0,0 +1,67 @@ +--- +title: "AccessToken invalidation" +lang: en +layout: page +keywords: LoopBack +tags: authentication +sidebar: lb2_sidebar +permalink: /doc/en/lb2/AccessToken-invalidation.html +summary: When a user changes their email or password, other sessions are logged out for security reasons. +--- + +When user's account is compromised, for example when their password is leaked, +or the attacker gains access to their email account, the user need means for +recovering from the situation and preventing the attacker from continued use +of the services under the attacked user's name. + +To address this case, LoopBack invalidates access tokens (logs out sessions) +when a change of password or email was detected. By default, this feature is +disabled in 2.x LTS for backwards compatibility and a warning is printed at +startup time to notify the app developer about a possible security issue. + +To enable access-token invalidation, one should set the flag +`"logoutSessionsOnSensitiveChanges`" to `true` in `server/config.json` file. + +{% include tip.html content=" +If your application implements an own solution for access-token invalidation, then set `logoutSessionsOnSensitiveChanges` to `false`, to prevent interference between the built-in invalidation and your custom solution. This will also disable the warning. However, note that this flag is not available in LoopBack 3.x. +"%} + +Example: + +```json +{ + "restApiRoot": "/api", + "host": "0.0.0.0", + "port": 3000, + "remoting": { + // ... + }, + "logoutSessionsOnSensitiveChanges": true, +} +``` + +To allow the access-token invalidation code detect and preserve the current +sessions, one has to enable context propagation via "options" argument +in the settings of your User model. This setting cannot be changed in the +built-in User model, the application must configure a custom model [extending +the built-in `User` model](Extending-built-in-models.html). + +Example of a `Customer` model extending the built-in `User` model: + +```json +{ + "name": "Customer", + "base": "User", + "idInjection": true, + "options": { + "validateUpsert": true + }, + "properties": {}, + "validations": [], + "relations": {}, + "acls": [], + "methods": {} +} +``` + + diff --git a/pages/en/lb2/Managing-users.md b/pages/en/lb2/Managing-users.md index 74f940265..22b6c1eeb 100644 --- a/pages/en/lb2/Managing-users.md +++ b/pages/en/lb2/Managing-users.md @@ -147,3 +147,7 @@ Since a model doesn't inherit ACLs from its base model, you must define ACLs for ### User realms See [Partitioning users with realms](Partitioning-users-with-realms.html). + +## Security considerations + +See [AccessToken invalidation](AccessToken-invalidation.html). diff --git a/pages/en/lb3/Managing-users.md b/pages/en/lb3/Managing-users.md index 82df442fd..6c015105e 100644 --- a/pages/en/lb3/Managing-users.md +++ b/pages/en/lb3/Managing-users.md @@ -147,3 +147,18 @@ Since a model doesn't inherit ACLs from its base model, you must define ACLs for ### User realms See [Partitioning users with realms](Partitioning-users-with-realms.html). + +## Security considerations + +When user's account is compromised, for example when their password is leaked, +or the attacker gains access to their email account, the user need means for +recovering from the situation and preventing the attacker from continued use +of the services under the attacked user's name. + +To address this case, LoopBack invalidates access tokens (logs out sessions) +when a change of password or email was detected. The access token used to +request the change (the current session) is preserved. + +{% include important.html content=" +To preserve backwards compatibility, LoopBack 2.x LTS does not enable this functionality by default, but prints a startup warning to notify the application developer about a potential security issue. See [AccessToken invalidation in LB 2.x](/doc/en/lb2/AccessToken-invalidation) for more details. +"%} From c06d7284064bb0e17dec84dcfd01526dfa5f7671 Mon Sep 17 00:00:00 2001 From: Rand McKinney Date: Thu, 26 Jan 2017 16:04:03 -0800 Subject: [PATCH 2/4] Update AccessToken-invalidation.md review edits --- pages/en/lb2/AccessToken-invalidation.md | 25 ++++++++++++------------ 1 file changed, 12 insertions(+), 13 deletions(-) diff --git a/pages/en/lb2/AccessToken-invalidation.md b/pages/en/lb2/AccessToken-invalidation.md index 13cc18a28..8e49e3d4d 100644 --- a/pages/en/lb2/AccessToken-invalidation.md +++ b/pages/en/lb2/AccessToken-invalidation.md @@ -1,5 +1,5 @@ --- -title: "AccessToken invalidation" +title: "Access token invalidation" lang: en layout: page keywords: LoopBack @@ -9,21 +9,20 @@ permalink: /doc/en/lb2/AccessToken-invalidation.html summary: When a user changes their email or password, other sessions are logged out for security reasons. --- -When user's account is compromised, for example when their password is leaked, -or the attacker gains access to their email account, the user need means for -recovering from the situation and preventing the attacker from continued use -of the services under the attacked user's name. +When a user's account is compromised (for example their password is leaked or +an attacker gains access to their email account), the app needs to be able to +prevent continued use of the hijacked account. To address this case, LoopBack invalidates access tokens (logs out sessions) when a change of password or email was detected. By default, this feature is disabled in 2.x LTS for backwards compatibility and a warning is printed at startup time to notify the app developer about a possible security issue. -To enable access-token invalidation, one should set the flag -`"logoutSessionsOnSensitiveChanges`" to `true` in `server/config.json` file. +To enable access-token invalidation, set the flag +`logoutSessionsOnSensitiveChanges` to `true` in the `server/config.json` file. {% include tip.html content=" -If your application implements an own solution for access-token invalidation, then set `logoutSessionsOnSensitiveChanges` to `false`, to prevent interference between the built-in invalidation and your custom solution. This will also disable the warning. However, note that this flag is not available in LoopBack 3.x. +If your application implements access-token invalidation itself, then set `logoutSessionsOnSensitiveChanges` to `false`, to prevent interference between the built-in invalidation and your custom solution. This will also disable the warning. This flag is not available in LoopBack 3.x. "%} Example: @@ -40,11 +39,11 @@ Example: } ``` -To allow the access-token invalidation code detect and preserve the current -sessions, one has to enable context propagation via "options" argument -in the settings of your User model. This setting cannot be changed in the -built-in User model, the application must configure a custom model [extending -the built-in `User` model](Extending-built-in-models.html). +To allow the access-token invalidation code to detect and preserve current sessions, +enable context propagation via the "options" argument +in the settings of your User model. You can't change this setting in the +built-in User model. Instead, configure a custom model that +[extends the built-in User model](Extending-built-in-models.html). Example of a `Customer` model extending the built-in `User` model: From c9ec2e36bf0fac80b66c0debd1cc02cfaec64726 Mon Sep 17 00:00:00 2001 From: Rand McKinney Date: Thu, 26 Jan 2017 16:04:56 -0800 Subject: [PATCH 3/4] Update Managing-users.md review edits. --- pages/en/lb2/Managing-users.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/pages/en/lb2/Managing-users.md b/pages/en/lb2/Managing-users.md index 22b6c1eeb..6007f805a 100644 --- a/pages/en/lb2/Managing-users.md +++ b/pages/en/lb2/Managing-users.md @@ -150,4 +150,4 @@ See [Partitioning users with realms](Partitioning-users-with-realms.html). ## Security considerations -See [AccessToken invalidation](AccessToken-invalidation.html). +See [Access token invalidation](AccessToken-invalidation.html). From 2e14f11ce03ee4e734d717e2579f74d872802c5b Mon Sep 17 00:00:00 2001 From: Rand McKinney Date: Thu, 26 Jan 2017 16:06:21 -0800 Subject: [PATCH 4/4] Update Managing-users.md review edits. --- pages/en/lb3/Managing-users.md | 8 +++----- 1 file changed, 3 insertions(+), 5 deletions(-) diff --git a/pages/en/lb3/Managing-users.md b/pages/en/lb3/Managing-users.md index 6c015105e..453885ac7 100644 --- a/pages/en/lb3/Managing-users.md +++ b/pages/en/lb3/Managing-users.md @@ -150,13 +150,11 @@ See [Partitioning users with realms](Partitioning-users-with-realms.html). ## Security considerations -When user's account is compromised, for example when their password is leaked, -or the attacker gains access to their email account, the user need means for -recovering from the situation and preventing the attacker from continued use -of the services under the attacked user's name. +When a user's account is compromised (for example their password is leaked or the attacker gains +access to their email account), the app needs to be able to prevent continued use of the hijacked account. To address this case, LoopBack invalidates access tokens (logs out sessions) -when a change of password or email was detected. The access token used to +when a change of password or email is detected. The access token used to request the change (the current session) is preserved. {% include important.html content="