docs(user-mgt): restructure user management documentation (#9946)

* docs(scim): updated scim documentions Signed-off-by: Mobarak Hosen Shakil <[email protected]> * docs(scim): updated scim documentions Signed-off-by: Mobarak Hosen Shakil <[email protected]> * docs(usr-mgt): removed ldap part Signed-off-by: Mobarak Hosen Shakil <[email protected]> * docs(usr-mgt): removed ldap part Signed-off-by: Mobarak Hosen Shakil <[email protected]> * docs(usr-mgt): Added docs on postgreSQL to explore jansDB in pgAdmin Signed-off-by: Mobarak Hosen Shakil <[email protected]> * updated jans tui command Signed-off-by: Mobarak Hosen Shakil <[email protected]> --------- Signed-off-by: Mobarak Hosen Shakil <[email protected]>
JanssenProject · Oct 28, 2024 · f35db99 · f35db99
1 parent fecffe9
commit f35db99
Show file tree

Hide file tree

Showing 16 changed files with 607 additions and 47 deletions.
diff --git a/docs/assets/jans-tui-add-user-claims.png b/docs/assets/jans-tui-add-user-claims.png
diff --git a/docs/assets/jans-tui-scim-config.png b/docs/assets/jans-tui-scim-config.png
diff --git a/docs/assets/pgAdmin-connection.png b/docs/assets/pgAdmin-connection.png
diff --git a/docs/assets/pgAdmin-server-name.png b/docs/assets/pgAdmin-server-name.png
diff --git a/docs/assets/pgAdmin-ssh-tunnel.png b/docs/assets/pgAdmin-ssh-tunnel.png
diff --git a/docs/assets/scim-attribute-retrieve.png b/docs/assets/scim-attribute-retrieve.png
diff --git a/docs/assets/tui-attribute.png b/docs/assets/tui-attribute.png
diff --git a/docs/janssen-server/config-guide/scim-config/user-config.md b/docs/janssen-server/config-guide/scim-config/user-config.md
diff --git a/docs/janssen-server/fido/monitoring.md b/docs/janssen-server/fido/monitoring.md
@@ -4,4 +4,54 @@ tags:
   - fido
 ---
 
-This page will be the landing page for the Janssen Project admin documentation
+# Monitoring
+
+## FIDO Devices
+
+A FIDO device represents a user credential stored in the Jans Server database that is compliant with the [FIDO](https://fidoalliance.org/) standard. These devices are used as a second factor in a setting of strong authentication.
+
+FIDO devices were superseded by [FIDO 2](#fido2-devices) devices in Jans Server.
+
+## FIDO2 devices
+
+FIDO2 devices are credentials that adhere to the more current Fido 2.0 initiative (WebAuthn + CTAP). Examples of FIDO2 devices are USB security keys and Super Gluu devices.
+
+The SCIM endpoints for FIDO 2 allow application developers to query, update and delete already existing devices. Addition of devices do not take place through the service since this process requires direct end-user interaction, ie. device enrolling.
+
+The schema attributes for a device of this kind can be found by hitting the URL  `https://<jans-server>/jans-scim/restv1/v2/Schemas/urn:ietf:params:scim:schemas:core:2.0:Fido2Device`
+
+To distinguish between regular FIDO2 and SuperGluu devices, note only SuperGluu entries have the attribute `deviceData` populated (i.e. not null)
+
+### Example: Querying Enrolled Devices
+
+Say we are interested in having a list of Super Gluu devices users have enrolled and whose operating system is iOS. We may issue a query like this:
+
+```
+curl -k -G -H 'Authorization: Bearer ACCESS_TOKEN' --data-urlencode 
+'filter=deviceData co "ios"' -d count=10 https://<jans-server>/jans-scim/restv1/v2/Fido2Devices
+```
+
+The response will be like:
+
+```
+{
+  "totalResults": ...,
+  "itemsPerPage": ...,
+  "startIndex": 1,
+  "schemas": [
+    "urn:ietf:params:scim:api:messages:2.0:ListResponse"
+  ],
+  "Resources": [
+    {
+      "id": "...",
+      "meta": {...},
+      "schemas": ["urn:ietf:params:scim:schemas:core:2.0:Fido2Device"],
+      "userId": "...",
+      ...
+      "deviceData": "{...}",
+      "displayName": ...,
+    },
+    ...
+  ]
+}
+```
diff --git a/docs/janssen-server/scim/README.md b/docs/janssen-server/scim/README.md
@@ -13,3 +13,74 @@ The specification defines reference schemas for users and groups along with REST
 Developers can think of **SCIM** merely as a **REST API** with endpoints exposing **CRUD** functionality (create, read, update, and delete).
 
 This section covers how to configure, protect, and monitor the Janssen Server SCIM module and its APIs.
+
+## Installation
+
+The API is available as a component of the Janssen Server. Upon [installation](../install/vm-install/vm-requirements.md) you can select if you want SCIM included in your environment. To add SCIM post-install do the following:
+
+```bash title="Command"
+python3 /opt/jans/jans-setup/setup.py --install-scim
+```
+
+## About API endpoints
+
+Throughout this document, you will notice endpoints are prefixed with path: `/jans-scim/restv1/v2`
+
+## API Protection
+
+Clearly, this API must not be anonymously accessed. However, the basic SCIM standard does not define a specific mechanism to prevent unauthorized requests to endpoints. There are just a few guidelines in section 2 of [RFC 7644](https://datatracker.ietf.org/doc/html/rfc7644) concerned with authentication and authorization.
+
+* OAUTH, This is the default and recommended mechanism
+* BYPASS
+
+To know more about OAuth protection mode please visit [here](./oauth-protection.md). The SCIM API endpoints are by default protected by (Bearer) OAuth 2.0 tokens. Depending on the operation, these tokens must have certain scopes for the operations to be authorized. We need a client to get Bearer token.
+
+## API documentation at a glance
+
+[SCIM API](../../admin/reference/openapi.md) doc page describes about our implementation of SCIM. The API has also been documented using OpenAPI (swagger) specification for the interested.
+
+## Potential performance issues with Group endpoints
+
+In SCIM a group resource basically consists of an identifier, a display name, and a collection of members associated to it. Also, every member is made up of a user identifier, his display name, and other attributes. As a consequence, retrieving group information requires making a correlation with existing user data. Since Gluu database model does not follow a relational database pattern this may entail a considerable amount of user queries when groups contain thousands of members.
+
+While this could have been workarounded by storing members' display names inside group entries, this brings additional problems to deal with.
+
+Another source of potential overhead stems from creation and modification of groups where many new users are associated to a given group: by default checks are made to guarantee only existing users are attached to groups, thus requiring continuous database queries.
+
+Currently there are two ways to lower the amount of database lookups required for SCIM group operations:
+
+* Explicitly excluding display names from responses
+* Pass the overhead bypass flag to skip members validations
+
+The first approach consists of using the query parameter `excludedAttributes` (see [RFC 7644](https://datatracker.ietf.org/doc/html/rfc7644)) so that display names are neither retrieved from database nor sent in responses. A value like `members.display` does the job. Note the query parameter attributes can also be used for this purpose, for example with a value like `members.value` that will output only members' identifiers and ignore other non-required attributes.
+
+This approach is particularly useful in search and retrievals when users' display names are not needed.
+
+The second is a stronger approach that turns off validation of incoming members data: if the usage of a POST/PUT/PATCH operation implies adding members, their existence is not verified, they will simply get added. Here, the client application is responsible for sending accurate data. To use this approach add a query or header parameter named `Group-Overhead-Bypass` with any value. Note under this mode of operation:
+
+* Display names are never returned regardless of `attributes` or `excludedAttributes` parameters values
+* Remove/replace patch operations that involve display names in path filters are ignored, eg: `"path": "members[value eq \"2819c223\" or display eq \"Joe\"]"`
+
+## User Registration Process with SCIM
+
+SCIM service has many use cases. One interesting and often arising is that of coding your own user registration process. With your SCIM endpoints you can build a custom application to maintain user entries in your database.
+
+### Important Considerations
+
+Here, you have some useful tips before you start:
+
+1. Choose a toolset you feel comfortable to work with. Keep in mind that you have to leverage the capabilities of your language/framework to issue complex HTTPS requests. Be sure that:
+
+      * You will be able to use at least the following verbs: GET, POST, PUT, and DELETE
+
+      * You can send headers in your requests as well as reading them from the service response
+
+2. If not supported natively, choose a library to facilitate JSON content manipulation. As you have already noticed we have been dealing with JSON for requests as well as for responses. Experience shows that being able to map from objects (or data structures) of your language to Json and viceversa helps saving hours of coding.
+
+3. Shape your data model early. List the attributes your application will operate upon and correlate with those found in the SCIM user schema. You can learn about the schema in [RFC 7644](https://datatracker.ietf.org/doc/html/rfc7644). At least, take a look at the JSON-formatted schema that your Jans Server shows: visit `https://<host-name>/jans-scim/restv1/v2/Schemas/urn:ietf:params:scim:schemas:core:2.0:User`
+
+4. You will have to manipulate database contents very often as you develop and run tests, thus, find a suitable tool for the task. In the case of LDAP, a TUI client is a good choice.
+
+5. Always check your [logs](./logs.md).
+
+6. In this user management guide with SCIM, we have already touched upon the fundamentals of SCIM in Jans Server and shown a good amount of sample requests for manipulation of user information. However, keep in mind the SCIM spec documents are definitely the key reference to build working request messages, specially [RFC 7643](https://datatracker.ietf.org/doc/html/rfc7643), and [RFC 7644](https://datatracker.ietf.org/doc/html/rfc7644).
diff --git a/docs/janssen-server/scim/config.md b/docs/janssen-server/scim/config.md
@@ -24,7 +24,7 @@ To retrieve the current server configuration run the command `python3 /opt/jans/
 
 To modify some aspect of the retrieved configuration prepare a PATCH request in JSON format. For instance:
 
-```
+```json title="PATCH"
 [
 { 
   "op":"replace",
@@ -47,12 +47,16 @@ These contents should be then passed to the `patch-scim-config` operation, e.g.
 To retrieve the current server configuration using TUI proceed as below:
 
 1. Launch TUI, e.g. by running `jans tui`, and follow the prompts
-1. Highlight the SCIM tab using your keyboard's left/right arrow key
-1. Highlight the "Get Scim Configuration" button using the tab key
-1. Press enter
+2. Highlight the SCIM tab using your keyboard's left/right arrow key
+3. Highlight the "Get Scim Configuration" button using the tab key
+4. Press enter
+
+You can modify the configuration in place by editing the fields of your interest. To persist the changes, highlight the "Save" button at the bottom and press enter.
+
+## SCIM Operations Guide using CLI, TUI and API
 
-You can modify the configuration in place by editing the fields of your interest. To persist the changes, highlight the "Save" button at the bottom and press enter 
+SCIM operations support mutiple options. Please check out this [documentation](../config-guide/scim-config/user-config.md) for guidelines of scim operations.
 
 ## When will changes take effect?
 
-Any configuration update will take effect one minute after it has been applied whether via CLI or TUI. 
+Any configuration update will take effect one minute after it has been applied whether via CLI or TUI.
diff --git a/docs/janssen-server/scim/custom-attributes.md b/docs/janssen-server/scim/custom-attributes.md
@@ -5,29 +5,29 @@ tags:
   - custom-attributes
 ---
 
-##  Custom Attributes
+# Custom Attributes
 
 [RFC 7643](https://datatracker.ietf.org/doc/html/rfc7643) defines the schema for resource types in SCIM (see section 3.3). In other words, it defines structures in terms of attributes to represent users and groups as well as attribute types, mutability, cardinality, and so on.
 
 Although the schema covers many attributes one might think of, at times you will need to add your own attributes for specific needs. This is where user extensions pitch in, they allow you to create custom attributes for SCIM. To do so, you will have to:
 
-* Add an attribute to LDAP schema
+* Add an attribute to Database schema
 
 * Include the new attribute in an LDAP's object class such as jansPerson
 
 * Register and activate your new attribute through **Jans TUI**.
 
-Please visit this [page](https://docs.jans.io/head/admin/config-guide/attribute-configuration/) for a more detailed explanation. When registering the attribute in the **TUI**, please ensure you have set the `Include in SCIM Extension` parameter to `true`.
+Please visit this [page](../config-guide/auth-server-config/attribute-configuration.md) for a more detailed explanation. When registering the attribute in the **TUI**, please ensure you have set the `Include in SCIM Extension` parameter to `true`.
 
-![attribute](https://github.com/JanssenProject/jans/assets/43112579/61d0aff6-75fa-4e6b-8db6-2eeb3332cfe5)
+![attribute](../../assets/tui-attribute.png)
 
 Once you submit this form, your attribute will be part of the `User Extension`. You can verify this by inspecting the `Schema` endpoint:
 
-```
+```bash title="Command"
 https://<host-name>/jans-scim/restv1/v2/Schemas/urn:ietf:params:scim:schemas:extension:gluu:2.0:User
 ```
 
-![output-json](https://github.com/JanssenProject/jans/assets/43112579/41804347-4084-4bb4-8bc5-05fc220ae394)
+![output-json](../../assets/scim-attribute-retrieve.png)
 
 In the JSON response, your new added attribute will appear.
 
@@ -39,12 +39,4 @@ To customize the URI associated to the extension (whose default value is `urn:ie
 * Set a value in the field `User Extension Schema URI`
 * Save the changes
 
-![scim-extension](https://github.com/JanssenProject/jans/assets/43112579/fb5b9d5c-8b17-4be0-af6c-d36389de82d2)
-
-
-
-
-
-
-
-
+![scim-extension](../../assets/jans-tui-scim-config.png)
diff --git a/docs/janssen-server/scim/logs.md b/docs/janssen-server/scim/logs.md
@@ -4,8 +4,8 @@ tags:
   - scim
 ---
 
-## SCIM Logs
+# SCIM Logs
 
-Logs can be found under `/opt/jans/jetty/jans-scim/logs` in your Janssen Server. The default logging level is `INFO` but this can be changed to any of `TRACE`, `DEBUG`, `WARN`, OR `ERROR` via TUI. 
+Logs can be found under `/opt/jans/jetty/jans-scim/logs` in your Janssen Server. The default logging level is `INFO` but this can be changed to any of `TRACE`, `DEBUG`, `WARN`, OR `ERROR` via TUI.
 
 To do so launch TUI, e.g. `jans tui`, and navigate to SCIM tab. Then in "Logging Level" select the desired option. Finally hit "Save".
diff --git a/docs/janssen-server/scim/monitoring.md b/docs/janssen-server/scim/monitoring.md
@@ -4,14 +4,16 @@ tags:
   - scim
 ---
 
-## This content is in progress
+# How is SCIM data stored?
 
-The Janssen Project documentation is currently in development. Topic pages are being created in order of broadest relevance, and this page is coming in the near future.
+SCIM [schema spec](https://datatracker.ietf.org/doc/html/rfc7643) does not use LDAP attribute names but a different naming convention for resource attributes (note this is not the case of custom attributes where the SCIM name used is that of the LDAP attribute).
+
+It is possible to determine if a given LDAP attribute is being mapped to a SCIM attribute. For that you need to check in Jans TUI `Auth-Server >> Attributes` and click on any attributes. Check `Include in SCIM Extension:` is `true` or `false`. Whenever you try to map any LDAP attribute to a SCIM attribute keep it's value `true`.
 
 ## Have questions in the meantime?
 
 While this documentation is in progress, you can ask questions through [GitHub Discussions](https://github.com/JanssenProject/jans/discussions) or the [community chat on Gitter](https://gitter.im/JanssenProject/Lobby). Any questions you have will help determine what information our documentation should cover.
 
 ## Want to contribute?
 
-If you have content you'd like to contribute to this page in the meantime, you can get started with our [Contribution guide](https://docs.jans.io/head/CONTRIBUTING/).
+If you have content you'd like to contribute to this page in the meantime, you can get started with our [Contribution guide](https://docs.jans.io/head/CONTRIBUTING/).
diff --git a/docs/janssen-server/scim/oauth-protection.md b/docs/janssen-server/scim/oauth-protection.md
@@ -4,7 +4,7 @@ tags:
   - scim
 ---
 
-## OAuth protection
+# OAuth protection
 
 The SCIM API endpoints are by default protected by (Bearer) OAuth 2.0 tokens. Depending on the operation, these tokens must have certain scopes for the operations to be authorized. The table below summarizes this fact:
 
@@ -36,19 +36,19 @@ From the "Basic" section, grab the "client id" and "client secret". This secret
 
 This is a `curl` example of how to get a token valid for retrieving and modifying users (line breaks added for readability). Note the use of white space to separate scope names.
 
-```
+```bash title="Command"
 curl -k -u 'CLIENT_ID:DECRYPTED_CLIENT_SECRET' -k -d grant_type=client_credentials -d 
     scope='https://jans.io/scim/users.read https://jans.io/scim/users.write' 
     https://your-jans-server/jans-auth/restv1/token
-``` 
+```
 
 Grab the "access_token" from the obtained response.
 
 ## Issue a request to the service
 
 The below is a curl example of how to call an operation by passing the previously obtained token (line breaks added for readability):
 
-```
+```bash title="Command"
 curl -k -G -H 'Authorization: Bearer ACCESS_TOKEN' --data-urlencode 'filter=displayName co "Admin"' 
     https://your-jans-server/jans-scim/restv1/v2/Users
 

diff --git a/docs/janssen-server/usermgmt/README.md b/docs/janssen-server/usermgmt/README.md
@@ -4,14 +4,74 @@ tags:
   - user management
 ---
 
-## This content is in progress
+# Local User Management
 
-The Janssen Project documentation is currently in development. Topic pages are being created in order of broadest relevance, and this page is coming in the near future.
+In this document we will cover managing people in the Jans Server's LDAP Directory, Jans CLI / TUI and using SCIM.
 
-## Have questions in the meantime?
+=== "Manage Data using DB Browser"
 
-While this documentation is in progress, you can ask questions through [GitHub Discussions](https://github.com/JanssenProject/jans/discussions) or the [community chat on Gitter](https://gitter.im/JanssenProject/Lobby). Any questions you have will help determine what information our documentation should cover.
+    You can manage your Janssen Server's data using external tool provided by specific DB. Jump into [Manage RDBMS Data](#manage-data-in-rdbms) section for guidelines to explore Janssen Server's data using [pgAdmin](https://www.pgadmin.org/).
+
+=== "User Management using SCIM"
+
+    SCIM allows many ways to manage users data. Jump into the [SCIM User Management](../config-guide/scim-config/user-config.md) for guidelines of SCIM operations. To know how SCIM works in Janssen Server, read more from [here](../scim/README.md).
+
+=== "Manage External Data Sources Using Link"
+
+    Janssen Server allows connecting external data sources using Jans Link. Syncing people and attributes from a backend server speeds up authentication transactions. It is possible to perform attribute transformations, changing the name of attributes, or even using an interception script to change the values. Transformations are stored locally in Janssen Server. Read out [Link Guide](../link/README.md) to know more details on it.
+
+
+## Manage Data in RDBMS
+
+During the Janssen server installation, you can choose any of the supported RDBMS from the list; like mysql, or postgreSQL. In this article, We will connect postgreSQL database locally to explore `jansDB`. Let's see how we can connect PostgreSQL DB from jans server to your local PC.
+
+### Get PostgreSQL DB Information
+
+Let's get the postgreSQL databse information from the Janssen server properties which is located in `/opt/jans/jans-setup/setup.properties.last`. Run the following command:
+
+```bash title="Command"
+cat /opt/jans/jans-setup/setup.properties.last | grep 'rdbm_'
+```
+
+It should print details like below:
+
+```text title="Output"
+rdbm_db=jansdb
+rdbm_host=localhost
+rdbm_install=True
+rdbm_install_type=1
+rdbm_password=xxxxxxxx
+rdbm_password_enc=xxxxxxxxxxxxx\=\=
+rdbm_port=5432
+rdbm_type=pgsql
+rdbm_user=jans
+static_rdbm_dir=/opt/jans/jans-setup/static/rdbm
+```
+
+### Create SSH Tunnel
+
+You can create a SSH tunnel with the Janssen Server's database using the following command:
+
+```
+ssh -fNL 5432:localhost:5432 [user]@[janssen-server-host]
+```
+
+Or using `pgAdmin`'s SSH tunnel option:
+
+![pgAdmin-SSH-Tunnel](../../assets/pgAdmin-ssh-tunnel.png)
+
+### Add Database in **`pgAdmin`**
+
+Let's open pgAdmin in your local pc, and add a server.
+
+![add-server](../../assets/pgAdmin-server-name.png)
+
+Go to `Connection` tab add the database as following in the image below:
+
+![add-db-in-pgadmin](../../assets/pgAdmin-connection.png)
+
+Finally, save it and explore.
 
 ## Want to contribute?
 
-If you have content you'd like to contribute to this page in the meantime, you can get started with our [Contribution guide](https://docs.jans.io/head/CONTRIBUTING/).
+If you have content you'd like to contribute to this page in the meantime, you can get started with our [Contribution guide](https://docs.jans.io/head/CONTRIBUTING/).