vikunja/docs/content/doc/setup/openid.md

Assign teams via oidc

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.

See below for setup instructions.

To distinguish between teams created in Vikunja and teams generated automatically via oidc, generated teams have an oidcID assigned internally.

Setup for authentik

To configure automatic team management through authentik, we assume you have already set up Authentik as an oidc provider for authentication with Vikunja.

To use Authentik's group assignment feature, follow these steps:

1. Edit config.yml 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:

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 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.

Proceed to vikunja and go to teams. You should see "(sso: your_oidcID)" 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.

Use cases

All examples assume one team called "team 1"

1. Token delivers team.name +team.oidc_id 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 oidc_id: "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.