From 1ea16e552e9d27eeb4e4d9d5ab7bb021b7edb6cf Mon Sep 17 00:00:00 2001
From: viehlieb <pf@pragma-shift.net>
Date: Wed, 1 Feb 2023 16:36:01 +0100
Subject: [PATCH] add openid.md as readme for feature: 950 assigning group
 through oidc claim

---
 pkg/modules/auth/openid/openid.md | 99 +++++++++++++++++++++++++++++++
 1 file changed, 99 insertions(+)
 create mode 100644 pkg/modules/auth/openid/openid.md

diff --git a/pkg/modules/auth/openid/openid.md b/pkg/modules/auth/openid/openid.md
new file mode 100644
index 0000000000..c3db488223
--- /dev/null
+++ b/pkg/modules/auth/openid/openid.md
@@ -0,0 +1,99 @@
+regarding:
+https://kolaente.dev/vikunja/api/pulls/1279
+
+# Assign teams via oidc
+This PR adds the functionality to assign users to teams via oidc.
+Read carefully and brief your administrators to use this feature.
+Tested with oidc provider authentik.
+To distinguish between groups created in vikunja and groups generated via oidc, there is an attribute neccessary, which is called: *oidcID*
+
+## Setup
+Edit config.yml to include scope: openid profile email vikunja_scope
+
+For authentik to use group assignment feature:
+- go to: .../if/admin/#/core/property-mappings
+
+- create a new mapping called "vikunja_scope"
+
+There is a field to enter python expressions that will be delivered with the oidc token.
+
+- write a small script, for adding group information to vikunja_scope.
+
+
+```python
+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": [
+        {
+            "name": "team 1",
+            "oidcID": 33349
+        },
+        {
+            "name": "team 2",
+            "oidcID": 35933
+        }
+    ]
+}
+"""
+```
+
+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 will see "(sso: XXXXX)" written next to each team you were asigned through oidc.
+
+
+## IMPORTANT NOTES: 
+**SSO/OIDC teams cannot be edited.**
+
+**It is crucial to call the element "vikunja_groups" since this is the name vikunja is looking for.**
+
+**Additionally, make sure to deliver an "oidcID" and a "name".**
+
+
+
+
+____________________________________________________________________________
+
+## BEHAVIOR
+
+*(.. examples for "team1" ..)*
+
+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"
+
+
+2. *In Vikunja Team with name "team 1" already exists in vikunja, but has no oidcID set:* \
+new team will be created called "team 1" with attribute oidcId: "33929"
+
+
+3. *In Vikunja Team with name "team 1" already exists in vikunja, but has different oidcID set:* \
+new team will be created called "team 1" with attribute oidcId: "33929"
+
+
+4. *In Vikunja Team with oidcID "33929" already exists in vikunja, but has different name than "team1":* \
+new team will be created called "team 1" with attribute oidcId: "33929"
+
+
+5. *Scope vikunja_scope is not set:* \
+nothing happens
+
+
+6. *oidcID is not set:* \
+You'll get error.
+Custom Scope malformed
+"The custom scope set by the OIDC provider is malformed. Please make sure the openid provider sets the data correctly for your scope. Check especially to have set an oidcID."
+ 
+7. *In Vikunja I am in "team 3" with oidcID "", but the token does not deliver any data for "team 3":* \
+You will stay in team 3 since it was not set by the oidc provider
+
+8. *In Vikunja I am in "team 3" with oidcID "12345", but the token does not deliver any data for "team 3"*:\
+You will be signed out of all teams, which have an oidcID set and are not contained in the token.
+Especially if you've been the last team member, the team will be deleted.
\ No newline at end of file