forked from vikunja/vikunja
docs: improve OpenID documentation
This commit is contained in:
parent
4bb09b69be
commit
4f474117b0
|
@ -1209,13 +1209,12 @@ Environment path: `VIKUNJA_AUTH_LOCAL`
|
||||||
|
|
||||||
OpenID configuration will allow users to authenticate through a third-party OpenID Connect compatible provider.<br/>
|
OpenID configuration will allow users to authenticate through a third-party OpenID Connect compatible provider.<br/>
|
||||||
The provider needs to support the `openid`, `profile` and `email` scopes.<br/>
|
The provider needs to support the `openid`, `profile` and `email` scopes.<br/>
|
||||||
**Note:** Some openid providers (like gitlab) only make the email of the user available through openid claims if they have set it to be publicly visible.
|
**Note:** Some openid providers (like Gitlab) only make the email of the user available through OpenID if they have set it to be publicly visible.
|
||||||
If the email is not public in those cases, authenticating will fail.
|
If the email is not public in those cases, authenticating will fail.
|
||||||
**Note 2:** The frontend expects to be redirected after authentication by the third party
|
**Note 2:** The frontend expects the third party to rediect the user <frontend-url>/auth/openid/<auth key> after authentication. Please make sure to configure the redirect url in your third party
|
||||||
to <frontend-url>/auth/openid/<auth key>. Please make sure to configure the redirect url in your third party
|
|
||||||
auth service accordingly if you're using the default vikunja frontend.
|
auth service accordingly if you're using the default vikunja frontend.
|
||||||
The frontend will automatically provide the api with the redirect url, composed from the current url where it's hosted.
|
The frontend will automatically provide the API with the redirect url, composed from the current url where it's hosted.
|
||||||
If you want to use the desktop client with openid, make sure to allow redirects to `127.0.0.1`.
|
If you want to use the desktop client with OpenID, make sure to allow redirects to `127.0.0.1`.
|
||||||
Take a look at the [default config file](https://kolaente.dev/vikunja/vikunja/src/branch/main/config.yml.sample) for more information about how to configure openid authentication.
|
Take a look at the [default config file](https://kolaente.dev/vikunja/vikunja/src/branch/main/config.yml.sample) for more information about how to configure openid authentication.
|
||||||
|
|
||||||
Default: `<empty>`
|
Default: `<empty>`
|
||||||
|
|
|
@ -10,7 +10,7 @@ menu:
|
||||||
|
|
||||||
# OpenID example configurations
|
# OpenID example configurations
|
||||||
|
|
||||||
On this page you will find examples about how to set up Vikunja with a third-party OpenID provider.
|
On this page you will find examples about how to set up Vikunja with a third-party OAuth 2.0 provider using OpenID Connect.
|
||||||
To add another example, please [edit this document](https://kolaente.dev/vikunja/vikunja/src/branch/main/docs/content/doc/setup/openid-examples.md) and send a PR.
|
To add another example, please [edit this document](https://kolaente.dev/vikunja/vikunja/src/branch/main/docs/content/doc/setup/openid-examples.md) and send a PR.
|
||||||
|
|
||||||
{{< table_of_contents >}}
|
{{< table_of_contents >}}
|
||||||
|
@ -28,6 +28,7 @@ openid:
|
||||||
authurl: https://login.mydomain.com
|
authurl: https://login.mydomain.com
|
||||||
clientid: <vikunja-id>
|
clientid: <vikunja-id>
|
||||||
clientsecret: <vikunja secret>
|
clientsecret: <vikunja secret>
|
||||||
|
scope: openid email profile
|
||||||
```
|
```
|
||||||
|
|
||||||
Authelia config:
|
Authelia config:
|
||||||
|
@ -57,6 +58,7 @@ openid:
|
||||||
authurl: https://accounts.google.com
|
authurl: https://accounts.google.com
|
||||||
clientid: <google-oauth-client-id>
|
clientid: <google-oauth-client-id>
|
||||||
clientsecret: <google-oauth-client-secret>
|
clientsecret: <google-oauth-client-secret>
|
||||||
|
scope: openid email profile
|
||||||
```
|
```
|
||||||
|
|
||||||
Google config:
|
Google config:
|
||||||
|
@ -80,6 +82,7 @@ openid:
|
||||||
logouturl: https://keycloak.mydomain.com/realms/<relam-name>/protocol/openid-connect/logout
|
logouturl: https://keycloak.mydomain.com/realms/<relam-name>/protocol/openid-connect/logout
|
||||||
clientid: <vikunja-id>
|
clientid: <vikunja-id>
|
||||||
clientsecret: <vikunja secret>
|
clientsecret: <vikunja secret>
|
||||||
|
scope: openid email profile
|
||||||
```
|
```
|
||||||
Keycloak Config:
|
Keycloak Config:
|
||||||
- Navigate to the keycloak instance
|
- Navigate to the keycloak instance
|
||||||
|
@ -109,6 +112,11 @@ auth:
|
||||||
logouturl: "https://authentik.mydomain.com/application/o/vikunja/end-session/"
|
logouturl: "https://authentik.mydomain.com/application/o/vikunja/end-session/"
|
||||||
clientid: "" # copy from Authetik
|
clientid: "" # copy from Authetik
|
||||||
clientsecret: "" # copy from Authentik
|
clientsecret: "" # copy from Authentik
|
||||||
|
scope: openid email profile
|
||||||
```
|
```
|
||||||
|
|
||||||
**Note:** The `authurl` that Vikunja requires is not the `Authorize URL` that you can see in the Provider. Vikunja uses Open ID Discovery to find the correct endpoint to use. Vikunja does this by automatically accessing the `OpenID Configuration URL` (usually `https://authentik.mydomain.com/application/o/vikunja/.well-known/openid-configuration`). Use this URL without the `.well-known/openid-configuration` as the `authurl`.
|
**Note:** The `authurl` that Vikunja requires is not the `Authorize URL` that you can see in the Provider.
|
||||||
|
Vikunja uses OpenID Discovery to find the correct endpoint to use.
|
||||||
|
Vikunja does this automatically by accessing the `OpenID Configuration URL` (usually `https://authentik.mydomain.com/application/o/vikunja/.well-known/openid-configuration`).
|
||||||
|
Use this URL without the `.well-known/openid-configuration` as the `authurl`.
|
||||||
|
Typically this URL can be found in the metadata section within your identity provider.
|
||||||
|
|
|
@ -10,27 +10,117 @@ menu:
|
||||||
|
|
||||||
# OpenID
|
# OpenID
|
||||||
|
|
||||||
Vikunja allows for authentication with an oauth provider via the OpenID standard.
|
Vikunja allows for authentication with an external identity source such as Authentik, Keycloak or similar via the
|
||||||
|
[OpenID Connect](https://openid.net/developers/specs/) standard.
|
||||||
To learn more about how to configure this, [check out the examples]({{< ref "openid-examples.md">}})
|
|
||||||
|
|
||||||
{{< table_of_contents >}}
|
{{< table_of_contents >}}
|
||||||
|
|
||||||
|
## OpenID Connect Overview
|
||||||
|
|
||||||
|
OpenID Connect is a standardized identity layer built on top of the more generic OAuth 2.0 specification, simplying interaction between the involved parties significantly.
|
||||||
|
While the [OpenID specification](https://openid.net/specs/openid-connect-core-1_0.html#Overview) is worth a read, we summarize the most important basics here.
|
||||||
|
|
||||||
|
The involved parties are:
|
||||||
|
|
||||||
|
- **Resource Owner:** typically the end-user
|
||||||
|
- **Resource Server:** the application server handling requests from the client, the Vikunja API in our case
|
||||||
|
- **Client:** the application or client accessing the RS on behalf of the RO. Vikunja web frontend or any of the apps
|
||||||
|
- **Authorization Server:** the server verifying the user identity and issuing tokens. These docs also use the words `OAuth 2.0 provider`, `Identity Provider` interchangeably.
|
||||||
|
|
||||||
|
After the user is authenticated, the provider issues a token to the user, containing various claims.
|
||||||
|
There's different types of tokens (ID token, access token, refresh token), and all of them are created as [JSON Web Token](https://www.rfc-editor.org/info/rfc7519).
|
||||||
|
Claims in turn are assertions containing information about the token bearer, usually the user.
|
||||||
|
|
||||||
|
**Scopes** are requested by the client when redirecting the end-user to the Authorization Server for authentication, and indirectly control which claims are included in the resulting tokens.
|
||||||
|
There's certain default scopes, but its also possible to define custom scopes, which are used by the feature assigning users to Teams automatically.
|
||||||
|
|
||||||
|
## Configuring OIDC Authentication
|
||||||
|
|
||||||
|
To achieve authentication via an external provider, it is required to (a) configure a confidential Client on your OAuth 2.0 provider and (b) configure Vikunja to authenticate against this provider.
|
||||||
|
[Example configurations]({{< ref "openid-examples.md">}}) are provided for various different identity providers, below you can find generic guides though.
|
||||||
|
|
||||||
|
OpenID Connect defines various flow types indicating how exactly the interaction between the involved parties work, Vikunja makes use of the standard **Authorization Code Flow**.
|
||||||
|
|
||||||
|
### Step 1: Configure your Authorization Server
|
||||||
|
|
||||||
|
The first step is to configure the Authorization Server to correctly handle requests coming from Vikunja.
|
||||||
|
In general, this involves the following steps at a minimum:
|
||||||
|
|
||||||
|
- Create a confidential client and obtain the client ID and client secret
|
||||||
|
- Configure (whitelist) redirect URLs that can be used by Vikunja
|
||||||
|
- Make sure the required scopes (`openid profile email` are the default scopes used by Vikunja) are supported
|
||||||
|
- Optional: configure an additional scope for automatic team assignment, see below for details
|
||||||
|
|
||||||
|
More detailled instructions for various different identity providers can be [found here]({{< ref "openid-examples.md">}})
|
||||||
|
|
||||||
|
### Step 2: Configure Vikunja
|
||||||
|
|
||||||
|
Vikunja has to be configured to use the identity provider. The general configuration is structured as follows:
|
||||||
|
|
||||||
|
```yaml
|
||||||
|
auth:
|
||||||
|
openid:
|
||||||
|
enabled: true
|
||||||
|
redirecturl: https://vikunja.mydomain.com/auth/openid/ <---- slash at the end is important
|
||||||
|
providers:
|
||||||
|
- name: <provider-name>
|
||||||
|
authurl: <auth-url>
|
||||||
|
clientid: <vikunja client-id>
|
||||||
|
clientsecret: <vikunja client-secret>
|
||||||
|
scope: openid profile email
|
||||||
|
```
|
||||||
|
|
||||||
|
The values for `authurl` can be obtained from the Metadata of your provider, while `clientid` and `clientsecret` are obtained when configuring the client.
|
||||||
|
The scope usually doesn't need to be specified or changed, unless you want to configure the automatic team assignment.
|
||||||
|
|
||||||
|
Once you're confident that the external authentication works and you want to disable local accounts, this can be done by configuring:
|
||||||
|
|
||||||
|
```yaml
|
||||||
|
auth:
|
||||||
|
local:
|
||||||
|
enabled: false
|
||||||
|
```
|
||||||
|
|
||||||
## Automatically assign users to teams
|
## Automatically assign users to teams
|
||||||
|
|
||||||
Vikunja is capable of automatically adding users to a team based on a group defined in the oidc provider.
|
Vikunja is capable of automatically adding users to a team based on OIDC claims added by the identity provider.
|
||||||
If configured, Vikunja will sync teams, automatically create new ones and make sure the members are part of the configured teams.
|
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.
|
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.
|
To distinguish between teams created in Vikunja and teams generated automatically via oidc, generated teams have an `oidcID` assigned internally.
|
||||||
|
Within the UI, the teams created through OIDC get a `(OIDC)` suffix to make them distinguishable from locally created teams.
|
||||||
|
|
||||||
You need to make sure the OpenID provider offers a `vikunja_groups` key through your custom scope. This is the key, which is looked up by Vikunja to start the procedure.
|
On a high level, you need to make sure that the **ID token** issued by your identity provider contains a `vikunja_groups` claim, following the structure defined below.
|
||||||
|
It depends on the provider being used as well as the preferences of the administrator how this is achieved.
|
||||||
|
Typically you'd want to request an additional scope (e.g. `vikunja_scope`) which then triggers the identity provider to add the claim.
|
||||||
|
If the `vikunja_groups` is part of the **ID token**, Vikunja will start the procedure and import teams and team memberships.
|
||||||
|
|
||||||
Additionally, make sure to deliver an `oidcID` and a `name` attribute within the `vikunja_groups`. You can see how to set this up, if you continue reading.
|
The claim structure expexted by Vikunja is as follows:
|
||||||
|
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"vikunja_groups": [
|
||||||
|
{
|
||||||
|
"name": "team 1",
|
||||||
|
"oidcID": 33349
|
||||||
|
},
|
||||||
|
{
|
||||||
|
"name": "team 2",
|
||||||
|
"oidcID": 35933
|
||||||
|
}
|
||||||
|
]
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
For each team, you need to define a team `name` and an `oidcID`, where the `oidcID` can be any string with a length of less than 250 characters.
|
||||||
|
The `oidcID` is used to uniquely identify the team, so please make sure to keep this unique.
|
||||||
|
|
||||||
|
Below you'll find two example implementations for Authentik and Keycloak.
|
||||||
|
If you've successfully implemented this with another identity provider, please let us know and submit a PR to improve the docs.
|
||||||
|
|
||||||
### Setup in Authentik
|
### Setup in Authentik
|
||||||
|
|
||||||
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 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:
|
To use Authentik's group assignment feature, follow these steps:
|
||||||
|
|
||||||
|
@ -46,38 +136,21 @@ for group in request.user.ak_groups.all():
|
||||||
return groupsDict
|
return groupsDict
|
||||||
```
|
```
|
||||||
|
|
||||||
output example:
|
|
||||||
|
|
||||||
```
|
|
||||||
{
|
|
||||||
"vikunja_groups": [
|
|
||||||
{
|
|
||||||
"name": "team 1",
|
|
||||||
"oidcID": 33349
|
|
||||||
},
|
|
||||||
{
|
|
||||||
"name": "team 2",
|
|
||||||
"oidcID": 35933
|
|
||||||
}
|
|
||||||
]
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
5. In Authentik's menu on the left, go to Applications > Providers > Select the Vikunja provider. Then click on "Edit", on the bottom open "Advanced protocol settings", select the newly created property mapping under "Scopes". Save the provider.
|
5. In Authentik's menu on the left, go to Applications > Providers > Select the Vikunja provider. Then click on "Edit", on the bottom open "Advanced protocol settings", select the newly created property mapping under "Scopes". Save the provider.
|
||||||
|
|
||||||
Now when you log into Vikunja via Authentik it will show you a list of scopes you are claiming.
|
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.
|
You should see the description you entered on the OIDC provider's admin area.
|
||||||
|
|
||||||
Proceed to vikunja and open the teams page in the sidebar menu.
|
Proceed to vikunja and open the teams page in the sidebar menu.
|
||||||
You should see "(sso: *your_oidcID*)" written next to each team you were assigned through oidc.
|
You should see "(OIDC)" written next to each team you were assigned through OIDC.
|
||||||
|
|
||||||
## Setup in Keycloak
|
### Setup in Keycloak
|
||||||
|
|
||||||
The kind people from the Darmstadt Makerspace have written [a guide on how to create a mapper for Vikunja here](https://github.com/makerspace-darmstadt/keycloak-vikunja-mapper).
|
The kind people from Makerspace Darmstadt e.V. have written [a guide on how to create a mapper for Vikunja here](https://github.com/makerspace-darmstadt/keycloak-vikunja-mapper).
|
||||||
|
|
||||||
## Use cases
|
## Use cases
|
||||||
|
|
||||||
All examples assume one team called "Team 1" in your provider.
|
All examples assume one team called "Team 1" to be configured within your provider.
|
||||||
|
|
||||||
* *Token delivers team.name +team.oidcID and Vikunja team does not exist:* \
|
* *Token delivers team.name +team.oidcID and Vikunja team does not exist:* \
|
||||||
New team will be created called "Team 1" with attribute oidcID: "33929"
|
New team will be created called "Team 1" with attribute oidcID: "33929"
|
||||||
|
|
Loading…
Reference in New Issue
Block a user