Describe access-token invalidation

_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'

pages/en/lb2/AccessToken-invalidation.md

@@ -0,0 +1,66 @@
+---
+title: "Access token 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 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, set the flag
+`logoutSessionsOnSensitiveChanges` to `true` in the `server/config.json` file.
+
+{% include tip.html content="
+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:
+
+```json
+{
+  "restApiRoot": "/api",
+  "host": "0.0.0.0",
+  "port": 3000,
+  "remoting": {
+    // ...
+  },
+  "logoutSessionsOnSensitiveChanges": true,
+}
+```
+
+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:
+
+```json
+{
+  "name": "Customer",
+  "base": "User",
+  "idInjection": true,
+  "options": {
+    "validateUpsert": true
+  },
+  "properties": {},
+  "validations": [],
+  "relations": {},
+  "acls": [],
+  "methods": {}
+}
+```
+
+

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 [Access token invalidation](AccessToken-invalidation.html).

pages/en/lb3/Managing-users.md

@@ -147,3 +147,16 @@ 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 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 is 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.
+"%}