fix(docs): Add user object and roles docs.

packages/docs/concepts/context-and-state.yaml

@@ -71,6 +71,8 @@ _ref:
 
             - [`_media`](/_media): The `media` object contains some information about the client screen size etc. This is useful in order to add additional responsive logic to a page.
 
+            - [`_user`](/user-object): The `user` object contains the data in the user idToken if OpenID Connect authentication is configured and a user is logged in.
+
       - _ref:
           path: templates/navigation_buttons.yaml
           vars:

packages/docs/concepts/lowdefy-schema.yaml

@@ -58,6 +58,8 @@ _ref:
 
             More than one menu can be configured in an app. As an example, this can be used when two logically different sections in the app need different menus.
 
+            If OpenID Connect authentication and role based authentication is configured, pages that the user is restricted from seeing are filtered from the menu object.
+
             The schema for a menu object is:
 
             - `id: string`: __Required__ - A identifier for the menu. If it is `default`, it will be used as default by pages.

packages/docs/menus.yaml

@@ -150,6 +150,11 @@
           pageId: user-object
           properties:
             title: User object
+        - id: roles
+          type: MenuLink
+          pageId: roles
+          properties:
+            title: Roles
 
     - id: blocks_input
       type: MenuGroup

packages/docs/pages.yaml

@@ -30,6 +30,7 @@
 - _ref: users/login-and-logout.yaml
 - _ref: users/protected-pages.yaml
 - _ref: users/user-object.yaml
+- _ref: users/roles.yaml
 
 - _ref: blocks/input/AutoComplete.yaml
 - _ref: blocks/input/ButtonSelector.yaml

packages/docs/users/roles.yaml

@@ -0,0 +1,71 @@
+# Copyright 2020-2021 Lowdefy, Inc
+
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+
+#     http://www.apache.org/licenses/LICENSE-2.0
+
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+_ref:
+  path: templates/general.yaml.njk
+  vars:
+    pageId: roles
+    pageTitle: Roles
+    section: User Authentication
+    filePath: concepts/roles.yaml
+    content:
+      - id: introduction
+        type: MarkdownWithCode
+        properties:
+          content: |
+            Roles can be used to limit user access to certain pages. Only users with the role will be able to see the page, and the page will be filtered from menus if the user does not have the role.
+
+            Roles can be read from a custom claim on the OpenID Connect `idToken`. This should be an array of strings which are the role names. This needs to be configured at the OpenID Connect provider. The field that contains the roles array is configured in the `config.auth.openId` field in the Lowdefy configuration.
+
+            ```yaml
+            lowdefy: 3.14.1
+            config:
+              auth:
+                openId:
+                  # Field in the user idToken that contains the roles array.
+                  rolesField: [string]
+            ```
+
+            The pages that are protected by roles are configured in the `config.auth.roles` field in the Lowdefy configuration. This should be an object, where the keys are the role names, and the values are an array of pageIds that are protected by that role.
+
+            #### Examples
+
+            ###### Protect pages using roles:
+            ```yaml
+            lowdefy: 3.14.1
+            config:
+              auth:
+                openId:
+                  rolesField: custom_roles
+                roles:
+                  user-admin:
+                    - users
+                    - new-user
+                    - edit-user
+                  sales:
+                    - customers
+                    - new-customer
+                    - edit-customer
+                  reports:
+                    - sales-report
+                    - operations-report
+            ````
+
+      # - _ref:
+      #     path: templates/navigation_buttons.yaml
+      #     vars:
+      #       previous_page_title: User object
+      #       previous_page_id: user-object
+      #       next_page_title: Provider configuration
+      #       next_page_id: openid-provider-configuration

packages/docs/users/user-object.yaml

@@ -49,6 +49,21 @@ _ref:
                 _user: picture
             ````
 
+            ###### Insert user name and id (sub) when inserting a document in MongoDB:
+            ```yaml
+            id: insert_data
+            type: MongoDBInsertOne
+            properties:
+              doc:
+                field:
+                  _state: field
+                inserted_by:
+                  name:
+                    _user: name
+                  id:
+                    _user: sub
+            ````
+
       - _ref:
           path: templates/navigation_buttons.yaml
           vars: