forked from vikunja/vikunja
add openid.md as readme for feature: 950 assigning group through oidc claim
This commit is contained in:
parent
3468b9ca81
commit
1ea16e552e
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