change openid.md directory, modify openid.md

docs/content/doc/setup/openid.md

@@ -1,23 +1,20 @@
 # Assign teams via oidc
-Adds the functionality to assign users to teams via oidc.
-Read carefully and brief your administrators to use this feature.
-You need to configure your oidc provider as explained in the documentation below to make this feature work.
-Tested with oidc provider authentik.
-To distinguish between teams created in vikunja and teams generated via oidc, a string attribute for vikunja teams is introduced, which is called: *oidcID*
-You should conigure your provider to send an oidcID to vikunja.
+Vikunja is capable of automatically adding users to a team based on a group defined in the oidc provider. If used, Vikunja will sync teams, automatically create new ones and make sure the members are part of the configured teams. Teams which only exist because they are generated from oidc attributes are not configurable in Vikunja.
 
-## Setup
+See below for setup instructions.
 
-Edit [config.yml](https://kolaente.dev/vikunja/api/src/branch/main/config.yml.sample) to include scope: openid profile email vikunja_scope
+To distinguish between teams created in Vikunja and teams generated automatically via oidc, generated teams have an `oidcID` assigned internally.
 
-For authentik to use group assignment feature:
-- go to: .../if/admin/#/core/property-mappings
+## Setup for atuhentik
 
-- create a new mapping called "vikunja_scope"
+To configure automatic team management through authentik, we assume you have already set up Authentik as an oidc provider for authentication with Vikunja.
 
-There is a field to enter python expressions that will be delivered with the oidc token.
+To use Authentik's group assignment feature, follow these steps:
 
-- write a small script, for adding group information to vikunja_scope.
+1. Edit [config.yml](https://kolaente.dev/vikunja/api/src/branch/main/config.yml.sample) to include scope: `openid profile email vikunja_scope`
+2. Open `<your authentik url>/if/admin/#/core/property-mappings`
+3. Create a new mapping called `vikunja_scope`. There is a field to enter python expressions that will be delivered with the oidc token.
+4. Write a small script like this to add group information to `vikunja_scope`:
 
 
 ```python
@@ -25,8 +22,9 @@ groupsDict = {"vikunja_groups": []}
 for group in request.user.ak_groups.all():
   groupsDict["vikunja_groups"].append({"name": group.name, "oidcID": group.num_pk})
 return groupsDict
+```
 
-"""
+```
 output example:
 {
     "vikunja_groups": [
@@ -40,21 +38,27 @@ output example:
         }
     ]
 }
-"""
 ```
+Now when you log into Vikunja via oidc there will be a list of scopes you are claiming from your oidc provider.
+You should see the description you entered in the oidc provider's admin area.
 
-Now when you log in via oidc there will be a list of scopes you are claiming from your oidc provider.
-You should see "the description you entered in the oidc provider's admin area"
+Log in and go to teams.
+You should see "(sso: XXXXX)" written next to each team you were asigned through oidc.
 
-- Log in and go to teams.
-- You will see "(sso: XXXXX)" written next to each team you were asigned through oidc.
+## IMPORTANT NOTES:
+* **SSO/OIDC teams cannot be edited.**
+
+* **It is required to deliver the key "vikunja_groups" via your custom_scope since this is the key vikunja is looking for to start the procedure.**
+
+* **Additionally, make sure to deliver an "oidcID" and a "name" attribute in the oidc token.**
 
 
-____________________________________________________________________________
+
+---
 
 ## BEHAVIOR
 
-*(.. examples for "team1" ..)*
+*All examples assume one team called "team 1"*
 
 1. *Token delivers team.name +team.oidcId  and Vikunja team does not exist:* \
 New team will be created called "team 1" with attribute oidcId: "33929"