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/>
|
||||
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.
|
||||
**Note 2:** The frontend expects to be redirected after authentication by the third party
|
||||
to <frontend-url>/auth/openid/<auth key>. Please make sure to configure the redirect url in your 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
|
||||
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.
|
||||
If you want to use the desktop client with openid, make sure to allow redirects to `127.0.0.1`.
|
||||
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`.
|
||||
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>`
|
||||
|
|
|
@ -10,7 +10,7 @@ menu:
|
|||
|
||||
# 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.
|
||||
|
||||
{{< table_of_contents >}}
|
||||
|
@ -28,6 +28,7 @@ openid:
|
|||
authurl: https://login.mydomain.com
|
||||
clientid: <vikunja-id>
|
||||
clientsecret: <vikunja secret>
|
||||
scope: openid email profile
|
||||
```
|
||||
|
||||
Authelia config:
|
||||
|
@ -57,6 +58,7 @@ openid:
|
|||
authurl: https://accounts.google.com
|
||||
clientid: <google-oauth-client-id>
|
||||
clientsecret: <google-oauth-client-secret>
|
||||
scope: openid email profile
|
||||
```
|
||||
|
||||
Google config:
|
||||
|
@ -80,6 +82,7 @@ openid:
|
|||
logouturl: https://keycloak.mydomain.com/realms/<relam-name>/protocol/openid-connect/logout
|
||||
clientid: <vikunja-id>
|
||||
clientsecret: <vikunja secret>
|
||||
scope: openid email profile
|
||||
```
|
||||
Keycloak Config:
|
||||
- Navigate to the keycloak instance
|
||||
|
@ -109,6 +112,11 @@ auth:
|
|||
logouturl: "https://authentik.mydomain.com/application/o/vikunja/end-session/"
|
||||
clientid: "" # copy from Authetik
|
||||
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
|
||||
|
||||
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">}})
|
||||
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.
|
||||
|
||||
{{< 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
|
||||
|
||||
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.
|
||||
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.
|
||||
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
|
||||
|
||||
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:
|
||||
|
||||
|
@ -46,38 +136,21 @@ for group in request.user.ak_groups.all():
|
|||
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.
|
||||
|
||||
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.
|
||||
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
|
||||
|
||||
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:* \
|
||||
New team will be created called "Team 1" with attribute oidcID: "33929"
|
||||
|
|
Loading…
Reference in New Issue