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..8e49e3d4d --- /dev/null +++ b/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": {} +} +``` + + diff --git a/pages/en/lb2/Managing-users.md b/pages/en/lb2/Managing-users.md index 74f940265..6007f805a 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 [Access token invalidation](AccessToken-invalidation.html). diff --git a/pages/en/lb3/Managing-users.md b/pages/en/lb3/Managing-users.md index 82df442fd..453885ac7 100644 --- a/pages/en/lb3/Managing-users.md +++ b/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. +"%}