website/docs: adds information about known device logins

website/docs/add-secure-apps/flows-stages/stages/user_login/index.md

@@ -1,5 +1,6 @@
 ---
 title: User Login stage
+toc_max_heading_level: 4
 ---
 
 The User Login stage attaches a currently pending user to the current session.
@@ -8,19 +9,18 @@ It can be used after `user_write` during an enrollment flow, or after a `passwor
 
 ## User login stage configuration options
 
-When creating or editing this stage in the UI of the Admin interface, you can set the following configuration options.
+When creating or editing this stage in the Admin interface, you can define configuration options using the following fields.
 
-**Name**: enter a descriptive name for the stage.
+#### Session duration
 
-**Stage-specific settings**
-
-- **Session duration**: By default, the authentik session expires when you close your browser (_seconds=0_).
+By default, the authentik session expires when you close your browser (_seconds=0_). Use the **Session duration** field to define a custom session length.
 
     :::warning
     Different browsers handle session cookies differently, and might not remove them even when the browser is closed. See [here](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Set-Cookie#expiresdate) for more info.
     :::
 
-    You can set the session to expire after any duration using the syntax of `hours=1,minutes=2,seconds=3`. The following keys are allowed:
+You can set the session to expire after any duration using the syntax of `hours=1,minutes=2,seconds=3`. The following keys are allowed:
+
     - Microseconds
     - Milliseconds
     - Seconds
@@ -29,55 +29,63 @@ When creating or editing this stage in the UI of the Admin interface, you can se
     - Days
     - Weeks
 
-    All values accept floating-point values.
+All values accept floating-point values.
+
+#### Stay signed in offset
 
-- **Stay signed in offset**: When this is set to a higher value than the default _seconds=0_, the user logging in is shown a prompt, allowing the user to choose if their session should be extended or not. The same syntax as for _Session duration_ applies.
+When the value in **Stay signed in offset** is set to a higher value than the default _seconds=0_, the user logging in is shown a prompt, allowing the user to choose if their session should be extended or not. The same syntax as for **Session duration** applies.
 
     ![](./stay_signed_in.png)
 
-- **Network binding and GeoIP binding**
+#### Remember device
+
+If set to a duration above 0, a cookie is stored for the duration specified that informs authentik whether the user is signing in from a known or unknown (new) device.
+
+If there's an existing authenticated user session for the user with the same IP address, authentik also classifies this as a known device. See [here](../../../../sys-mgmt/events/notification_rule_expression_policies.mdx#trigger-alert-when-user-logs-in-from-unknown-device) for an example of how an alert can be configured for logins from unknown devices.
+
+#### Network binding and GeoIP binding
 
-    When configured, all sessions authenticated by this stage will be bound to the selected network and/or GeoIP criteria.
+When configured, all sessions authenticated by this stage will be bound to the selected network and/or GeoIP criteria.
 
-    Sessions that break this binding will be terminated on use. The created [`logout`](../../../../sys-mgmt/events/event-actions#logout) event will contain additional data related to what caused the binding to be broken:
+Sessions that break this binding will be terminated. The created [`logout`](../../../../sys-mgmt/events/event-actions#logout) event will contain additional data related to what caused the binding to be broken:
 
-    ```json
-    {
-        "asn": {
+```json
+{
+    "asn": {
+        "asn": 6805,
+        "as_org": "Telefonica Germany",
+        "network": "5.4.0.0/14"
+    },
+    "geo": {
+        "lat": 51.2993,
+        "city": "",
+        "long": 9.491,
+        "country": "DE",
+        "continent": "EU"
+    },
+    "binding": {
+        "reason": "network.missing",
+        "new_value": {
             "asn": 6805,
             "as_org": "Telefonica Germany",
             "network": "5.4.0.0/14"
         },
-        "geo": {
-            "lat": 51.2993,
-            "city": "",
-            "long": 9.491,
-            "country": "DE",
-            "continent": "EU"
-        },
-        "binding": {
-            "reason": "network.missing",
-            "new_value": {
-                "asn": 6805,
-                "as_org": "Telefonica Germany",
-                "network": "5.4.0.0/14"
-            },
-            "previous_value": {}
-        },
-        "ip": {
-            "previous": "1.2.3.4",
-            "new": "5.6.7.8"
-        },
-        "http_request": {
-            "args": {},
-            "path": "/if/admin/",
-            "method": "GET",
-            "user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/120.0.0.0 Safari/537.36"
-        },
-        "logout_reason": "Session binding broken"
-    }
-    ```
-
-- **Terminate other sessions**
-
-    When enabled, previous sessions of the user logging in will be revoked. This has no affect on OAuth refresh tokens.
+        "previous_value": {}
+    },
+    "ip": {
+        "previous": "1.2.3.4",
+        "new": "5.6.7.8"
+    },
+    "http_request": {
+        "args": {},
+        "path": "/if/admin/",
+        "method": "GET",
+        "user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/120.0.0.0 Safari/537.36"
+    },
+    "logout_reason": "Session binding broken"
+}
+```
+
+#### Terminate other sessions
+
+When enabled, previous sessions of the same user are revoked. This has no affect on OAuth refresh tokens.

website/docs/sys-mgmt/events/notification_rule_expression_policies.mdx

@@ -2,13 +2,38 @@
 title: Notification Rule Expression Policies
 ---
 
-## Introduction
+[Notification rules](./notifications.md) with [bound expression policies](./notifications.md#3-create-a-notification-rule-and-bind-it-to-the-policy) are very powerful. The following are examples of what can be achieved.
 
-Notification rules with bound expression policies are very powerful. The following are examples of what can be achieved.
+### Trigger alert when user logs in from unknown device
+
+This expression policy is triggered when a user logs in from an unknown device. This can be combined with a notification rule to alert administrators, or the user in question if `Send notification to event user` is enabled on the notification rule.
+
+```python
+# Check if an event has occurred
+event = request.context.get("event", None)
+if not event:
+    ak_logger.info("no event")
+    return False
+
+# Check if the event action includes updating a model
+if event.action != "login":
+    ak_logger.info("event action does not match")
+    return False
+
+# Get the known device status
+known_device = event.context["auth_method_args"]["known_device"]
+
+# Alert if device is unknown
+if known_device == False:
+  ak_logger.info("User logged in from unknown device")
+  return True
+else:
+  return False
+```
 
 ### Change user attributes upon account deactivation
 
-This example code is triggered when a user account with the `sshPublicKey` attribute set is deactivated. It saves the `sshPublicKey` attribute to a new `inactivesshPublicKey` attribute, and subsequently nullifies the `sshPublicKey` attribute.
+This expression policy is triggered when a user account with the `sshPublicKey` attribute set is deactivated. It saves the `sshPublicKey` attribute to a new `inactivesshPublicKey` attribute, and subsequently nullifies the `sshPublicKey` attribute.
 
 ```python
 from authentik.core.models import User
@@ -63,7 +88,7 @@ return False
 
 ### Alert when application is created without binding
 
-This code is triggered when a new application is created without any user, group, or policy bound to it. The notification rule can then be configured to alert an administrator. This feature is useful for ensuring limited access to applications, as by default, an application without any users, groups, or policies bound to it can be accessed by all users.
+This expression policy is triggered when a new application is created without any user, group, or policy bound to it. The notification rule can then be configured to alert an administrator. This feature is useful for ensuring limited access to applications, because by default an application without any users, groups, or policies bound to it can be accessed by all users.
 
 ```python
 from authentik.core.models import Application
@@ -106,7 +131,7 @@ return False
 
 ### Append user addition history to group attributes
 
-This code is triggered when a user is added to a group. It then creates and updates a `UserAddedHistory` attribute to the group with a date/time stamp and the username of the added user. This functionality is already available within the changelog of a group, but this code can be used as a template to trigger alerts or other events.
+This expression policy is triggered when a user is added to a group. The policy then creates and updates a `UserAddedHistory` attribute to the group with a date/time stamp and the username of the added user. This functionality is already available within the changelog of a group, but this code can be used as a template to trigger alerts or other events.
 
 :::info
 This policy interacts with the `diff` event output. This field is only available with an enterprise license.