From be54a361fd680e7bd63309db5338980badea86de Mon Sep 17 00:00:00 2001 From: waza-ari Date: Fri, 15 Mar 2024 13:50:46 +0000 Subject: [PATCH] docs: add details about supported and required OIDC claims (#2201) Again based on a [community question](https://community.vikunja.io/t/oidc-how-can-i-prevent-username-from-being-set-randomly-how-can-users-find-each-other/2138/2), it might make sense to add a few more details about the OIDC behaviour to the docs. Co-authored-by: Daniel Herrmann Reviewed-on: https://kolaente.dev/vikunja/vikunja/pulls/2201 Co-authored-by: waza-ari Co-committed-by: waza-ari --- docs/content/doc/setup/openid.md | 16 ++++++++++++++++ 1 file changed, 16 insertions(+) diff --git a/docs/content/doc/setup/openid.md b/docs/content/doc/setup/openid.md index 4b65b2c08..b4df2d34b 100644 --- a/docs/content/doc/setup/openid.md +++ b/docs/content/doc/setup/openid.md @@ -34,6 +34,22 @@ Claims in turn are assertions containing information about the token bearer, usu **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. +## Supported and required claims + +Vikunja only requires a few claims to be present in the ID token to successfully authenticate the user. +Additional claims can be added though to customize behaviour during user creation. + +The following table gives an overview about the claims supported by Vikunja. The scope column lists the scope that should request the claim according to the [OpenID Connect Standard](https://openid.net/specs/openid-connect-core-1_0.html#ScopeClaims). It omits the claims such as `sub` or `issuer` required by the `openid` scope, which must always be present. + +| Claim | Type | Scope | Comment | +| ------|------|-------|---------| +| email | required | email | Sets the email address of the user. Taken from the `userinfo` endpoint if not present in ID token. User creation fails if claim not present and userinfo lookup fails. | +| name | optional | profile | Sets the display name of the user. Taken from the `userinfo` endpoint if not present in ID token. | +| preferred_username | optional | profile | Sets the username of the user. Taken from the `userinfo` endpoint if not present in ID token. If this also doesn't contain the claim, use the `nickname` claim from `userinfo` instead. If that one is not available either, the username is auto-generated by Vikunja. | +| vikunja_groups | optional | N/A | Can be used to automatically assign users to teams. See below for a more detailed explanation about the expected format and implementation examples. | + +If one of the claims `email`, `name` or `preferred_username` is missing from the ID token, Vikunja will attempt to query the `userinfo` endpoint to obtain the information from there. + ## 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.