vikunja/vikunja
6
43
Fork 73
Code Issues 150 Pull Requests 20 Packages Releases 32 Activity

feat: assign users to teams via OIDC claims #1393

Merged
konrad merged 93 commits from viehlieb/api:950_reworked_assign_teams_via_oidc into main 2024-03-02 08:47:12 +00:00
Conversation 34 Commits 93 Files Changed 26 +28 -27
1 changed files with 28 additions and 27 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files
Showing only changes of commit 48ba083226 - Show all commits

55
docs/content/doc/setup/openid.md
View File

@ -1,21 +1,33 @@
# 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.
# OpenID
See below for setup instructions.
Vikunja allows for authentication with an oauth provider via the OpenID standard.
To learn more about how to configure this, [check out the examples]({{< ref "openid-examples.md">}})
{{< table_of_contents >}}
viehlieb marked this conversation as resolved Outdated
konrad commented 2023-10-18 15:07:26 +00:00
Outdated
Review
Copy Link

Typo: Should be Authentik.

Typo: Should be `Authentik`.
## Automatically assign users to teams
Vikunja is capable of automatically adding users to a team based on a group defined in the oidc provider.
If configured, Vikunja will sync teams, automatically create new ones and make sure the members are part of the configured teams.
Teams which exist only because they were created from oidc attributes are not editable in Vikunja.
To distinguish between teams created in Vikunja and teams generated automatically via oidc, generated teams have an `oidcID` assigned internally.
## Setup for authentik
You need to make sure the OpenID provider has the `vikunja_groups` scope via your custom scope since this is the key Vikunja is looking for to start the procedure.
To configure automatic team management through authentik, we assume you have already set up Authentik as an oidc provider for authentication with Vikunja.
Additionally, make sure to deliver an `oidcID` and a `name` attribute in the oidc token.
### Setup in Authentik
konrad commented 2023-12-01 14:47:54 +00:00
Outdated
Review
Copy Link

Here it is called vikunja_groups and in the text before it's vikunja_scope. Should this be the same?

Here it is called `vikunja_groups` and in the text before it's `vikunja_scope`. Should this be the same?
viehlieb commented 2023-12-06 12:18:27 +00:00
Outdated
Review
Copy Link

one is the required scope, which has to be customized -> vikunja_scope
another one is a key for the groups within this scope -> vikunja_groups.

the scope attribute in vikunja should be pluralized into "scopes"

in authentik the attribute that is asked for is referred to as scope.
Screenshot from 2023-12-06 14-35-25.png

one is the required scope, which has to be customized -> vikunja_scope another one is a key for the groups within this scope -> vikunja_groups. the scope attribute in vikunja should be pluralized into "scopes" in authentik the attribute that is asked for is referred to as scope. ![Screenshot from 2023-12-06 14-35-25.png ](https://kolaente.dev/vikunja/api/issues/1393/attachments/941b6b69-6f92-4abe-8d1c-b23ab43e8626)
Screenshot from 2023-12-06 14-35-25.png
39 KiB
konrad commented 2023-12-12 22:33:27 +00:00
Outdated
Review
Copy Link

Can you add this explanation to the docs?

Can you add this explanation to the docs?
viehlieb commented 2024-02-23 14:26:17 +00:00
Outdated
Review
Copy Link

I changed the docs a little to clarify this.

5f521c0982

Not sure if there is more needed.

I changed the docs a little to clarify this. https://kolaente.dev/vikunja/vikunja/commit/5f521c0982aa220b687c915cd8b02a01d3c696ab Not sure if there is more needed.
To configure automatic team management through Authentik, we assume you have already [set up Authentik]({{< ref "openid-examples.md">}}#authentik) as an oidc provider for authentication with Vikunja.
To use Authentik's group assignment feature, follow these steps:
1. Edit [config.yml](https://kolaente.dev/vikunja/api/src/branch/main/config.yml.sample) to include scope: `openid profile email vikunja_scope`
1. Edit [your config]({{< ref "config.md">}}) to include the following scopes: `openid profile email vikunja_scope`
2. Open `<your authentik url>/if/admin/#/core/property-mappings`
viehlieb marked this conversation as resolved Outdated
konrad commented 2023-10-18 15:08:38 +00:00
Outdated
Review
Copy Link

Can you move the title to the outside of the example json?

Can you move the title to the outside of the example json?
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`:
4. Write a small script like the following to add group information to `vikunja_scope`:
konrad marked this conversation as resolved Outdated
konrad commented 2024-03-01 19:52:13 +00:00
Outdated
Review
Copy Link

Please add to this guide how to add the scope to the Auth provider so that it actually shows up in Vikunja.

Please add to this guide how to add the scope to the Auth provider so that it actually shows up in Vikunja.
konrad commented 2024-03-02 08:24:19 +00:00
Outdated
Review
Copy Link

Now done.

Now done.
```python
groupsDict = {"vikunja_groups": []}
@ -40,43 +52,32 @@ 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.
Proceed to vikunja and go to teams.
You should see "(sso: *your_oidcID*)" written next to each team you were asigned through oidc.
Now when you log into Vikunja via Authentik it will show you a list of scopes you are claiming.
You should see the description you entered on the oidc provider's admin area.
viehlieb marked this conversation as resolved Outdated
konrad commented 2023-10-18 15:11:01 +00:00
Outdated
Review
Copy Link

This is unnecessary, please remove it

This is unnecessary, please remove it
## 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.
Proceed to vikunja and open the teams page in the sidebar menu.
viehlieb marked this conversation as resolved Outdated
konrad commented 2023-10-18 15:11:57 +00:00
Outdated
Review
Copy Link

What kind of behaviour? Please rename it to something more specific.

And please don't capitalize the heading, same for the other headings.

What kind of behaviour? Please rename it to something more specific. And please don't capitalize the heading, same for the other headings.
You should see "(sso: *your_oidcID*)" written next to each team you were assigned through oidc.
## Use cases
*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"
All examples assume one team called "Team 1" in your provider.
viehlieb marked this conversation as resolved Outdated
konrad commented 2023-10-18 15:12:50 +00:00
Outdated
Review
Copy Link

Is the attribute called oidcId or oidcID? The Authentik example was using oidcId.

Is the attribute called `oidcId` or `oidcID`? The Authentik example was using `oidcId`.
viehlieb commented 2023-11-07 14:01:11 +00:00
Outdated
Review
Copy Link

in authentik it is called oidcID

in migration:

type teams20230104152903 struct {
	OidcID string `xorm:"varchar(250) null" maxLength:"250" json:"oidc_id"`
}

Therefore in the db it is called oidc_id

I agree, there is an inconsistency in the .md file.

I try to fit the naming to the context.
Do you have suggested changes in renaming?

in authentik it is called `oidcID` in migration: ``` type teams20230104152903 struct { OidcID string `xorm:"varchar(250) null" maxLength:"250" json:"oidc_id"` } ``` Therefore in the db it is called oidc_id I agree, there is an inconsistency in the .md file. I try to fit the naming to the context. Do you have suggested changes in renaming?
konrad commented 2023-11-07 15:04:08 +00:00
Outdated
Review
Copy Link

I think the name is fine, but please use the same one everywhere.

I think the name is fine, but please use the same one everywhere.
👍 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
@ -87,4 +88,4 @@ 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.
Especially if you've been the last team member, the team will be deleted.