From 20caad24ed0a0102678a16e97a2984506d48da32 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jan=20B=C3=B6hmer?= Date: Sat, 4 Mar 2023 17:15:17 +0100 Subject: [PATCH] Improved documentation --- README.md | 1 + docs/index.md | 1 + docs/installation/saml_sso.md | 7 ++++++- 3 files changed, 8 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index 254e0cbe..2ab62eba 100644 --- a/README.md +++ b/README.md @@ -41,6 +41,7 @@ and multiple store locations and price information. Parts can be grouped using t * Barcodes/Labels generator for parts and storage locations, scan barcodes via webcam using the builtin barcode scanner * User system with groups and detailed (fine granular) permissions. Two-factor authentication is supported (Google Authenticator and Webauthn/U2F keys) and can be enforced for groups. Password reset via email can be setuped. +* Optional support for single sign-on (SSO) via SAML (using an intermediate service like [Keycloak](https://www.keycloak.org/) you can connect Part-DB to an existing LDAP or Active Directory server) * Import/Export system (partial working) * Project management: Create projects and assign parts to the bill of material (BOM), to show how often you could build this project and directly withdraw all components needed from DB * Event log: Track what changes happens to your inventory, track which user does what. Revert your parts to older versions. diff --git a/docs/index.md b/docs/index.md index c2f561cf..9bc5b1a4 100644 --- a/docs/index.md +++ b/docs/index.md @@ -27,6 +27,7 @@ It is installed on a web server and so can be accessed with any browser without * Barcodes/Labels generator for parts and storage locations, scan barcodes via webcam using the builtin barcode scanner * User system with groups and detailed (fine granular) permissions. Two-factor authentication is supported (Google Authenticator and Webauthn/U2F keys) and can be enforced for groups. Password reset via email can be setuped. +* Optional support for single sign-on (SSO) via SAML (using an intermediate service like [Keycloak](https://www.keycloak.org/) you can connect Part-DB to an existing LDAP or Active Directory server) * Import/Export system (partial working) * Project management: Create projects and assign parts to the bill of material (BOM), to show how often you could build this project and directly withdraw all components needed from DB * Event log: Track what changes happens to your inventory, track which user does what. Revert your parts to older versions. diff --git a/docs/installation/saml_sso.md b/docs/installation/saml_sso.md index 09349047..4922d042 100644 --- a/docs/installation/saml_sso.md +++ b/docs/installation/saml_sso.md @@ -24,6 +24,11 @@ but it should work with any SAML 2.0 compatible identity provider. This guide assumes that you have a working Keycloak installation with some users. If you don't, you can follow the [Keycloak Getting Started Guide](https://www.keycloak.org/docs/latest/getting_started/index.html). +{: .important } +> Part-DB associates local users with SAML users by their username. That means if the username of a SAML user changes, a new local user will be created (and the old account can not be accessed). +> You should make sure that the username of a SAML user does not change. If you use Keycloak make sure that the possibility to change the username is disabled (which is by default). +> If you really have to rename a SAML user, a Part-DB admin can rename the local user in the Part-DB in the admin panel, to match the new username of the SAML user. + ## Configure basic SAML connection ### Create a new SAML client @@ -99,7 +104,7 @@ Part-DB allows you to configure a mapping between SAML roles or groups and Part- For this you need first have to create the groups in Part-DB, to which you want to assign the users and configure their permissions. You will need the IDs of the groups, which you can find in the `System->Group` page of Part-DB in the Info tab. -The map is provided as [JSON](https://en.wikipedia.org/wiki/JSON) encoded map between the SAML role and the group ID, which has the form `{"saml_role": group_id, "*": group_id, ...}`. You can use the `*` key to assign a group to all users, which are not in any other group. The map is configured via the `SAML_ROLE_MAPPING` environment variable, which you can configure via the `.env.local` or `docker-compose.yml` file. Please note that you have to enclose the JSON string in single quotes here, as JSON itself uses double quotes (e.g. `SAML_ROLE_MAPPING='{ "*": 2, "editor": 3, "admin": 1 }'). +The map is provided as [JSON](https://en.wikipedia.org/wiki/JSON) encoded map between the SAML role and the group ID, which has the form `{"saml_role": group_id, "*": group_id, ...}`. You can use the `*` key to assign a group to all users, which are not in any other group. The map is configured via the `SAML_ROLE_MAPPING` environment variable, which you can configure via the `.env.local` or `docker-compose.yml` file. Please note that you have to enclose the JSON string in single quotes here, as JSON itself uses double quotes (e.g. `SAML_ROLE_MAPPING='{ "*": 2, "editor": 3, "admin": 1 }`). For example if you want to assign the group with ID 1 (by default admin) to every SAML user which has the role `admin`, the role with ID 3 (by default editor) to every SAML user with the role `editor` and everybody else to the group with ID 2 (by default readonly), you can configure the following map: