add openid.md as readme for feature: 950 assigning group through oidc claim
This commit is contained in:
parent
f2208491e7
commit
f6d1016648
99
pkg/modules/auth/openid/openid.md
Normal file
99
pkg/modules/auth/openid/openid.md
Normal file
|
@ -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.
|
Loading…
Reference in New Issue
Block a user